메인 콘텐츠로 건너뛰기

SDK 개요

EKB SDK(Software Development Kit)는 EKB의 강력한 기능을 애플리케이션에 통합하기 위한 포괄적인 TypeScript/JavaScript 라이브러리를 제공합니다. 채팅 인터페이스를 구축하고, 구조화된 데이터를 관리하고, 음성 대화를 활성화하며, AI 에이전트를 프로그래밍 방식으로 활용하세요. 이 기사에서는 EKB SDK의 개요와 사용 사례 예시 및 모범 사례를 제공합니다.

EKB SDK란?​

EKB SDK는 EKB의 핵심 기능에 대한 프로그래밍 방식 접근을 제공하는 TypeScript 라이브러리입니다:

  • ChatSDK: 채팅 관리, 메시지 처리 및 스트리밍 응답을 포함한 대화형 AI 인터페이스 구축.
  • SmartTablesSDK: 고급 쿼리링, 필터링 및 AI 기반 데이터 처리로 구조화된 데이터 테이블 관리.
  • VoiceSDK: 자동 채팅 통합과 React hooks를 통한 음성 대화 활성화.

설치​

npm install @odin-ai-staging/sdk

또는 yarn:

yarn add @odin-ai-staging/sdk

빠른 시작​

기본 설정​

import { ChatSDK } from '@odin-ai-staging/sdk';

// SDK 초기화
const chatSDK = new ChatSDK({
  baseUrl: 'https://your-api-endpoint.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// 채팅을 만들고 메시지를 보냄
const chat = await chatSDK.createChat('My First Chat');
const response = await chatSDK.sendMessage('Hello!', {
  chatId: chat.chat_id
});

console.log('AI Response:', response.message);

인증​

SDK는 두 가지 인증 방법을 지원합니다:

1. API 키 인증 (서버 측 권장)​

서버 간 통신 및 외부 통합을 위해 API 키를 사용합니다:

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

API 키 가져오기:

  1. EKB 대시보드에서 내 계정 > API 키로 이동
  2. 새 API 키 쌍 만들기
  3. API 키와 API 시크릿 복사
  4. 안전하게 저장(환경 변수 사용, 버전 관리에 커밋하지 마세요)

2. 액세스 토큰 인증 (웹 앱용)​

기존 사용자 세션이 있는 클라이언트 측 애플리케이션을 위해 액세스 토큰을 사용합니다:

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'your-project-id',
  accessToken: 'user-access-token' // 인증 시스템에서 가져옴
});

SDK 컴포넌트​

Chat SDK​

포괄적인 채팅 관리를 사용하여 대화형 AI 인터페이스를 구축합니다.

주요 기능:

  • 채팅 만들기, 나열 및 관리
  • 스트리밍 지원이 포함된 메시지 보내기
  • 지식 기반 통합
  • 파일 업로드 (이미지, 문서)
  • 사용자 피드백 (좋아요/싫어요)
  • 사용자 지정 에이전트 및 모델

자세히 알아보기: Chat SDK 문서

Smart Tables SDK​

고급 쿼리링 및 AI 기반 처리로 구조화된 데이터를 관리합니다.

주요 기능:

  • 데이터 테이블 만들기 및 관리
  • 고급 필터링 및 정렬
  • 데이터 가져오기/내보내기 (CSV, Excel)
  • AI 기반 열 계산
  • 사용자 지정 보기 및 열 관리
  • 페이지네이션 및 검색

자세히 알아보기: Smart Tables SDK 문서

Voice SDK​

자동 채팅 통합과 함께 음성 대화를 활성화합니다.

주요 기능:

  • 실시간 음성 대화
  • 자동 전사
  • 쉬운 통합을 위한 React hooks
  • 오디오 시각화
  • 세션 관리
  • 채팅 통합

자세히 알아보기: Voice SDK 문서

일반적인 사용 사례​

1. 고객 지원 챗봇​

import { ChatSDK } from '@odin-ai-staging/sdk';

const supportBot = new ChatSDK({
  baseUrl: process.env.API_BASE_URL,
  projectId: process.env.PROJECT_ID,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
});

// 지원 채팅 세션 만들기
const chat = await supportBot.createChat('Support Request');

// 고객 메시지 보내기
const response = await supportBot.sendMessage(
  'I need help with my account',
  {
    chatId: chat.chat_id,
    agentType: 'chat_agent',
    agentId: 'support-agent-id'
  }
);

2. 데이터 관리 애플리케이션​

import { SmartTablesSDK } from '@odin-ai-staging/sdk';

const dataManager = new SmartTablesSDK({
  baseUrl: process.env.API_BASE_URL,
  projectId: process.env.PROJECT_ID,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
});

// 고객 데이터를 위한 테이블 만들기
const table = await dataManager.createTable(
  'Customer Database',
  'Manage customer information'
);

// 열 추가
await dataManager.addColumn(table.id, {
  name: 'email',
  type: 'email',
  description: 'Customer email',
  notNull: true,
  unique: true
});

// 데이터 쿼리
const results = await dataManager.queryTable(table.id, {
  filters: [{ column: 'email', operator: 'contains', value: '@example.com' }],
  pagination: { limit: 50, page: 1 }
});

