# Guia n8n — AI Agent com tool calling nativo

## Quando este guia e o certo

Use este caminho quando:

- voce quer o node **AI Agent** do n8n (nao o `HTTP Request` simples)
- o agente precisa **decidir sozinho** quando chamar uma ou mais Tools do n8n
  (HTTP Request Tool, Code Tool, Workflow Tool etc.)
- voce quer manter o ecossistema de nodes do n8n (memoria, Tools, parsers)
  em vez de montar esse loop na mao

Se voce so precisa mandar uma mensagem e devolver uma resposta pronta, sem o
agente decidir chamar ferramentas sozinho, use o
[guia n8n simples](/docs/integration-guide-n8n.md) — `Webhook` → `HTTP Request` →
responde. Este guia aqui e' para quando o n8n precisa orquestrar tool calling
de verdade.

## Por que funciona

O ChatAgent expoe `/v1/chat/completions` no mesmo contrato que a OpenAI usa
para tool calling: voce manda `tools` no corpo da requisicao, e quando o
modelo decide usar uma, a resposta volta com `finish_reason: "tool_calls"` e
os argumentos em JSON — o mesmo formato que qualquer client (inclusive o n8n)
ja espera. O node **AI Agent** do n8n so sabe conversar com um "Chat Model"
que fala esse contrato; ele nao sabe (nem precisa saber) que o modelo por
tras e' o ChatAgent em vez da OpenAI direto.

## Passo a passo

### 1. Crie a credencial

No n8n, crie uma credencial do tipo **OpenAI API** (a nativa, nao precisa de
credencial custom):

- **API Key**: sua API key de tenant (`chatag_...`)
- **Base URL**: `https://SEU-DOMINIO/v1` (ex.: `https://chatagentai.online/v1`)

### 2. Adicione o node "OpenAI Chat Model"

Conecte esse node a credencial criada no passo 1. Configure:

- **Model**: `chatagent-default` (roteia para ChatGPT) ou `chatagent-deepseek`
  (roteia para DeepSeek, texto-only)

Esses sao nomes de modelo **virtuais** — nao sao os modelos reais por tras
(ex.: `gpt-5.5`). Eles so escolhem qual provider o ChatAgent usa; o cliente
(n8n, nesse caso) fica desacoplado da implementacao interna.

### 3. Conecte no node "AI Agent"

Ligue a saida do "OpenAI Chat Model" na entrada de "Chat Model" do node
**AI Agent**. Adicione as Tools que o agente pode usar (HTTP Request Tool,
Code Tool, Workflow Tool, etc.) normalmente, como faria com a OpenAI direto.

### 4. Rode

O AI Agent gerencia o loop sozinho: manda a mensagem + `tools` pro Chat
Model, recebe `tool_calls` se o modelo decidir usar uma, executa a Tool
correspondente, manda o resultado de volta, e repete ate ter uma resposta
final em texto. Nada disso muda em relacao a usar a OpenAI direto — o
contrato e' o mesmo.

## O que e' diferente de tool calling nativo

O tool calling do ChatAgent e' **guiado por prompt**: as instrucoes das
Tools sao injetadas no contexto e o modelo responde com um JSON que o
ChatAgent decodifica e traduz pro formato `tool_calls` da OpenAI. O contrato
de request/response e' identico ao nativo, entao o n8n nao precisa de
nenhuma adaptacao — mas a taxa de acerto pode variar um pouco mais que um
modelo com function calling nativo de fabrica, especialmente com muitas
Tools declaradas ao mesmo tempo (acima de ~5-6). Se notar o agente ignorando
ou confundindo Tools, o primeiro ajuste e' reduzir quantas Tools ficam
disponiveis na mesma chamada.

## Erros comuns

- **Base URL sem `/v1` no final** — a credencial aponta pra raiz do site,
  n8n nao acha `/chat/completions`. Confirme que termina em `/v1`.
- **Usar a API key errada** — essa credencial usa a API key de **tenant**
  (`chatag_...`), a mesma do `/api/chat`. Nao e' a
  `INTERNAL_PRODUCT_IMAGE_API_KEY` (essa e' so para os endpoints de imagem).
- **Streaming desligado no node e a resposta demora "sumir"** — o endpoint
  suporta streaming; se o node tiver opcao de desativar, desative so se
  estiver debugando.
- **Muitas Tools, agente confuso** — ver secao acima.

## Validacao

- o node "OpenAI Chat Model" aponta pra `https://SEU-DOMINIO/v1`
- a credencial usa a API key de tenant, nao a interna de imagem
- o AI Agent chama uma Tool de teste simples primeiro (ex.: "que horas sao"
  via uma Tool que devolve a hora) antes de testar com Tools de produto reais
- os creditos do tenant diminuem a cada chamada (confirma que esta' batendo
  no ChatAgent de verdade, nao cacheado)