Como criar um agente de IA no n8n em VPS

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

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 memória opcional. Especifique um objetivo em linguagem simples, e o modelo decide que ferramentas deve chamar e em que ordem até conseguir responder. Tudo o que se segue é a configuração em torno dessa ideia.

Uma chain funciona ao contrário. Numa Basic LLM Chain, você define os passos e o modelo apenas preenche 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 única diferença determina todas as definições deste guia. Se este ciclo é uma ideia nova para si, e não apenas uma 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 passará o resto deste guia a raciocinar.

Isto 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 num Docker com um certificado real, porque a chave da API que está prestes a guardar precisa da cópia de segurança da chave de encriptação exigida por esse guia. Para os padrões sem agente, como sumarizadores com webhook e classificadores agendados, consulte padrões de workflows do Claude e do n8n.

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

docker compose exec n8n n8n --version

A versão 1.82.0 descontinuou a definição do tipo de agente em favor do Tools Agent. Os nós legados v1 ainda têm essa definição; a documentação do n8n prevê a remoção dessa versão do nó no n8n 3.0.

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

Coloque um nó AI Agent no canvas. O n8n mostra imediatamente um conector Chat Model vazio por baixo dele. Ligue nesse conector um subnó Anthropic Chat Model.

Crie a credencial na Claude Console, em platform.claude.com, através de Settings e depois API keys. A chave é apresentada apenas uma vez. A Console também pede que escolha uma data de expiração quando cria uma chave. Um agente sem supervisão deixa de funcionar no dia em que a chave expira. Registe essa data num local visível. Para um agente sem supervisão, use uma chave de conta de serviço com âmbito limitado a um workspace. Assim, os pedidos não precisam de um cabeçalho de workspace separado.

A utilização da API é faturada por token. A forma de pagamento depende do seu plano Claude, em 31 October 2026. Os planos Max, Ultra e Team incluem créditos mensais para a API: $100 no Max, $200 no Ultra e até $500 partilhados no Team. Para os utilizar, associe uma organização da Console ao plano em Settings > Billing no Max ou Ultra, ou em Organization settings > Billing no Team. Não precisa de adicionar um método de pagamento na Console. Os novos subscritores podem utilizar os créditos depois de 7 dias no plano. Os créditos não utilizados expiram no final de cada ciclo de faturação, ou mensalmente nos planos anuais. Quando os créditos incluídos acabam, os pedidos continuam a utilizar créditos comprados. O auto-reload pode comprar mais créditos, e as organizações faturadas recebem uma fatura pela utilização excedente. Os pedidos param quando uma organização pré-paga fica sem créditos. A utilização da API nunca é cobrada ao seu plano Claude. Os planos Free, Pro e Enterprise não incluem créditos mensais para a API. Nesses planos, a API é faturada separadamente da subscrição.

Escolha o modelo por agente, não por empresa. Um agente com uma ferramenta que consulta algo e apresenta o resultado funciona bem com Haiku. A versão atual, Haiku 5.5, tem o preço indicado de $0.10 por milhão de tokens de entrada e $0.50 por milhão de tokens de saída em 12 October 2026. O preço sobe para $0.50 e $2.50 em qualquer pedido cujo prompt ultrapasse 100,000 tokens. Uma janela de memória longa e resultados extensos das ferramentas podem fazer com que ultrapasse esse limite. Quando o agente tiver várias ferramentas e precisar de planear entre elas, mude para Sonnet. O problema que deve evitar é um modelo barato chamar a ferramenta errada quatro vezes. Isso pode custar mais do que usar o modelo caro para chamar a ferramenta correta uma vez.

Defina Maximum Number of Tokens nas opções do subnó. Este parâmetro limita o comprimento 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 ressalva na documentação do n8n que causa problemas frequentes: as expressões dentro de um subnó são sempre resolvidas com base no primeiro item de entrada, nunca por item. Coloque as expressões por item nos campos de prompt do nó raiz.

Etapa 3: o prompt que o agente recebe

Abra o nó AI Agent. O parâmetro Source for Prompt (User Message) tem duas opções.

• Connected Chat Trigger Node 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 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.

Passo 4: forneça uma ferramenta ao agente

A documentação do n8n indica que é necessário ligar pelo menos um subnó de ferramenta a um nó AI Agent, embora o código atual do nó (versão 3.1) apenas impeça a execução quando não existe um modelo de chat. Comece com uma ferramenta de qualquer forma, porque uma única ferramenta funcional ensina mais do que quatro ferramentas parcialmente configuradas, e um agente sem ferramentas é apenas uma chain mais dispendiosa.

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 vai 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. O modelo lê esse campo juntamente com o nome da ferramenta e o esquema dos parâmetros para decidir se a ferramenta é relevante. Escreva uma afirmação simples sobre o que é 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 funciona apenas em ferramentas ligadas a um nó AI Agent e não funciona na ferramenta Code.

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

