Como criar um agente de IA do n8n no seu VPS

O que é um agente de IA do n8n e como ele difere de uma cadeia

Um agente de IA do n8n é um único nó AI Agent com subnós conectados a ele: um modelo de chat, uma ou mais ferramentas e uma memória opcional. Você informa um objetivo em linguagem simples, e o modelo decide quais ferramentas chamar e em que ordem, até conseguir responder. Tudo abaixo é a configuração em torno dessa ideia.

Uma cadeia funciona de outra forma. Em uma Basic LLM Chain, você define as etapas, e o modelo apenas preenche o texto. Em um agente, o modelo define as etapas. Por isso, a mesma pergunta pode custar uma chamada ao modelo hoje e nove amanhã. Essa única diferença determina todas as configurações deste guia.

Este guia pressupõe que o n8n já esteja em execução atrás de HTTPS em uma máquina sob seu controle. Se não estiver, comece por hospedar o n8n em Docker com um certificado real, porque a chave de API que você está prestes a armazenar precisa do backup da chave de criptografia exigido por esse guia. Para os padrões sem agente, como sumarizadores de webhook e classificadores agendados, consulte padrões de workflows com Claude e n8n.

Verifique sua versão antes de confiar em qualquer nome de campo aqui, porque o n8n altera os nós de IA com frequência.

docker compose exec n8n n8n --version

Os nomes deste guia correspondem à versão estável atual do n8n em julho de 2026. Desde a versão 1.82.0, todo nó AI Agent é executado como um Tools Agent. Portanto, o menu suspenso do tipo antigo de agente não existe mais.

Etapa 1: escolha o gatilho

Para um agente conversacional, adicione um nó Chat Trigger. Mantenha Make Chat Publicly Available desativado durante a configuração, para que somente o painel de chat do editor possa acessá-lo. Ative-o quando o agente estiver pronto e você tiver definido a autenticação.

O Chat Trigger fornece ao agente um campo chamado chatInput. Esse nome é importante na etapa 3, e informá-lo incorretamente é a causa mais comum da primeira falha.

Para um agente não supervisionado, use um nó Schedule Trigger ou Webhook. Nenhum dos dois produz chatInput, portanto você escreverá o prompt manualmente.

Etapa 2: a credencial do modelo

Adicione um nó AI Agent à tela. O n8n exibirá imediatamente um conector Chat Model vazio abaixo dele. Anexe um subnó Anthropic Chat Model nesse conector.

Crie a credencial no Anthropic Console, em platform.claude.com, acessando Settings e depois API Keys. A chave é exibida uma única vez. O uso da API é cobrado por token e é separado de qualquer assinatura do Claude.ai. Portanto, a conta precisa ter o faturamento configurado antes da primeira execução.

Escolha o modelo por agente, não por empresa. Um agente com uma ferramenta que consulta algo e informa o resultado funciona bem com Haiku, que em julho de 2026 está listado a $1 por milhão de tokens de entrada e $5 por milhão de tokens de saída. Quando o agente tiver várias ferramentas e precisar planejar entre elas, passe para Sonnet. O problema que você deve evitar é um modelo barato chamar a ferramenta errada quatro vezes, gerando um custo maior que o de um modelo caro chamar a ferramenta correta uma vez.

Defina Maximum Number of Tokens nas opções do subnó. Esse parâmetro limita o tamanho de cada resposta produzida pelo modelo. Se permanecer com um valor padrão alto, uma execução confusa poderá produzir uma resposta muito longa e gerar essa cobrança.

Há uma observação da documentação do n8n que costuma causar problemas: as expressões dentro de um subnó sempre são avaliadas em relação ao primeiro item de entrada, nunca por item. Coloque as expressões por item nos campos de prompt do nó raiz.

Etapa 3: o prompt recebido pelo agente

Abra o nó AI Agent. O parâmetro Prompt tem duas configurações.

• Take from previous node automatically espera um campo de entrada chamado chatInput. Essa é a opção correta quando o nó vem depois de um Chat Trigger.
• Define below exibe um campo Prompt (User Message) no qual você escreve texto estático ou uma expressão. Essa é a opção correta quando o nó vem depois de um Schedule Trigger ou de um Webhook node.

Com um Webhook node na etapa anterior, o corpo da requisição POST fica em $json.body, portanto o campo de prompt fica assim.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Etapa 4: forneça uma ferramenta ao agente

Um nó AI Agent sem um subnó de ferramenta se recusa a executar. Comece com uma ferramenta, porque uma ferramenta funcionando ensina mais do que quatro ferramentas parcialmente configuradas.

Conecte um nó HTTP Request ao conector Tool do agente. Configure-o exatamente como faria com um nó HTTP Request normal. Depois, teste esse endpoint primeiro a partir de um shell.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

Se esse comando curl retornar um erro ou uma página de login em HTML, o agente também falhará. A falha parecerá um problema do modelo, quando na verdade será um problema de URL ou autenticação. Corrija-o no shell, não no nó.

O campo Description da ferramenta não é documentação para seus colegas. Ele é o único conteúdo que o modelo lê ao decidir se essa ferramenta é relevante. Escreva uma afirmação simples sobre o que será retornado: "Retorna o estado atual, ativo ou inativo, e a duração da indisponibilidade de um serviço monitorado, no formato JSON."

Para permitir que o modelo preencha parte da solicitação, use a expressão $fromAI(). Ela funciona somente em ferramentas conectadas a um nó AI Agent. Ela não funciona na ferramenta Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Os argumentos são key, seguidos por description, type e defaultValue opcionais. A chave deve ter de 1 a 64 caracteres e usar letras, dígitos, sublinhados e hífens. O tipo deve ser um dos valores string, number, boolean ou json, e o padrão é string. Uma chamada mais completa é semelhante a esta.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

