> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tigyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Crie ferramentas de API REST que seu agente de IA pode invocar durante as conversas para integrar-se a sistemas externos.

As ferramentas de HTTP API permitem que seu agente chame endpoints REST durante uma conversa com base no prompt do nó 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 em nível de nó em inglês simples (ou qualquer idioma)
* Nome da ferramenta
* Descrição da ferramenta
* Definições de parâmetros

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## 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"

<img src="https://mintlify.s3.us-west-1.amazonaws.com/callguard/images/tool%20description.png" alt="Exemplo de descrição de ferramenta" />

### 3. Configuração do endpoint

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

<Note>Erro comum: esquecer o https\:// na URL.</Note>

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

### 4. Autenticação e cabeçalhos

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

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

### 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 (string):
  "Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false."

<img src="https://mintlify.s3.us-west-1.amazonaws.com/callguard/images/tool%20params.png" alt="Exemplo de parâmetro" />

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## Anexando ferramentas aos nós do workflow

* Você pode anexar **várias ferramentas a um único nó**
* Todas as ferramentas que você criou estarão disponíveis para seleção no nó
* As ferramentas só podem ser chamadas quando anexadas àquele nó
* O LLM escolherá qual chamar

Dentro do nó, 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.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/callguard/images/tool%20attachment.png" alt="Exemplo de anexo de ferramenta" />

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## 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 nó
* 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

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## 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 dos nós
* Anexe apenas ferramentas relevantes a cada nó

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