Como Criar Um Agente de IA em 30 Minutos

Fonte: Unsplash

Trinta minutos é tempo de assistir a um episódio de série. Também é o tempo que falta entre abrir a ideia e ter um agente respondendo de verdade — desde que você não caia no buraco negro de comparar ferramenta, ler documentação infinita e desistir na configuração. Neste guia, o caminho é único: n8n, hospedado na sua própria máquina, com o nó de Agente de IA conectado a um modelo de linguagem. No fim, você terá um fluxo que lê uma pergunta, consulta uma fonte que você indicou e responde citando de onde tirou a informação.

Sem framework, sem Python, sem container quebrando. Se você já mexeu com planilha e sabe o que é um webhook, dá conta.

Passo 0 — O que você precisa ter em mãos (3 minutos)

Três coisas, todas obrigatórias:

Docker instalado — no Windows, Docker Desktop; no Mac, Docker Desktop; no Linux, o pacote padrão da sua distribuição.
Chave de API de um modelo — Anthropic (Claude), OpenAI ou outro provedor compatível. Você gera no painel deles e copia a chave.
Um arquivo de conhecimento — PDF, markdown ou texto com o assunto que o agente vai responder. Pode ser o manual da sua empresa, suas notas, um FAQ. Quanto mais objetivo, melhor.

Se algum desses itens faltar, pare aqui e resolva. Tentar contornar costuma custar bem mais tempo do que fazer direito.

Passo 1 — Subir o n8n em um comando (5 minutos)

Abra o terminal e rode:

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -e N8N_SECURE_COOKIE=false \
  docker.n8n.io/n8nio/n8n

Quando a linha com a URL aparecer, abra http://localhost:5678 no navegador e crie a conta local. Em produção você configuraria HTTPS e persistência de dados; para o tutorial, esse comando basta e some quando você para o container.

Dica de organização que economiza dor de cabeça depois: crie um workflow chamado "agente-faq" e salve antes de qualquer edição. O n8n salva automaticamente, mas o hábito de nomear cedo evita aquela pilha de "My workflow 12".

Passo 2 — A espinha dorsal do fluxo (7 minutos)

Um agente minimamente útil tem quatro nós. Monte nesta ordem:

Chat Trigger (gatilho de conversa) — é a tela de chat onde você faz a pergunta. Busque "Chat Trigger" na barra de nós.
AI Agent — o cérebro. Ele recebe a mensagem e decide o que fazer.
Modelo (Chat Model) — conecte ao nó AI Agent no campo Model. Escolha o provedor da sua chave e cole a credencial.
Fonte de conhecimento — no campo Tools do AI Agent, adicione um Vector Store Tool ou um Simple Memory Tool, dependendo do tamanho do seu material.

Conecte tudo: Chat Trigger → AI Agent → (retorno de resposta). O modelo e as ferramentas ficam ligados nos campos do próprio AI Agent, não em linha separada — é o erro de montagem mais comum de quem está começando.

Se a sua chave estiver configurada, o chat já responde. Mas responde "de cabeça", sem o seu material. É isso que o próximo passo corrige.

Passo 3 — Alimentar com a sua fonte (7 minutos)

Resposta sem fonte é chute bem escrito. Para amarrar o agente ao seu documento:

Adicione um nó Embeddings (por exemplo, o do provedor que você já está usando) e conecte a um Vector Store — o próprio n8n oferece opções locais, o que evita assinar outro serviço agora.
Crie um segundo fluxo (ou uma branch) com: Loaders de documento → Embeddings → Vector Store. Aponte para o seu PDF ou pasta.
Rode esse fluxo de ingestão uma vez. Ele quebra o texto em pedaços e indexa.
No AI Agent, no campo de ferramenta, adicione o Vector Store e escreva uma descrição honesta da ferramenta — ela é o que o modelo lê para saber quando usar a busca:

Descrição da ferramenta:
"Busca na base de documentos internos. Use SEMPRE que a pergunta
for sobre procedimento, regra, preço, prazo ou política interna.
Se não encontrar nada, responda que não há informação na base —
não invente."

Essa última frase não é enfeite. É o que separa um agente útil de um que improvisa. Modelo de linguagem não tem botão de "não sei"; alguém precisa dizer a ele para usar.

Passo 4 — Escrever a instrução de papel (4 minutos)

No campo System Message / Instructions do AI Agent, cole algo direto. Não precisa ser longo — precisa ser restrito:

Você é o assistente de dúvidas internas.
Responda em português, em no máximo 5 linhas.
Use a ferramenta de busca ANTES de responder qualquer pergunta
sobre procedimento ou dado da empresa.
Sempre cite o trecho ou documento de onde veio a resposta.
Se a busca não retornar nada, diga: "não encontrei na base".
Não invente nomes, valores, prazos ou pessoas.

Teste três perguntas agora: uma que exista na base, uma que não exista, e uma fora do assunto. O comportamento na segunda e na terceira pergunta diz mais sobre a qualidade do agente do que a primeira.

Passo 5 — Testar, ajustar e publicar (4 minutos)

Aperte Chat no canto superior e faça perguntas reais, inclusive mal redigidas — abreviação, erro de digitação, pergunta vaga. Você está testando duas coisas: se ele busca quando precisa e se ele admita não saber quando não tem.

Critérios para considerar pronto:

Responde com base no seu documento, não com conhecimento geral genérico.
Recusa responder fora do escopo de forma educada.
Não demora tanto que a pessoa perde a paciência (se demorar, reduza o tamanho do trecho buscado).
Registro de execução mostra o que foi consultado — abra o painel de execuções e confira.

Depois disso, publique: o n8n expõe o chat como página e também um webhook, que é o que você usaria para plugar no seu site, no WhatsApp Business ou numa planilha. Para o primeiro uso, a página de chat já basta.

Os três erros que quebram o fluxo no mesmo dia

Credencial no lugar errado. A chave vai na credencial do nó de modelo, nunca escrita dentro do texto do agente.
Ingestão esquecida. Você monta tudo, testa e o agente responde qualquer coisa. Nove em dez vezes é porque o Vector Store está vazio.
Instrução contraditória. Se o system message manda ser detalhado e a outra configuração pede respostas curtas, o modelo oscila. Uma fonte de verdade para as instruções.

Com o fluxo no ar, o próximo passo natural é estender: adicionar um gatilho por e-mail recebido, um nó que grava a conversa numa planilha, ou uma regra que encaminha para humano quando a confiança cai. Mas isso é assunto para a segunda semana. Hoje, você tem um agente de verdade rodando — e a parte difícil já passou.

E aí, fez sentido?

Conte nos comentários como foi seu primeiro agente no n8n — e se o artigo te ajudou, compartilhe com alguém que precisa ler. 👇