@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

``bash
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.

`ts
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

$3

`ts
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

---

$3

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

`ts
{
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.

---

$3

Cada tool possui:

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

`ts
{
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.

---

$3

`ts
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

`ts
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