Visão Geral do SDK - Automation Anywhere EKB Docs

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:

Navegue até Minha Conta > Chaves de API no seu painel do EKB
Crie um novo par de chaves de API
Copie a Chave de API e o Secret da API
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.

​O que é o SDK do EKB?

​Instalação

​Início Rápido

​Configuração Básica

​Autenticação

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

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

​Componentes do SDK

​Chat SDK

​Smart Tables SDK

​Voice SDK

​Casos de Uso Comuns

​1. Chatbot de Suporte ao Cliente

​2. Aplicativo de Gerenciamento de Dados

​3. Aplicativo com Suporte a Voz

​Variáveis de Ambiente

​Tratamento de Erros

​Suporte a TypeScript

​Integração com React

​Práticas Recomendadas

​1. Use Variáveis de Ambiente

​2. Trate Erros Adequadamente

​3. Reutilize Instâncias do SDK

​4. Use Streaming para Melhor Experiência

​5. Implemente Paginação

​Obter Ajuda