Aller au contenu principal

Aperçu du SDK

Le SDK EKB (Software Development Kit) fournit une bibliothèque TypeScript/JavaScript complète pour intégrer les puissantes fonctionnalités d'EKB dans vos applications. Créez des interfaces de chat, gérez des données structurées, activez les conversations vocales et exploitez les agents IA par programmation. Cet article vous donnera un aperçu du SDK EKB avec quelques exemples de cas d'usage et les meilleures pratiques.

Qu'est-ce que le SDK EKB ?​

Le SDK EKB est une bibliothèque TypeScript qui fournit un accès programmatique aux fonctionnalités principales d'EKB :

  • ChatSDK : Créez des interfaces conversationnelles avec gestion des chats, gestion des messages et réponses en streaming.
  • SmartTablesSDK : Gérez les tableaux de données structurées avec requêtes avancées, filtrage et traitement des données alimenté par l'IA.
  • VoiceSDK : Activez les conversations vocales avec intégration automatique des chats et hooks React.

Installation​

npm install @odin-ai-staging/sdk

Ou avec yarn :

yarn add @odin-ai-staging/sdk

Démarrage rapide​

Configuration de base​

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

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

// Créer un chat et envoyer un 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);

Authentification​

Le SDK supporte deux méthodes d'authentification :

1. Authentification par clé API (recommandée pour le serveur)​

Utilisez les clés API pour la communication serveur à serveur et les intégrations externes :

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

Obtenir les clés API :

  1. Accédez à Mon compte > Clés API dans votre tableau de bord EKB
  2. Créez une nouvelle paire de clés API
  3. Copiez la clé API et le secret API
  4. Stockez-les en toute sécurité (utilisez les variables d'environnement, ne les validez jamais sur le contrôle de version)

2. Authentification par jeton d'accès (pour les applications Web)​

Utilisez les jetons d'accès pour les applications côté client avec des sessions utilisateur existantes :

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

Composants du SDK​

Chat SDK​

Créez des interfaces conversationnelles avec gestion complète des chats.

Fonctionnalités principales :

  • Créer, lister et gérer les chats
  • Envoyer des messages avec support du streaming
  • Intégration de la base de connaissances
  • Téléchargements de fichiers (images, documents)
  • Retours utilisateurs (pouces vers le haut/bas)
  • Agents et modèles personnalisés

En savoir plus : Documentation du Chat SDK

Smart Tables SDK​

Gérez les données structurées avec requêtes avancées et traitement alimenté par l'IA.

Fonctionnalités principales :

  • Créer et gérer les tableaux de données
  • Filtrage et tri avancés
  • Import/export de données (CSV, Excel)
  • Calcul de colonnes alimenté par l'IA
  • Vues personnalisées et gestion des colonnes
  • Pagination et recherche

En savoir plus : Documentation du Smart Tables SDK

Voice SDK​

Activez les conversations vocales avec intégration automatique des chats.

Fonctionnalités principales :

  • Conversations vocales en temps réel
  • Transcription automatique
  • Hooks React pour une intégration facile
  • Visualisation audio
  • Gestion des sessions
  • Intégration des chats

En savoir plus : Documentation du Voice SDK

Cas d'usage courants​

1. Chatbot d'assistance client​

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

// Créer une session de chat d'assistance
const chat = await supportBot.createChat('Support Request');

// Envoyer le message du client
const response = await supportBot.sendMessage(
  'I need help with my account',
  {
    chatId: chat.chat_id,
    agentType: 'chat_agent',
    agentId: 'support-agent-id'
  }
);

2. Application de gestion de données​

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

// Créer un tableau pour les données clients
const table = await dataManager.createTable(
  'Customer Database',
  'Manage customer information'
);

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

// Interroger les données
const results = await dataManager.queryTable(table.id, {
  filters: [{ column: 'email', operator: 'contains', value: '@example.com' }],
  pagination: { limit: 50, page: 1 }
});

3. Application activée par la voix​

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

// Démarrer une conversation vocale
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);
    }
  }
});

Variables d'environnement​

Pour les applications de production, utilisez toujours les variables d'environnement :

# .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!
});

Gestion des erreurs​

Toutes les méthodes du SDK lèvent des erreurs qui doivent être capturées et gérées :

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

Support de TypeScript​

Le SDK est écrit en TypeScript et fournit des définitions de type complètes :

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

Intégration React​

Le SDK inclut des hooks React pour une intégration facile :

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

Meilleures pratiques​

1. Utilisez les variables d'environnement​

Ne codez jamais en dur vos clés API ou secrets dans votre code. Utilisez toujours les variables d'environnement.

2. Gérez les erreurs avec grâce​

Enveloppez toujours les appels du SDK dans des blocs try-catch et fournissez des messages d'erreur significatifs aux utilisateurs.

3. Réutilisez les instances du SDK​

Créez les instances du SDK une seule fois et réutilisez-les plutôt que de créer de nouvelles instances pour chaque opération.

// 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. Utilisez le streaming pour une meilleure UX​

Pour les applications de chat, utilisez les réponses en streaming pour un retour en temps réel :

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

5. Implémentez la pagination​

Lors de la liste des chats ou de l'interrogation des tableaux, implémentez toujours la pagination :

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

Obtenir de l'aide​

  • Documentation : Parcourez la documentation détaillée pour chaque composant du SDK.
  • Support : Envoyez un email à Support pour l'assistance technique.
  • Exemples : Consultez le dépôt du SDK pour les exemples complets de travail.