Ferramentas customizadas: integrar APIs externas

As ferramentas customizadas (Custom Tools) são o mecanismo pelo qual o Capitão IA chama APIs externas dentro de uma conversa. Em vez de só responder com base no que sabe, o assistente passa a agir: consulta um pedido no ERP, valida um cupom, cria um lead no CRM, abre um chamado no help desk, busca disponibilidade na agenda.

Cada ferramenta é um endpoint HTTP descrito por um esquema. O assistente decide quando chamá-la com base na descrição que você fornece, monta os parâmetros tipados a partir do contexto da conversa, executa a chamada e usa a resposta para continuar conversando.

Onde criar

Em Configurações → Capitão IA → Ferramentas. Clique em Nova ferramenta e preencha:

• Título — nome legível, exibido na listagem e referenciado em cenários.
• Descrição — explica para o assistente quando usar a ferramenta. É esse texto que o motor lê para decidir se a chamada é apropriada. Seja específico ("consulta o status de um pedido a partir do número do pedido", em vez de "fala com o ERP").
• URL do endpoint — endereço completo da API. URLs locais e endereços inseguros são bloqueados pela validação interna.
• Método HTTP — GET ou POST.
• Esquema de parâmetros — define os argumentos que o assistente pode passar. Cada parâmetro tem name, type, description e required (booleano). O motor valida e converte os valores antes de fazer a chamada.
• Template de requisição (request_template) — opcional. Texto com placeholders que serão substituídos pelos parâmetros antes do envio. Útil para montar corpos de POST com formato específico.
• Template de resposta (response_template) — opcional. Define como o resultado da API é apresentado de volta ao assistente, permitindo extrair só os campos relevantes em vez de devolver o JSON cru.
• Autenticação — none, bearer, basic ou api_key. Conforme o tipo escolhido, o sistema solicita o token, usuário/senha ou par chave/valor que será injetado em cada chamada. As credenciais ficam armazenadas com criptografia no workspace e nunca são expostas ao modelo.

Limites

Cada workspace pode ter até 15 ferramentas customizadas ativas. Ferramentas desativadas (enabled: false) não contam no limite e ficam disponíveis para reativação rápida sem reconfiguração.

O slug da ferramenta (gerado automaticamente a partir do título) tem no máximo 64 caracteres e é único por workspace. Esse slug é o identificador usado pelo motor ao listar as ferramentas para o assistente — por isso, evite renomear ferramentas em produção sem antes atualizar os cenários que dependem delas.

Esquema de parâmetros — exemplo

Para uma ferramenta de consulta de pedido:

[
  {
    "name": "order_id",
    "type": "string",
    "description": "Número do pedido a consultar, fornecido pelo cliente.",
    "required": true
  },
  {
    "name": "include_tracking",
    "type": "boolean",
    "description": "Quando verdadeiro, traz código de rastreamento.",
    "required": false
  }
]

A description de cada parâmetro é importante — é a partir dela que o assistente entende o que precisa coletar do cliente antes de fazer a chamada.

Como o assistente decide chamar uma ferramenta

Existem dois caminhos:

1. Decisão automática — o assistente, durante a geração de uma resposta, percebe que precisa de um dado externo e chama a ferramenta cujo description melhor casa com a necessidade.
2. Acionamento por cenário — você menciona explicitamente a ferramenta na instrução de um cenário com a sintaxe [@Título da Ferramenta](tool://slug). Quando o cenário é executado, a ferramenta é considerada disponível e o assistente a chama nos passos previstos.

Testar antes de publicar

A página de criação tem o botão Testar requisição. Ele dispara uma chamada real ao endpoint configurado (sem parâmetros do cliente) e mostra o status HTTP e os primeiros 500 caracteres da resposta. Use para validar:

• Que a URL está acessível a partir dos servidores do SiteUp.
• Que a autenticação configurada está correta.
• Que o formato da resposta é o esperado.

Se o teste retornar erro de rede, autenticação ou validação de domínio, corrija antes de habilitar a ferramenta para os assistentes.

Boas práticas

• Uma ferramenta = uma intenção. Não tente fazer uma ferramenta polivalente. Crie ferramentas pequenas e específicas; o motor escolhe melhor entre opções claras.
• Descreva como se fosse para um humano novo. A descrição da ferramenta e dos parâmetros é o único contexto que o motor recebe sobre quando e como usá-los.
• Trate erros no template de resposta. Se sua API devolve { "error": "..." }, transforme isso numa frase que o assistente saberá repassar de forma humanizada ao cliente.
• Versione mudanças no endpoint. Se a API muda de schema, crie uma nova ferramenta e migre cenários gradualmente, em vez de editar a antiga em produção.
• Não exponha dados sensíveis. Como a resposta da API entra no contexto do modelo, evite retornar campos confidenciais que não precisam ser usados na conversa.

Próximos passos

• Use as ferramentas dentro de cenários — veja Receitas de fluxo.
• Combine ferramentas com guardrails para evitar que dados externos sejam usados fora do escopo — veja Validações e handoff.