Como criar um agente de IA no n8n em VPS

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

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

Uma cadeia funciona de forma diferente. Numa Basic LLM Chain, você define os passos e o modelo apenas gera o texto. Num agente, o modelo decide os passos. Por isso, a mesma pergunta pode custar uma chamada ao modelo hoje e nove amanhã. Essa diferença determina todas as definições deste guia. Se este ciclo ainda é novo para si como conceito, e não apenas como funcionalidade do n8n, vale a pena escrevê-lo manualmente uma vez antes de o montar com nós, porque o nó oculta precisamente a parte sobre a qual terá de raciocinar durante o resto deste guia.

Este guia pressupõe que o n8n já está a funcionar atrás de HTTPS numa máquina que controla. Se não estiver, comece por alojar o n8n no Docker com um certificado válido, porque a chave da API que vai armazenar precisa da cópia de segurança da encryption key exigida nesse guia. Para os padrões sem agentes, como sumarizadores acionados por webhook e classificadores agendados, consulte Padrões de workflows com Claude e n8n.

Confirme a sua versão antes de confiar em qualquer nome de campo apresentado aqui, porque o n8n altera frequentemente os nós de IA.

docker compose exec n8n n8n --version

Os nomes deste guia correspondem à versão stable atual do n8n em julho de 2026. Desde a versão 1.82.0, todos os nós AI Agent funcionam como Tools Agent, pelo que a antiga lista suspensa de tipos de agente já não existe.

Passo 1: escolha o acionador

Para um agente conversacional, adicione um nó Chat Trigger. Mantenha Make Chat Publicly Available desativado enquanto estiver a criar o fluxo, para que apenas o painel de chat do editor lhe possa aceder. Ative-o quando o agente estiver concluído e tiver decidido o método de autenticação.

O Chat Trigger fornece ao agente um campo chamado chatInput. Esse nome é importante no passo 3, e escrevê-lo incorretamente é a causa mais comum da primeira falha.

Para um agente não supervisionado, utilize um nó Schedule Trigger ou Webhook. Nenhum dos dois produz chatInput, por isso terá de escrever o prompt manualmente.

Passo 2: a credencial do modelo

Adicione um nó AI Agent ao canvas. O n8n mostra imediatamente um conector Chat Model vazio por baixo dele. Ligue aí um subnó Anthropic Chat Model.

Crie a credencial na Anthropic Console, em platform.claude.com, através de Settings e depois API Keys. A chave é apresentada uma única vez. A utilização da API é faturada por token e é independente de qualquer subscrição Claude.ai. Por isso, a conta tem de ter a faturação configurada antes da primeira execução.

Escolha o modelo por agente, não por empresa. Um agente com uma ferramenta, que consulta algo e comunica o resultado, funciona bem com Haiku, que em julho de 2026 apresenta o preço de $1 por milhão de tokens de entrada e $5 por milhão de tokens de saída. Quando o agente tem várias ferramentas e precisa de planear entre elas, mude para Sonnet. O problema que deve evitar é um modelo barato que chama a ferramenta errada quatro vezes. Isso pode custar mais do que um modelo caro a chamar a ferramenta correta uma vez.

Defina Maximum Number of Tokens nas opções do subnó. Este parâmetro limita o tamanho de cada resposta produzida pelo modelo. Se ficar com um valor predefinido elevado, uma execução confusa pode produzir uma resposta muito longa e aumentar a faturação.

Há uma particularidade na documentação do n8n que causa problemas frequentes: as expressões dentro de um subnó são sempre avaliadas em relação ao primeiro item de entrada, nunca por item. Coloque as expressões específicas de cada 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 definições.

• Take from previous node automatically espera um campo de entrada chamado chatInput. Esta é a opção correta quando existe um Chat Trigger a montante.
• Define below mostra um campo Prompt (User Message) onde pode escrever texto estático ou uma expressão. Esta é a opção correta quando existe um Schedule Trigger ou um nó Webhook a montante.

Com um nó Webhook a montante, o corpo de uma requisição POST fica disponível em $json.body, por isso o campo do 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: dê ao agente uma ferramenta

Um nó AI Agent sem um subnó de ferramenta recusa-se a executar. Comece com uma ferramenta, porque uma ferramenta funcional ensina mais do que quatro ferramentas configuradas apenas pela metade.

Ligue um nó HTTP Request ao conector Tool do agente. Configure-o exatamente como configuraria um nó HTTP Request normal e teste primeiro esse endpoint a partir de uma shell.

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

Se esse curl devolver um erro ou uma página HTML de início de sessão, o agente também vai falhar. A falha pode parecer um problema do modelo, quando na realidade é um problema de URL ou de autenticação. Corrija-o na shell, não no nó.