3. 음성 활성화 애플리케이션​

import { VoiceSDK } from '@odin-ai-staging/sdk';

const voiceApp = new VoiceSDK({
  baseUrl: process.env.API_BASE_URL,
  projectId: process.env.PROJECT_ID,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  agentId: 'voice-agent-id'
});

// 음성 대화 시작
const sessionId = await voiceApp.startVoiceConversation({
  saveToChat: true,
  callbacks: {
    onConnect: () => console.log('Voice connected'),
    onMessage: (message) => console.log('Message:', message),
    onTranscription: (text, isFinal) => {
      if (isFinal) console.log('User said:', text);
    }
  }
});

환경 변수​

프로덕션 애플리케이션에서는 항상 환경 변수를 사용합니다:

# .env 파일
API_BASE_URL=https://api.getodin.ai
PROJECT_ID=your-project-id
API_KEY=your-api-key
API_SECRET=your-api-secret
// 코드에서
const chatSDK = new ChatSDK({
  baseUrl: process.env.API_BASE_URL!,
  projectId: process.env.PROJECT_ID!,
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!
});

오류 처리​

모든 SDK 메서드는 캐치하고 처리해야 하는 오류를 발생시킵니다:

try {
  const chat = await chatSDK.createChat('My Chat');
  // 성공 처리
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    // 특정 오류 코드 처리
    if (error.status === 401) {
      // 인증 실패
    } else if (error.status === 403) {
      // 접근 거부됨
    } else if (error.status === 404) {
      // 리소스를 찾을 수 없음
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript 지원​

SDK는 TypeScript로 작성되었으며 전체 유형 정의를 제공합니다:

import { ChatSDK, Chat, Message, SendMessageOptions } from '@odin-ai-staging/sdk';

const chatSDK = new ChatSDK(config);

// 모든 메서드는 완전한 유형을 가집니다
const chat: Chat = await chatSDK.createChat('My Chat');
const options: SendMessageOptions = {
  chatId: chat.id,
  agentType: 'chat_agent'
};
const response: Message = await chatSDK.sendMessage('Hello', options);

React 통합​

SDK에는 쉬운 통합을 위한 React hooks가 포함되어 있습니다:

import { useVoiceConversation } from '@odin-ai-staging/sdk';

function VoiceChat() {
  const { status, startSession, endSession } = useVoiceConversation({
    sdkConfig: {
      baseUrl: process.env.REACT_APP_API_BASE_URL,
      projectId: process.env.REACT_APP_PROJECT_ID,
      agentId: process.env.REACT_APP_AGENT_ID
    },
    callbacks: {
      onConnect: () => console.log('Connected!'),
      onMessage: (message) => console.log('Message:', message)
    }
  });

  return (
    <div>
      <button onClick={() => startSession()}>Start Voice Chat</button>
      <button onClick={() => endSession()}>End Chat</button>
      <div>Status: {status}</div>
    </div>
  );
}

모범 사례​

1. 환경 변수 사용​

코드에 API 키나 시크릿을 하드코딩하지 마세요. 항상 환경 변수를 사용합니다.

2. 우아한 오류 처리​

모든 SDK 호출을 try-catch 블록으로 감싸고 사용자에게 의미 있는 오류 메시지를 제공합니다.

3. SDK 인스턴스 재사용​

SDK 인스턴스를 한 번 만들고 재사용하세요. 각 작업에 대해 새 인스턴스를 만드는 대신 사용합니다.

// 좋음: 한 번 만들고 재사용
const chatSDK = new ChatSDK(config);

async function sendMessage(text: string) {
  return await chatSDK.sendMessage(text, options);
}

// 나쁨: 새 인스턴스 만들기
async function sendMessage(text: string) {
  const chatSDK = new ChatSDK(config); // 하지 마세요
  return await chatSDK.sendMessage(text, options);
}

4. 더 나은 UX를 위한 스트리밍 사용​

채팅 애플리케이션의 경우 실시간 피드백을 위해 스트리밍 응답을 사용합니다:

await chatSDK.sendMessageStream('Hello', {
  chatId: chat.id,
  onChunk: (chunk) => {
    // 실시간으로 UI 업데이트
    updateChatUI(chunk);
  },
  onComplete: (message) => {
    // 완료 처리
    saveMessage(message);
  }
});

5. 페이지네이션 구현​

채팅을 나열하거나 테이블을 쿼리할 때 항상 페이지네이션을 구현합니다:

// 페이지네이션을 사용하여 채팅 나열
let cursor: number | undefined;
let hasMore = true;

while (hasMore) {
  const result = await chatSDK.listChats(cursor, 30);
  processChats(result.chats);
  hasMore = result.has_more;
  cursor = result.next_cursor;
}

도움말​

  • 문서화: 각 SDK 컴포넌트에 대한 자세한 문서화를 탐색합니다.
  • 지원: 기술 지원을 위해 지원팀에 이메일을 보냅니다.
  • 예시: 완전한 작동 예시를 위해 SDK 리포지토리를 확인하세요.