@botly-ai/sdk

🔗 Site oficial: https://botly.com.br

SDK TypeScript para criar assistentes de IA com ferramentas (tools) de forma simples, tipada e extensível — ideal para backends Node.js e aplicações NestJS.

O @botly-ai/sdk abstrai a comunicação com provedores de LLM (ex: OpenAI) e facilita:

• Gerenciamento de mensagens
• Execução de tools com callbacks
• Tipagem forte em TypeScript
• Fluxos com segunda resposta automática do modelo

Instalação

pnpm add @botly-ai/sdk
# ou
npm install @botly-ai/sdk
# ou
yarn add @botly-ai/sdk

Uso básico (Node.js / TypeScript)

Exemplo de uso simples em um arquivo TypeScript, sem dependência de frameworks.

import { Botly } from "@botly-ai/sdk";

const messages: { role: 'user' | 'assistant'; content: string }[] = [];

async function run() {
    const client = new Botly({
        apiKey: process.env.OPENAI_API_KEY ?? '',
        provider: 'openai',
        model: 'gpt-4o-mini',
        temperature: 0.7,
        systemPrompt: 'You are a helpful assistant that can answer questions and help with tasks.',
    });

    messages.push({ role: 'user', content: 'How many users do we have?' });

    const response = await client.response({
        input: [...messages],
        secondResponseCallback: true,
        tools: [
            {
                name: 'get_user_count',
                description: 'Get the number of users in the database',
                fields: [
                    {
                        name: 'user_type',
                        type: 'string',
                        description: 'The type of user to get the count of',
                    },
                ],
                async callback({ user_type }: { user_type: string }) {
                    console.log('User type:', user_type);

                    return {
                        count: 1000,
                    };
                },
            },
            {
                name: 'create_new_user',
                description: 'Create a new user in the database',
                fields: [
                    { name: 'name', type: 'string' },
                    { name: 'email', type: 'string' },
                    { name: 'phone', type: 'string' },
                ],
                async callback({ name, email, phone }: { name: string; email: string; phone: string }) {
                    console.log(name, email, phone);

                    return {
                        message: 'User created successfully',
                    };
                },
            },
        ],
    });

    messages.push({ role: 'assistant', content: response.output_text ?? '' });

    console.log(response.output_text);
}

run();

Conceitos principais

Botly Client

const client = new Botly({
  apiKey: process.env.OPENAI_API_KEY!,
  provider: 'openai',
  model: 'gpt-4o-mini',
  temperature: 0.7,
  systemPrompt: 'You are a helpful assistant',
});

Opções principais:

• apiKey: chave do provedor
• provider: provedor de LLM (openai, etc.)
• model: modelo utilizado
• temperature: nível de criatividade
• systemPrompt: prompt base do agente

Messages (input)

O histórico de mensagens segue o padrão:

{
  name: 'get_user_count',
  description: 'Get the number of users stored in the system',
  fields: [
    {
      name: 'user_type',
      type: 'string',
      description: 'The type of user to get the count of (e.g. admin, customer, guest)',
    }
  ],
  async callback(args) {
    // args is already a parsed JSON object
    // matching the schema defined in `fields`
    const { user_type } = args;

    return { count: 1000 };
  }
}

Você controla totalmente o estado da conversa.

Tools (Function Calling)

Cada tool possui:

• name
• description
• fields (schema de entrada)
• callback assíncrono

{
  name: 'get_user_count',
  fields: [
    { name: 'user_type', type: 'string' }
  ],
  async callback(args) {
    return { count: 1000 };
  }
}

O modelo decide quando chamar a tool, e o @botly-ai/sdk executa o callback automaticamente.

secondResponseCallback

secondResponseCallback: true

Quando ativado:

1. O modelo chama a tool
2. O callback é executado
3. O resultado volta para o modelo
4. O modelo gera uma segunda resposta final

Ideal para fluxos naturais e conversacionais.

Retorno

const response = await client.response(...);

response.output_text;

Você também pode acessar o objeto completo (Output) se precisar de mais controle.

Requisitos

• Node.js >= 18
• TypeScript recomendado

Licença

MIT