Tool HTTP: referência

A tool HTTP (no painel, Chamada de API) faz o agente chamar qualquer sistema que tenha API: a agenda da clínica, o ERP da loja, um CRM externo, um fluxo no n8n. O modelo decide quando chamar, preenche os dados que você marcou como “IA”, e recebe a resposta da API para usar na conversa. Esta página é a referência do editor. O que a API do outro lado precisa cumprir está em Tool HTTP: como montar a sua API.

​

Onde fica no painel

Editor do agente → Tools → Adicionar → Chamada de API. O editor abre com o mínimo (nome, descrição, endereço). Cada seção de envio só aparece quando ligada.

​

Como configurar

​

Campos principais

​

Enviar

Três seções, cada uma com um interruptor. Desligar a seção apaga o que estava nela.

​

Os três modos de valor

Cada linha (parâmetro, cabeçalho ou campo do corpo) tem Nome, Valor e um modo: No modo IA, a linha pede:

• Nome para a IA: o nome do dado que o modelo preenche (numero_do_pedido).
• Descrição para a IA: o que colocar ali (“Número do pedido informado pelo cliente, só dígitos”).
• Tipo: Texto, Número, Número inteiro, Booleano, Lista ou Objeto.
• Obrigatório: se o modelo pode deixar de fora. Todo dado novo nasce obrigatório.

Os dados do modo IA aparecem em Preenchido pela IA, acima das seções.

​

Variáveis do lead

No modo Variável (ou escrevendo {{…}} direto num campo): Regras:

• Variável vazia cancela a chamada. Se o lead não tem anotação e a tool usa {{lead_notes}}, a requisição não é feita e o modelo recebe um erro dizendo que a variável não está disponível. Só use variável que todo lead tem.
• Propriedades só chegam se estiverem marcadas “enviar para a IA”. As outras não existem para a tool, e usar uma delas cancela a chamada. Veja Propriedades.
• Campo que é só a variável mantém o tipo. "{{args.quantidade}}" envia o número 5, não o texto "5". {{lead_tags}} sozinho envia uma lista.
• Variável no meio de um texto vira texto. "Bearer {{args.token}}" funciona; no editor, a linha aparece como Fixo, com o texto como está.
• {{args.x}} pode ir na URL: https://api.loja.com/pedidos/{{args.numero}}.

​

Comportamento

​

Enviar dados da conversa

Ligado, acrescenta ao corpo da requisição: Um campo seu no Corpo com o mesmo nome vale no lugar do automático. Em GET não há corpo, então esses dados não vão. Para mandar o lead num GET, use variáveis em Parâmetros na URL.

​

Tempo limite

Cada chamada pode levar até 180 segundos por padrão. O campo não aparece no editor; muda só pelo JSON (timeout_seconds). Como a resposta inteira do agente também tem 180 segundos, uma API que demora deixa o lead esperando e pode estourar o tempo. Faça a API responder em poucos segundos.

​

O schema dos parâmetros

Os dados do modo IA formam um JSON Schema que vai intacto ao modelo. É ele que diz ao modelo o formato de cada dado.

• Lista precisa do formato do item. Ao escolher Lista, defina Formato de cada item. Sem isso, o painel não deixa salvar: alguns modelos (como os do Google) recusam a chamada inteira, em todas as mensagens, não só nesta tool.
• Objeto pede Campos do objeto, cada um com nome, tipo, descrição e obrigatório.
• Lista ou objeto: dá para colar um exemplo em JSON e o editor deduz o formato.
• Dados que não estão posicionados em nenhuma linha (vindos de um JSON antigo) vão inteiros no corpo, ou na URL em GET. Ao abrir no editor, eles aparecem como linhas do corpo.

​

O que o modelo recebe

​

Importar de cURL

Em Endereço, Importar de cURL: cole um comando curl (da documentação da API ou do Postman) e clique Preencher. O editor:

• preenche método, URL, cabeçalhos e parâmetros da URL (substitui o que havia);
• transforma cada campo do corpo JSON em um dado do modo IA, obrigatório, com o tipo deduzido do exemplo;
• usa o fim da URL como nome, se o nome estiver vazio.

Depois de importar, revise: escreva a Descrição para a IA de cada dado, passe para Fixo o que não deve vir do modelo (ids, chaves), e defina o formato do item de toda Lista.

​

Testar

O botão Testar, no rodapé, roda a tool de verdade, do mesmo jeito que o agente rodaria. O teste recusa endereços internos (localhost, IPs de rede privada) e segue até 5 redirecionamentos. A API precisa estar num endereço público.

​

Pelo MCP

A tool viaja no bloco langchain do template do projeto, em config.tools, com os campos da tabela acima. O get_template devolve cabeçalhos e chaves preenchidos: nunca mostre esses valores na conversa e mantenha o snapshot fora do git. Na escrita, require_approval é forçado para false, com nota. Testar só pelo painel.

​

Armadilhas

• Variável que nem todo lead tem ({{lead_notes}}, {{lead_name}} de quem não tem nome no WhatsApp, uma propriedade não preenchida) cancela a chamada para esses leads.
• Propriedade sem “enviar para a IA” não chega à tool.
• GET com Enviar dados da conversa ligado não envia os dados (não há corpo).
• Lista sem formato do item bloqueia o salvamento. Num JSON escrito à mão, faz alguns modelos recusarem todas as mensagens do agente.
• Desligar uma seção apaga o conteúdo dela.
• Chave no modo IA. Chave de API vai em Fixo. No modo IA, o modelo inventaria um valor.
• Descrição para a IA vazia. O modelo adivinha o formato (data com ou sem hora? CPF com pontos?). Escreva o formato esperado.
• Testar cria dados reais.

​

Perguntas frequentes

​

Para saber mais

• Tool HTTP: como montar a sua API
• Tools: visão geral
• O que a Zatten injeta no contexto
• Testar o agente
• OpenAI, function calling (schema dos parâmetros): https://developers.openai.com/api/docs/guides/function-calling
• Anthropic, “Writing tools for agents”: https://www.anthropic.com/engineering/writing-tools-for-agents
• Termos para buscar: “JSON Schema”, “function calling parameters”, “cURL”, “Bearer token”.