> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 개요

> TypeScript SDK를 사용하여 EKB를 애플리케이션에 통합

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

## EKB SDK란?

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

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

## 설치

```bash theme={null}
npm install @odin-ai-staging/sdk
```

또는 yarn:

```bash theme={null}
yarn add @odin-ai-staging/sdk
```

## 빠른 시작

### 기본 설정

```typescript theme={null}
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 키를 사용합니다:

```typescript theme={null}
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. 액세스 토큰 인증 (웹 앱용)

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

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

## SDK 컴포넌트

### Chat SDK

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

**주요 기능:**

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

**자세히 알아보기:** [Chat SDK 문서](./chat)

### Smart Tables SDK

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

**주요 기능:**

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

**자세히 알아보기:** [Smart Tables SDK 문서](./smart-tables)

### Voice SDK

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

**주요 기능:**

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

**자세히 알아보기:** [Voice SDK 문서](./voice)

## 일반적인 사용 사례

### 1. 고객 지원 챗봇

```typescript theme={null}
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. 데이터 관리 애플리케이션

```typescript theme={null}
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. 음성 활성화 애플리케이션

```typescript theme={null}
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);
    }
  }
});
```

## 환경 변수

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

```bash theme={null}
# .env 파일
API_BASE_URL=https://api.getodin.ai
PROJECT_ID=your-project-id
API_KEY=your-api-key
API_SECRET=your-api-secret
```

```typescript theme={null}
// 코드에서
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 메서드는 캐치하고 처리해야 하는 오류를 발생시킵니다:

```typescript theme={null}
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로 작성되었으며 전체 유형 정의를 제공합니다:

```typescript theme={null}
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가 포함되어 있습니다:

```tsx theme={null}
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 인스턴스를 한 번 만들고 재사용하세요. 각 작업에 대해 새 인스턴스를 만드는 대신 사용합니다.

```typescript theme={null}
// 좋음: 한 번 만들고 재사용
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를 위한 스트리밍 사용**

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

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

### 5. **페이지네이션 구현**

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

```typescript theme={null}
// 페이지네이션을 사용하여 채팅 나열
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 컴포넌트에 대한 자세한 문서화를 탐색합니다.
* **지원**: 기술 지원을 위해 [지원팀](support@automationanywhere.com)에 이메일을 보냅니다.
* **예시**: 완전한 작동 예시를 위해 SDK 리포지토리를 확인하세요.