メインコンテンツへスキップ

SDKの概要

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

EKB SDK とは何ですか?​

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

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

インストール​

npm install @odin-ai-staging/sdk

または糸を使って:

yarn add @odin-ai-staging/sdk

クイックスタート​

基本セットアップ​

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 キーを使用します。

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 アプリの場合)​

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

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

スマート テーブル SDK​

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

主な機能:

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

詳細: Smart Tables SDK Documentation

音声 SDK​

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

主な機能:

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

詳細: Voice SDK Documentation

一般的な使用例​

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
});

// 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. データ管理アプリケーション​

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. 音声対応アプリケーション​

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);
    }
  }
});

環境変数​

運用アプリケーションの場合は、常に環境変数を使用してください。

# .env file
API_BASE_URL=https://api.getodin.ai
PROJECT_ID=your-project-id
API_KEY=your-api-key
API_SECRET=your-api-secret
// 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 メソッドは、捕捉して処理する必要があるエラーをスローします。

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 で書かれており、完全な型定義を提供します。

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 フックが含まれています。

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 インスタンスを一度作成して再利用します。

// 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 を向上させるためにストリーミングを使用する​

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

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

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

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

// 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 まで電子メールを送信してください。
  • 例: 完全な動作例については、SDK リポジトリを確認してください。