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 Configuração › Integrações › Ferramentas HTTP — rota /config/integracoes/http-tools. Criar e editar exige a permissão integracoes:edit.

A lista

KPIs no topo (total, ativas, execuções e erros nos últimos 7 dias). Cada tool mostra o método (GET/POST/PUT/DELETE/PATCH), o nome, a URL template, a descrição, um toggle ativar/desativar e métricas (execuções, % de erro, último status HTTP). Se a taxa de erro passar de 5%, aparece um alerta “Taxa de erro alta”.

Ações por tool: Testar (roda com argumentos vazios e mostra o JSON de resposta), Editar e Excluir. O botão Nova HTTP tool abre o formulário.

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 — ajuda o LLM a interpretar o retorno.

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

Testar antes de soltar

Na tela de edição há um testador que roda a ferramenta com argumentos reais e mostra o resultado, e um histórico das execuções recentes. Sempre teste com um caso real antes de habilitar — assim você confirma URL, headers e a forma da resposta.

Veja também

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