HTTP API

As ferramentas de HTTP API permitem que seu agente chame endpoints REST durante uma conversa com base no prompt do agente e na definição da ferramenta.

O que é uma ferramenta de HTTP API?

Uma ferramenta de HTTP API é uma definição de API REST que o LLM pode invocar em tempo de execução.

Casos de uso típicos:

• Chamar os endpoints do seu próprio backend
• Disparar automações do n8n
• Sincronizar dados com um CRM
• Buscar dados de APIs externas (clima, preços, disponibilidade etc.)
• Gravar/atualizar/ler dados usando API REST

O LLM decide:

• qual ferramenta chamar
• quando chamá-la
• quais parâmetros enviar

Com base em:

• Seus prompts: instruções do agente em inglês simples (ou qualquer idioma)
• Nome da ferramenta
• Descrição da ferramenta
• Definições de parâmetros

---

Definindo uma ferramenta de HTTP API

1. Nome da ferramenta

• Deve ser claro e orientado à ação.

• Exemplos: capture_lead_interest, fetch_weather, create_crm_contact etc.

2. Descrição da ferramenta

• Extremamente importante
• É assim que o LLM decide quando usar a ferramenta.
• Escreva-a em inglês simples e explícito.

Ruim: "API to capture data"

Bom: "This tool is to capture interest. Use this tool when the user clearly expresses interest in the product or wants to be contacted"

3. Configuração do endpoint

• URL completa (deve incluir http:// ou https://)
• Suporta métodos REST

Nota

Erro comum: esquecer o https:// na URL.

---

4. Autenticação e cabeçalhos

• Adicione autenticação personalizada
• Adicione cabeçalhos personalizados
• Funciona com serviços internos e APIs de terceiros

---

5. Parâmetros

Cada parâmetro deve ter:

• Nome
• Tipo
• Descrição
• Sinalizador de obrigatório/opcional

As descrições dos parâmetros importam mais do que os tipos.

Diretrizes:

• Comece com parâmetros de string quando possível
• Seja explícito sobre o que o valor representa
• Marque apenas campos verdadeiramente obrigatórios como required

Exemplo:

• interest (boolean): "Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false."

---

Anexando ferramentas ao agente

• Você pode anexar várias ferramentas ao agente
• Todas as ferramentas que você criou estarão disponíveis para seleção nas configurações do agente
• As ferramentas só podem ser chamadas quando anexadas ao agente
• O LLM escolherá qual chamar

No prompt do agente, guie o LLM usando instruções em inglês simples.

Exemplo:

"If the user shows interest in speaking to sales or wants a callback, immediately call the capture_lead_interest tool and set interest to true."

Essa instrução costuma ser o fator decisivo para o uso correto da ferramenta.

---

Lógica de invocação da ferramenta (como o LLM pensa)

O LLM considera:

• A intenção falada do usuário
• As instruções do prompt do agente
• O nome e a descrição da ferramenta
• As descrições dos parâmetros

Se tudo isso se alinhar claramente, a ferramenta é chamada automaticamente.

Nomes ruins ou descrições vagas levam a:

• Chamadas de ferramenta perdidas
• Parâmetros errados
• Valores alucinados

---

Principais práticas recomendadas

• Dê nomes claros às ferramentas
• Escreva descrições detalhadas e baseadas em ação
• Mantenha os parâmetros simples no início
• Sempre inclua http/https nas URLs
• Use inglês simples nas instruções do agente
• Anexe apenas ferramentas relevantes ao agente

Ferramentas bem definidas + prompts claros = agentes de voz confiáveis, prontos para produção.

Confirme o resultado da configuração

Associe a ferramenta ao agente e teste uma pergunta que exija a consulta. Confira se os parâmetros têm os nomes e tipos esperados pelo endpoint e se o agente explica o resultado recebido.

Use uma credencial e endpoint de teste quando a ação altera dados. Configure nas instruções o comportamento em caso de erro; não anuncie uma atualização como concluída sem confirmação do serviço.

Ferramenta durante a conversa ou webhook depois dela?

HTTP API permite consultar ou executar uma ação quando o agente precisa dela na conversa. Um webhook pós-chamada envia dados de resultado ao seu sistema. Escolha pelo momento da tarefa, não apenas porque ambos usam HTTP.