Tutorial de AI Agent no n8n: crie um assistente de IA que usa ferramentas

O n8n inclui recursos completos de IA. O mais poderoso é o nó AI Agent: ele não apenas responde a perguntas, mas também pode decidir por conta própria quais ferramentas usar conforme necessário, por exemplo, para consultar informações, chamar APIs ou fazer cálculos, e então responder com base nos resultados.

Componentes do AI Agent

Abaixo do nó AI Agent há alguns conectores para ligar “subnós”:

                    [When chat message received]
                               │
                               ▼
                         [ AI Agent ]
                     ┌────────┼────────┐
               Chat Model   Memory    Tool(s)
                   │          │        │
          [OpenAI Chat Model] [Simple Memory] [Calculator] [HTTP Request Tool] …

Crie um assistente de chat

1. Adicione um gatilho de chat

Crie um workflow e escolha When chat message received (Chat Trigger) como primeiro nó. O botão Open chat aparecerá na parte inferior do editor. Você pode conversar diretamente no n8n para testar.

2. Adicione o AI Agent

Adicione o nó AI Agent depois do Chat Trigger.

3. Conecte um modelo de chat

Clique no + de Chat Model, abaixo do AI Agent, e escolha um modelo, como OpenAI Chat Model:

1. Crie uma credencial da OpenAI e cole a chave de API.
2. Escolha um modelo.

Para usar um modelo local gratuito, veja Conecte o n8n ao Ollama.

4. Conecte a memória

Clique no + de Memory e escolha Simple Memory. Context Window Length define quantas rodadas recentes da conversa serão lembradas, por exemplo, 10.

Sem memória, cada frase enviada ao Agent inicia uma conversa nova, e ele não se lembra do que você acabou de dizer.

Simple Memory fica na memória do n8n e desaparece quando ele é reiniciado. Também não é adequada para ambientes com várias instâncias do n8n. Para uso em produção, troque por Postgres ou Redis Chat Memory.

5. Configure as instruções do sistema

Em Options → System Message, no AI Agent, escreva o papel e as regras do Agent:

Você é o assistente de atendimento online da cafeteria “Bom Café”.
- Use sempre português brasileiro, com um tom simpático e conciso.
- Responda sobre o cardápio e os preços apenas com base nos resultados da ferramenta “Consultar cardápio”; não invente informações.
- Se receber uma reclamação ou uma pergunta que não puder resolver, peça ao cliente que deixe uma forma de contato e informe que uma pessoa da equipe responderá.

6. Teste

Clique em Open chat e digite “Olá, qual é o horário de funcionamento?”. Na saída (Logs) do nó AI Agent, você pode ver cada etapa do raciocínio do modelo e as chamadas de ferramentas.

Adicione ferramentas

As ferramentas permitem que o Agent obtenha informações em tempo real ou execute ações. Clique no + de Tool para adicionar várias ferramentas.

Calculator

Permite que o Agent faça cálculos precisos. Modelos de linguagem costumam errar ao calcular números diretamente; com a ferramenta de calculadora, os resultados são muito mais confiáveis.

Ferramenta Google Sheets: consultar o cardápio

1. Prepare uma planilha com as colunas “Nome do item, preço, descrição”.
2. Adicione a ferramenta Google Sheets e escolha a operação de leitura de linhas (Get Rows).
3. Explique a finalidade no campo Description da ferramenta:

Consulte o cardápio da cafeteria. Use quando o cliente perguntar sobre itens, preços ou recomendações.

O Agent decide quando usar essa ferramenta com base nessa descrição. A qualidade da descrição da ferramenta afeta diretamente o desempenho do Agent.

Deixe a IA preencher os parâmetros

Ao lado dos campos de parâmetros da ferramenta há um botão ✨ (Let the model define this parameter). Ao ativá-lo, o Agent preenche o campo automaticamente com base na conversa. Por exemplo, para o parâmetro de cidade do HTTP Request Tool, o Agent extrai “Campinas” da pergunta “Vai chover hoje em Campinas?”.

Em expressões, você também pode usar $fromAI():

{{ $fromAI('city', 'Nome da cidade para consultar o clima', 'string') }}

Chame outros workflows como ferramentas

Call n8n Workflow Tool transforma qualquer workflow em uma ferramenta do Agent. Por exemplo, você pode empacotar todo o processo de “Criar pedido” (gravar no banco de dados, enviar um e-mail de confirmação e avisar a equipe) como uma ferramenta para o Agent usar.

Interface de chat pública

Nas configurações do Chat Trigger, ative Make Chat Publicly Available. Depois de publicar o workflow, você receberá o endereço de uma página de chat. Também pode incorporar o pacote oficial ao seu site. Lembre-se de configurar a autenticação para evitar uso indevido e custos elevados de API.

Diferentes formas de iniciar

O AI Agent não precisa estar conectado a um Chat Trigger; você pode usar qualquer gatilho:

• Telegram Trigger → AI Agent → resposta no Telegram: um chatbot no Telegram (veja Bot do Telegram)
• Gmail Trigger → AI Agent → rascunho de resposta
• Webhook → AI Agent → Respond to Webhook: crie uma API de IA

Nesse caso, altere a entrada do Agent em Source for Prompt para uma expressão personalizada, por exemplo, {{ $json.message.text }}.

Perguntas frequentes

O Agent não usa ferramentas

• Confirme se o modelo escolhido aceita chamadas de ferramentas.
• Melhore a descrição da ferramenta e explique claramente quando usá-la.
• Nas instruções do sistema, peça explicitamente: “Antes de responder a perguntas sobre preços, use sempre a ferramenta Consultar cardápio”.

As respostas demoram ou custam caro

Cada chamada de ferramenta gera uma solicitação adicional ao modelo. Remova ferramentas desnecessárias, reduza o tamanho da memória ou escolha um modelo mais rápido.

Não se lembra das conversas anteriores

Confirme se Memory está conectado e se você está usando o mesmo Session ID. O Chat Trigger cuida disso automaticamente; com outros gatilhos, defina o ID do usuário como Session Key.

Na próxima seção, você vai aprender a fazer o AI Agent usar um modelo local gratuito.

Atualizado 12 de outubro de 2026