> ## 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.

# Visão Geral do SDK

> Integre o EKB aos Seus Aplicativos Usando Nosso SDK TypeScript

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

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

Ou com yarn:

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

## Início Rápido

### Configuração Básica

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

## 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:

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

```typescript theme={null}
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](./chat)

### 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](./smart-tables)

### 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](./voice)

## Casos de Uso Comuns

### 1. Chatbot de Suporte ao Cliente

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

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

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

## Variáveis de Ambiente

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

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

## Tratamento de Erros

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

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

## Suporte a TypeScript

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

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

## Integração com React

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

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

## 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.

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

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

```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. **Implemente Paginação**

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

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

## Obter Ajuda

* **Documentação:** Navegue pela documentação detalhada de cada componente do SDK.
* **Suporte:** Envie um e-mail para [Suporte](support@automationanywhere.com) para assistência técnica.
* **Exemplos:** Confira o repositório do SDK para exemplos completos e funcionais.