API

Ferramentas personalizadas

Deixe a IA chamar a sua API no meio de uma conversa

Visão geral

Uma ferramenta personalizada é um endpoint seu que o agente pode chamar enquanto conversa com um cliente: consultar um crédito pelo número de documento, verificar o estoque, abrir um chamado. Você descreve quando ela se aplica e quais parâmetros precisa; a IA decide quando chamá-la, preenche os parâmetros com o que o cliente disse e responde com o que a sua API retornou. Até 15 ferramentas por agente.

Definição

Cada ferramenta é uma entrada com estes campos:

`name`	Nome técnico com que a IA a chama: letras, números e sublinhado (consultar_credito).
`description`	Quando usá-la e o que ela retorna. É o que a IA lê para decidir; escreva como instrução («Consulta um crédito pelo número de documento; retorna saldo e parcelas»).
`parameters`	Lista de {name, type (string \| number \| boolean \| enum), description, required, enum_values}. A IA os preenche com o que o cliente disse.
`method + endpoint`	GET, POST, PUT ou DELETE e a URL completa.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (nome e valor de header que você escolhe) ou BASIC (usuário e senha).
`headers`	Headers extras enviados em cada chamada.
`body_template`	Modelo JSON opcional com {{param}}. Sem ele, POST/PUT enviam os parâmetros como objeto JSON.
`response_path`	Caminho com pontos opcional (data.results) até a parte da resposta que a IA deve ler.

Como a chamada é feita

GET e DELETE adicionam os parâmetros à URL como query string. POST e PUT os enviam como body JSON, ou o body_template já preenchido. Os headers de auth e os extras vão em cada chamada. Responda 2xx com JSON: a IA recebe o body (ou a parte de response_path) como texto e o usa para responder. Um código diferente de 2xx chega à IA como «API returned <status>» e ela diz ao cliente que não conseguiu consultar; não há novas tentativas automáticas.

Como criar uma

Canvas (newui.tbit.app): pergunte «quais ferramentas personalizadas eu tenho?» → a lista tem «Nova ferramenta…»; cada linha abre a ferramenta com Editar. Um formulário pede tudo o que está acima; os segredos que você deixar vazios ao editar são mantidos.
MCP (Claude, ChatGPT…): list_custom_tools para lê-las, manage_custom_tool com action=create | update | delete. A mudança é proposta e você a confirma.
App da plataforma: Integrações → API personalizada.

Exemplo: criar pelo MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

O que o seu endpoint recebe

Com o exemplo acima, quando um cliente pergunta pelo crédito dele, a IA chama:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Boas práticas

Escreva a descrição para a IA, não para um desenvolvedor: quando usá-la e o que ela retorna.
Marque como obrigatório só o que a IA precisa pedir ao cliente; para o resto, defina um valor padrão do seu lado.
Mantenha os GET idempotentes: a IA pode chamar a mesma ferramenta duas vezes em uma conversa se a primeira tentativa falhar.
Retorne um JSON pequeno e plano. Use response_path se a sua API envolve os resultados.