O campo Description da ferramenta não é documentação para os seus colegas. É a única informação que o modelo lê ao decidir se essa ferramenta é relevante. Escreva uma descrição simples do resultado devolvido: "Devolve o estado atual, ativo ou inativo, e a duração da indisponibilidade de um serviço monitorizado, em JSON."

Para permitir que o modelo preencha parte do pedido, use a expressão $fromAI(). Esta expressão só funciona em ferramentas ligadas a um nó AI Agent. Não funciona na ferramenta Code.

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

Os argumentos são key, seguidos de description, type e defaultValue opcionais. A chave deve ter entre 1 e 64 caracteres e usar letras, algarismos, sublinhados e hífenes. O tipo deve ser um de string, number, boolean ou json e, por predefinição, é string. Uma chamada mais completa tem este aspeto.

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

A chave é uma indicação, não uma referência a dados existentes. $fromAI('service') não lê um campo chamado service a partir de nenhum local. Indica ao modelo que deve "produzir um valor e chamar-lhe service". O modelo procura esse valor na conversa, nos dados de entrada e nos resultados de outras ferramentas. Num fluxo de trabalho de chat, pode simplesmente perguntar ao utilizador.

A pesquisa na Web é normalmente a segunda ferramenta. Como é apenas outro endpoint HTTP, pode apontar este mesmo nó para a sua própria instância SearXNG em vez de uma API de pesquisa paga, desde que trate todas as páginas que ela devolve como texto não fiável que passa a estar dentro do seu prompt.

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 manter a conversa recente.

Ele tem dois parâmetros. Session Key determina qual é a conversa, por isso dois utilizadores com chaves diferentes têm históricos separados. Context Window Length define quantas interações anteriores são reenviadas no prompt.

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

Simple Memory não funciona num workflow de produção ativo quando o n8n é executado em modo de fila, porque o histórico fica nos próprios dados do workflow, e não num armazenamento partilhado. Numa instância em modo de fila, use o subnó Postgres Chat Memory e aponte-o para uma base de dados que possa ser acedida pelo processo principal e pelos workers.

Passo 6: a mensagem do sistema

Abra as Options do agente e adicione uma System Message. É aqui que entra a descrição da tarefa, e este é o texto com maior impacto em todo o 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 concreta. Sem essa instrução, um modelo que considere já conhecer a resposta ignora a ferramenta e responde com base na memória. A resposta estará errada com confiança assim que a sua infraestrutura mudar.

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

Em Options, também existe Max Iterations, que tem o valor padrão 10. Uma iteração é uma chamada ao modelo seguida de um resultado de ferramenta devolvido ao contexto. Portanto, uma execução do agente não corresponde a uma única chamada à API. Ela pode fazer até dez chamadas, e cada uma transporta 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 contínuo numa falha clara que pode ser consultada na lista de execuções.

Durante a depuração, ative Return Intermediate Steps. A saída final passa a incluir as chamadas de ferramenta feitas pelo agente. Assim, é possível distinguir entre “o modelo nunca chamou a ferramenta” e “a ferramenta não devolveu nada útil”. Desative essa opção antes de colocar o serviço em produção, porque essas etapas são ruído para o utilizador final.

Observe uma execução a partir da shell.

docker compose logs -f n8n

Impedir que um agente não supervisionado gaste silenciosamente

Um agente atrás de um Chat Trigger tem uma pessoa a acompanhá-lo, e essa pessoa interrompe-o quando a resposta parece incorreta. Um agente atrás de um Schedule Trigger não tem ninguém a monitorizá-lo. O que está a monitorizar aqui é o consumo do modelo, e não o custo de licenças, porque os nós de agente, ferramenta e memória funcionam na edição self-hosted gratuita, e as funcionalidades que precisam de uma chave paga são sobretudo as relacionadas com equipas e governação. A explicação completa está em Controlo de custos de agentes de IA numa VPS sempre ativa. Quatro definições fazem a maior parte do trabalho aqui.

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

Desative o workflow enquanto faz iterações. Um workflow ativo com um Schedule Trigger continua a ser executado com base na versão que o n8n guardou, que nem sempre é a versão apresentada no ecrã.

FAQ

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

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

O agente responde, mas nunca chama a 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. Por isso, uma descrição como "HTTP Request" não informa quando a ferramenta deve ser usada. Reescreva a descrição para indicar que dados são retornados e em que situação a ferramenta é útil. Depois, adicione uma linha à 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. A cada iteração, ele reenvia toda a conversa até ao momento, 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. Return Intermediate Steps mostra quantas etapas a execução realmente utilizou.

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

Verifique se a instância está a ser executada em modo de fila. Simple Memory armazena o histórico nos próprios dados de execução do workflow. Esses dados não persistem quando o workflow é entregue a um processo de trabalho 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 na base de dados partilhada por todos os processos de trabalho.