A chave é uma dica, não uma referência a dados existentes. $fromAI('service') não lê um campo chamado service de nenhum lugar. Ele informa ao modelo: "produza um valor e chame-o de service". O modelo procura esse valor na conversa, nos dados de entrada e nos resultados de outras ferramentas. Em um fluxo de trabalho de chat, ele pode simplesmente perguntar ao usuário.

Etapa 5: memória e por que o agente esquece

Sem um subnó de memória, cada mensagem começa do zero. Anexe um subnó Simple Memory para armazenar a conversa recente.

Ele tem dois parâmetros. Session Key define qual é a conversa, portanto dois usuários com chaves diferentes têm históricos separados. Context Window Length define quantas interações anteriores são reinseridas no prompt.

Context Window Length também controla o custo, não apenas a qualidade, porque cada turno armazenado é reenviado como tokens de entrada em todas as chamadas posteriores. Uma janela de 20 em um agente com muitas mensagens significa pagar vinte vezes pelas mesmas mensagens iniciais.

Simple Memory não funciona em um workflow de produção ativo quando o n8n é executado no modo de fila, porque o histórico fica nos próprios dados do workflow, e não em um armazenamento compartilhado. Em uma instância no modo de fila, use o subnó Postgres Chat Memory e aponte-o para um banco de dados que possa ser acessado tanto pelo processo principal quanto pelos workers.

Etapa 6: a mensagem do sistema

Abra as Options do agente e adicione uma System Message. É nesse campo que entra a descrição da tarefa, e esse é o texto de maior impacto no fluxo de trabalho.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

"Always call the status tool before answering" tem uma função importante. Sem essa instrução, um modelo que acredita já saber a resposta pode ignorar a ferramenta e responder com base na memória. A resposta estará errada com segurança assim que a sua infraestrutura mudar.

Por que o agente entra em loop e o que o interrompe

Em Options, também está disponível Max Iterations, cujo padrão é 10. Uma iteração é uma chamada do modelo seguida de um resultado de ferramenta enviado de volta ao contexto. Portanto, uma execução do agente não é uma única chamada de API: são até dez chamadas, e cada uma envia como entrada toda a conversa acumulada.

Reduza esse valor. A maioria dos agentes que usam uma única ferramenta termina em duas iterações. Um limite de 3 ou 4 transforma um loop sem fim em uma falha clara, que você pode ver na lista de execuções.

Enquanto estiver depurando, ative Return Intermediate Steps. A saída final passará a incluir as chamadas de ferramenta feitas pelo agente. Assim, você pode diferenciar "o modelo nunca chamou a ferramenta" de "a ferramenta não retornou nada útil". Desative essa opção antes de colocar o sistema em produção, porque essas etapas não são úteis para o usuário final.

Observe uma execução pelo shell.

docker compose logs -f n8n

Impedir que um agente não supervisionado consuma recursos silenciosamente

Um agente acionado por um Chat Trigger tem uma pessoa supervisionando-o, e essa pessoa o interrompe quando a resposta parece incorreta. Um agente acionado por um Schedule Trigger não tem ninguém observando. O tratamento completo está em Controle de custos de agentes de IA em um VPS sempre ativo. Quatro configurações fazem a maior parte do trabalho aqui.

• Limite Maximum Number of Tokens no subnó do modelo, para que nenhuma resposta individual seja longa demais.
• Defina Max Iterations como o menor número que ainda conclua a tarefa.
• Mantenha pequenas as respostas das ferramentas. Uma ferramenta que retorna um bloco JSON de 4,000 linhas insere todo esse conteúdo na próxima chamada do modelo e, depois, em todas as chamadas seguintes da mesma execução.
• Verifique se o agente realmente precisa de um agendamento. Um job executado a cada cinco minutos é disparado 288 vezes por dia. Multiplique o custo de uma execução por esse número.

Desative o workflow enquanto estiver iterando. Um workflow ativo com um Schedule Trigger continua sendo executado com base na versão que o n8n salvou, que nem sempre é a versão exibida na tela.

FAQ

Por que meu nó AI Agent se recusa a executar?

O nó AI Agent exige um subnó de modelo de chat e pelo menos um subnó de ferramenta. Um nó com um modelo, mas sem uma ferramenta, falha antes de fazer qualquer chamada de API. Adicione uma ferramenta, mesmo que seja trivial, e execute novamente.

O agente responde, mas nunca chama minha ferramenta. O que está errado?

Quase sempre, o problema está no campo Description da ferramenta. O modelo escolhe as ferramentas lendo essas descrições. Portanto, uma descrição como "HTTP Request" não informa quando a ferramenta deve ser usada. Reescreva a descrição para informar quais dados são retornados e em que situação a ferramenta é útil. Em seguida, adicione uma linha ao System Message instruindo o agente a chamar essa ferramenta antes de responder.

Por que a mesma pergunta custa um valor diferente em cada execução?

Porque o modelo escolhe o número de etapas. Cada iteração envia novamente todo o histórico da conversa, incluindo a saída anterior da ferramenta. Por isso, uma execução que leva quatro iterações custa muito mais do que quatro vezes uma única chamada. Max Iterations define o limite máximo, e Return Intermediate Steps mostra quantas etapas a execução realmente usou.

Minha memória funciona no editor, mas não em produção. O que mudou?

Verifique se a instância está executando no modo de fila. Simple Memory armazena o histórico nos dados de execução do próprio workflow. Esses dados não persistem quando são transferidos para um processo de worker separado. Por isso, um workflow de produção ativo perde o histórico. Substitua-o pelo subnó Postgres Chat Memory, que mantém o histórico no banco de dados compartilhado por todos os workers.