> ## 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 (ソフトウェア開発キット) は、EKB の強力な機能をアプリケーションに統合するための包括的な TypeScript/JavaScript ライブラリを提供します。チャット インターフェイスを構築し、構造化データを管理し、音声会話を可能にし、AI エージェントをプログラムで活用します。この記事では、EKB SDK の概要をいくつかの使用例とベスト プラクティスとともに説明します。

## EKB SDK とは何ですか?

EKB SDK は、EKB のコア機能へのプログラムによるアクセスを提供する TypeScript ライブラリです。

* **ChatSDK**: チャット管理、メッセージ処理、ストリーミング応答を備えた会話型 AI インターフェイスを構築します。
* **SmartTablesSDK**: 高度なクエリ、フィルタリング、AI を活用したデータ処理を使用して構造化データ テーブルを管理します。
* **VoiceSDK**: 自動チャット統合と React フックを使用して音声会話を可能にします。

## インストール

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

または糸を使って:

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

## クイックスタート

### 基本セットアップ

```typescript theme={null}
import { ChatSDK } from '@odin-ai-staging/sdk';

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

// Create a chat and send a message
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 は 2 つの認証方法をサポートしています。

### 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. アクセストークン認証 (Web アプリの場合)

既存のユーザー セッションでクライアント側アプリケーションのアクセス トークンを使用します。

```typescript theme={null}
const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'your-project-id',
  accessToken: 'user-access-token' // From your authentication system
});
```

## SDK コンポーネント

### チャット SDK

包括的なチャット管理を備えた会話型 AI インターフェイスを構築します。

**主な機能:**

* チャットの作成、リスト、管理
* ストリーミングサポートによるメッセージの送信
* ナレッジベースの統合
* ファイルのアップロード (画像、ドキュメント)
* ユーザーからのフィードバック (高評価/低評価)
* カスタムエージェントとモデル

**詳細:** [Chat SDK Documentation](./chat)

### スマート テーブル SDK

高度なクエリと AI を活用した処理で構造化データを管理します。

**主な機能:**

* データテーブルの作成と管理
* 高度なフィルタリングと並べ替え
* データのインポート/エクスポート（CSV、Excel）
* AI を活用した列計算
* カスタムビューと列管理
* ページネーションと検索

**詳細:** [Smart Tables SDK Documentation](./smart-tables)

### 音声 SDK

自動チャット統合により音声会話を可能にします。

**主な機能:**

* リアルタイムの音声会話
* 自動文字起こし
* 統合を容易にする React フック
* オーディオの視覚化
* セッション管理
* チャットの統合

**詳細:** [Voice SDK Documentation](./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
});

// Create a support chat session
const chat = await supportBot.createChat('Support Request');

// Send customer message
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
});

// Create a table for customer data
const table = await dataManager.createTable(
  'Customer Database',
  'Manage customer information'
);

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

// Query data
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'
});

// Start a voice conversation
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 file
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}
// In your code
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');
  // Handle success
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    // Handle specific error codes
    if (error.status === 401) {
      // Authentication failed
    } else if (error.status === 403) {
      // Permission denied
    } else if (error.status === 404) {
      // Resource not found
    }
  } 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);

// All methods are fully typed
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 フックが含まれています。

```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}
// Good: Create once, reuse
const chatSDK = new ChatSDK(config);

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

// Bad: Creating new instances
async function sendMessage(text: string) {
  const chatSDK = new ChatSDK(config); // Don't do this
  return await chatSDK.sendMessage(text, options);
}
```

### 4. **UX を向上させるためにストリーミングを使用する**

チャット アプリケーションの場合は、ストリーミング応答を使用してリアルタイムのフィードバックを取得します。

```typescript theme={null}
await chatSDK.sendMessageStream('Hello', {
  chatId: chat.id,
  onChunk: (chunk) => {
    // Update UI in real-time
    updateChatUI(chunk);
  },
  onComplete: (message) => {
    // Handle completion
    saveMessage(message);
  }
});
```

### 5. **ページネーションを実装する**

チャットをリストしたり、テーブルをクエリしたりするときは、常にページネーションを実装してください。

```typescript theme={null}
// List chats with pagination
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](support@automationanywhere.com) まで電子メールを送信してください。
* **例**: 完全な動作例については、SDK リポジトリを確認してください。