Pular para o conteúdo principal

Visão Geral do SDK

O SDK do EKB (Software Development Kit) fornece uma biblioteca completa em TypeScript/JavaScript para integrar os poderosos recursos do EKB aos seus aplicativos. Construa interfaces de chat, gerencie dados estruturados, habilite conversas por voz e aproveite agentes de IA programaticamente. Este artigo fornecerá uma visão geral do SDK do EKB com exemplos de uso e práticas recomendadas.

O que é o SDK do EKB?​

O SDK do EKB é uma biblioteca TypeScript que fornece acesso programático aos recursos principais do EKB:

  • ChatSDK: Construa interfaces de IA conversacional com gerenciamento de chat, tratamento de mensagens e respostas por streaming.
  • SmartTablesSDK: Gerencie tabelas de dados estruturados com consultas avançadas, filtragem e processamento de dados por IA.
  • VoiceSDK: Habilite conversas por voz com integração automática de chat e hooks do React.

Instalação​

npm install @odin-ai-staging/sdk

Ou com yarn:

yarn add @odin-ai-staging/sdk

Início Rápido​

Configuração Básica​

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

Autenticação​

O SDK suporta dois métodos de autenticação:

1. Autenticação por Chave de API (Recomendado para Lado do Servidor)​

Use chaves de API para comunicação entre servidores e integrações externas:

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

Obtendo Chaves de API:

  1. Navegue até Minha Conta > Chaves de API no seu painel do EKB
  2. Crie um novo par de chaves de API
  3. Copie a Chave de API e o Secret da API
  4. Armazene-as de forma segura (use variáveis de ambiente, nunca faça commit para controle de versão)

2. Autenticação por Token de Acesso (Para Aplicativos Web)​

Use tokens de acesso para aplicações do lado do cliente com sessões de usuário existentes:

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

Componentes do SDK​

Chat SDK​

Construa interfaces de IA conversacional com gerenciamento abrangente de chat.

Principais Recursos:

  • Criar, listar e gerenciar chats
  • Enviar mensagens com suporte a streaming
  • Integração com base de conhecimento
  • Upload de arquivos (imagens, documentos)
  • Feedback do usuário (curtir/não curtir)
  • Agentes e modelos personalizados

Saiba Mais: Documentação do Chat SDK

Smart Tables SDK​

Gerencie dados estruturados com consultas avançadas e processamento por IA.

Principais Recursos:

  • Criar e gerenciar tabelas de dados
  • Filtragem e ordenação avançadas
  • Importação/exportação de dados (CSV, Excel)
  • Cálculo de colunas por IA
  • Visualizações e gerenciamento de colunas personalizadas
  • Paginação e busca

Saiba Mais: Documentação do Smart Tables SDK

Voice SDK​

Habilite conversas por voz com integração automática de chat.

Principais Recursos:

  • Conversas por voz em tempo real
  • Transcrição automática
  • Hooks do React para fácil integração
  • Visualização de áudio
  • Gerenciamento de sessões
  • Integração com chat

Saiba Mais: Documentação do Voice SDK

Casos de Uso Comuns​

1. Chatbot de Suporte ao Cliente​

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. Aplicativo de Gerenciamento de Dados​

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. Aplicativo com Suporte a Voz​

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

Variáveis de Ambiente​

Para aplicações em produção, sempre use variáveis de ambiente:

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

Tratamento de Erros​

Todos os métodos do SDK lançam erros que devem ser capturados e tratados:

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

Suporte a TypeScript​

O SDK é escrito em TypeScript e fornece definições de tipos completas:

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

Integração com React​

O SDK inclui hooks do React para fácil integração:

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

Práticas Recomendadas​

1. Use Variáveis de Ambiente​

Nunca codifique chaves de API ou secrets diretamente no código. Sempre use variáveis de ambiente.

2. Trate Erros Adequadamente​

Sempre envolva chamadas ao SDK em blocos try-catch e forneça mensagens de erro significativas aos usuários.

3. Reutilize Instâncias do SDK​

Crie instâncias do SDK uma vez e reutilize-as, em vez de criar novas instâncias para cada operação.

// 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. Use Streaming para Melhor Experiência​

Para aplicativos de chat, use respostas por streaming para feedback em tempo real:

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

5. Implemente Paginação​

Ao listar chats ou consultar tabelas, sempre implemente paginação:

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

Obter Ajuda​

  • Documentação: Navegue pela documentação detalhada de cada componente do SDK.
  • Suporte: Envie um e-mail para Suporte para assistência técnica.
  • Exemplos: Confira o repositório do SDK para exemplos completos e funcionais.