Ferramentas HTTP customizadas

Nem tudo cabe nas ferramentas nativas. Com as HTTP tools, você aponta o agente para um endpoint HTTP dos seus próprios sistemas (um webhook, uma API interna, um recurso do IXC/MK-Auth/SGP que ainda não é nativo) e ele passa a usá-lo como uma ferramenta. No LLM, cada uma vira http_<slug>.

Onde fica

Menu Loja › Ferramentas HTTP, rota /config/integracoes/http-tools. Criar e editar exige a permissão integracoes:edit.

A lista

No topo, uma frase resume a tela: quantas ferramentas existem, quantas estão ligadas e quantas chamadas os agentes fizeram nos últimos 7 dias, com quantas terminaram em erro.

Abaixo, uma linha por ferramenta: o nome, a descrição, o método e o servidor chamado, e o uso da semana (por exemplo, “120 chamadas em 7 dias, 2,5% com erro”). A ferramenta desligada diz Desligada. Quando uma ferramenta ligada erra em mais de 5% das chamadas, a linha ganha uma régua de atenção ao lado: é ela que precisa ser olhada.

Clique numa ferramenta para abrir o painel ao lado, com o endereço completo, o uso da semana, o teste e as últimas chamadas. O botão Nova ferramenta HTTP abre o formulário nesse mesmo painel.

Criar uma HTTP tool

1. Identificação. Um Nome (slug) no formato [a-z][a-z0-9_]* (ex. consulta_estoque) e uma Descrição: este texto é a instrução para o LLM sobre quando usar a ferramenta. Capriche: é o que faz a IA acionar a tool na hora certa.

2. Request. O Método e a URL template. A URL aceita interpolação de variáveis:

   • {{args.x}}: o que o LLM passa na chamada
   • {{subscriber.name}}: dados do assinante em atendimento
   • {{org.id}}: dados da organização

   Adicione Headers (chave/valor, ex. Authorization: Bearer {{org.api_token}}) e, se o método não for GET, um Body template (ex. {"sku":"{{args.sku}}"}).

3. Parâmetros. O que o LLM preenche em cada chamada. Para cada um: nome ([a-zA-Z][a-zA-Z0-9_]*), tipo (string/number/boolean), se é obrigatório, uma descrição e, para strings, valores permitidos (enum). Isso vira o JSON Schema que o agente entende.

4. Response mapping (opcional). Documente os campos da resposta que importam: isso ajuda o LLM a interpretar o retorno.

5. Avançado. Timeout em milissegundos (1000 a 60000, padrão 15000) e o checkbox Habilitada. Clique em Criar ferramenta.

Testar, editar, ligar e excluir

Tudo acontece no painel da ferramenta:

• Testar com valores de exemplo: preencha os valores que o agente passaria e clique em Testar agora. O resultado diz se deu certo, o status HTTP, o tempo e o que voltou; em Ver a requisição montada aparecem o endereço, os cabeçalhos (com os segredos mascarados) e o corpo enviados. Sempre teste com um caso real antes de ligar: assim você confirma URL, cabeçalhos e a forma da resposta.
• Últimas chamadas: as 20 mais recentes, cada uma com Deu certo ou Falhou, o status HTTP, o tempo, o canal (WhatsApp, telefone ou teste) e há quanto tempo foi. Na que falhou, aparece a mensagem de erro.
• Editar troca o painel pelo formulário. Ao salvar, o painel volta a mostrar a ferramenta, pronta para testar de novo.
• Ligar ou Desligar controla se o agente vê a ferramenta.
• Excluir pede confirmação e não pode ser desfeito.

Sem a permissão integracoes:edit, a tela mostra a lista e as últimas chamadas, mas não oferece criar, testar, editar nem excluir, e os cabeçalhos (que podem guardar token) não aparecem.

Veja também

• Servidores MCP: outra forma de estender o agente
• Ferramentas nativas
• Ferramentas do agente