Os argumentos são key, seguidos opcionalmente por description, type e defaultValue. A chave deve ter entre 1 e 64 caracteres e usar letras, dígitos, sublinhados e hífenes. O tipo deve ser um de string, number, boolean ou json, e o valor predefinido é 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 em nenhum local. Indica ao modelo para "produzir um valor e chamá-lo service", e o modelo procura esse valor na conversa, nos dados de entrada e nos resultados de outras ferramentas. Num workflow de chat, pode simplesmente pedi-lo 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 do SearXNG em vez de uma API de pesquisa paga, desde que trate todas as páginas devolvidas como texto não fiável que passa a estar dentro do seu prompt.

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

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

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

Context Window Length é tanto um controlo de custo como de qualidade, porque cada turno guardado é reenviado como tokens de entrada em todas as chamadas seguintes. Uma janela de 20 num agente muito conversador significa pagar vinte vezes pelas mesmas mensagens iniciais.

Simple Memory não funciona num workflow de produção ativo quando o n8n é executado em modo de fila, porque guarda o histórico num Map singleton local ao processo, indexado pelos IDs do workflow e da sessão, e os workers não partilham essa memória. Numa instância em modo de fila, use o subnó Postgres Chat Memory e aponte-o para uma base de dados que tanto o processo principal como os workers consigam alcançar.

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 num loop e o que o interrompe

Também em Opções está Máximo de iterações, que tem o valor predefinido de 10. Uma iteração corresponde a uma chamada ao modelo, que solicita ferramentas ou devolve a resposta final; os resultados das ferramentas são enviados para a chamada seguinte. Portanto, uma execução do agente não corresponde a uma única chamada à API. 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, visível na lista de execuções.

Enquanto estiver a depurar, ative Devolver passos intermédios. A saída final passa a incluir as chamadas às ferramentas feitas pelo agente. Assim, pode distinguir entre “o modelo nunca chamou a ferramenta” e “a ferramenta não devolveu nada útil”. Desative esta opção antes de colocar o sistema em produção, porque esses passos 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 ligado a um Chat Trigger tem uma pessoa a supervisioná-lo, e essa pessoa interrompe-o quando a resposta parece errada. Um agente ligado a um Schedule Trigger não tem ninguém a observá-lo. Neste caso, o que está a monitorizar é o consumo do modelo, não o custo da licença, porque os nós do agente, das ferramentas e da memória funcionam na edição self-hosted gratuita, e as funcionalidades que precisam de uma chave paga são sobretudo as de equipa e governação. O tratamento completo está em Controlar os custos de agentes de IA num VPS sempre ligado. Quatro definições resolvem a maior parte do problema.

• 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 devolva um objeto JSON com 4,000 linhas coloca todo esse conteúdo na chamada seguinte ao modelo e, depois, em todas as chamadas seguintes da mesma execução.
• Verifique se o agente precisa realmente de um agendamento. Um job executado a cada cinco minutos é acionado 288 vezes por dia. Multiplique o custo de uma execução por esse número.

Retire o workflow de publicação enquanto faz alterações ou, pelo menos, confirme qual é a versão publicada. Um workflow publicado com um Schedule Trigger continua a executar a última versão publicada, não o rascunho apresentado no ecrã, porque o n8n mantém as alterações em rascunho até serem publicadas novamente.

FAQ

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

Verifique primeiro os conectores. O nó AI Agent precisa de um subnó de modelo de chat. Sem esse subnó, para com a mensagem "Please connect a model to the Chat Model input" antes de fazer qualquer chamada à API. A documentação do n8n também indica que é necessário pelo menos um subnó de ferramenta. Portanto, se o modelo estiver ligado e o nó continuar a recusar a execução, adicione uma ferramenta, mesmo que seja trivial, e execute 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 se aplica. Reescreva-a para indicar que dados são devolvidos e em que situação a ferramenta é útil. Em seguida, adicione uma linha à System Message a instruir o agente a chamar essa ferramenta antes de responder.

Por que a mesma pergunta tem um custo diferente em cada execução?

Porque o modelo escolhe o número de etapas. Em cada iteração, toda a conversa até esse momento é enviada novamente, incluindo a saída anterior da ferramenta. Assim, uma execução que demora quatro iterações cobra os tokens de entrada e de saída das quatro chamadas. Max Iterations define o limite máximo. Return Intermediate Steps mostra quantas etapas a execução utilizou efetivamente.

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

Verifique se a instância está a executar em modo de fila. Simple Memory armazena o histórico num Map singleton local ao processo, indexado pelos IDs do workflow e da sessão. Processos de worker separados não partilham esse Map. Substitua-o pelo subnó Postgres Chat Memory, que mantém o histórico na base de dados partilhada por todos os workers.