n8n: Um guia com exemplos práticos

n8n surgiu como uma estrutura popular e poderosa em IA agêntica. Ele nos permite criar fluxos de trabalho automatizados sem a necessidade de codificação complexa.

Neste artigo, explicarei passo a passo como você pode aproveitar ao máximo essa plataforma robusta para automatizar dois processos distintos:

1. Primeiro, vou orientar você na configuração de um agente de IA para processar automaticamente e-mails do Gmail, economizando tempo valioso e reduzindo o esforço manual.
2. Em seguida, criaremos um agente inteligente que poderá conversar sobre qualquer documento, fornecendo acesso rápido às informações na ponta dos dedos.

Mantemos nossos leitores atualizados sobre as últimas novidades em IA enviando o The Median, nosso boletim informativo gratuito de sexta-feira que detalha as principais histórias da semana. Inscreva-se e fique atento em apenas alguns minutos por semana:

O que é a n8n?

A n8n é uma ferramenta de automação de código aberto que nos ajuda a conectar vários aplicativos e serviços para criar fluxos de trabalho, como uma linha de montagem digital. Ele permite que os usuários projetem visualmente esses fluxos de trabalho com nós, cada um representando uma etapa diferente do processo.

Com a n8n, podemos automatizar tarefas, gerenciar o fluxo de dados e até mesmo integrar APIs, tudo isso sem a necessidade de grandes habilidades de programação. Aqui está um exemplo de uma automação que criaremos neste tutorial:

Sem entrar em detalhes, aqui está uma descrição do que essa automação faz:

1. Ele acessa nossa conta do Gmail para verificar se há novas mensagens de e-mail.
2. Novos e-mails são enviados ao ChatGPT para processamento de IA.
3. A IA identifica as informações relevantes, que são salvas em uma planilha.

Como usar o n8n?

Você tem duas opções para usar o n8n:

1. Use a interface da Web aqui. Isso requer uma conta e uma assinatura paga, mas há uma avaliação gratuita de 14 dias que você pode usar para seguir este tutorial.
2. Como ele é de código aberto, também podemos executá-lo localmente ou hospedá-lo nós mesmos. Você tem acesso gratuito a quase todos os seus recursos (alguns recursos são exclusivos dos planos pagos de nuvem ou empresariais).

Ambas as opções permitem que você siga este tutorial sem nenhum custo. Vamos executá-lo localmente, mas se você preferir usar a interface da Web, as etapas são as mesmas.

Configuração local do n8n

O repositório oficial do n8n explica como você pode configurar o n8n localmente. A maneira mais simples é você:

1. Faça o download e instale o Node.js em site oficial.
2. Abra um terminal e execute o comando npx n8n.

É isso aí! Depois de executar o comando, você deverá ver isso no terminal:

Para abrir a interface, pressione "o" no teclado ou abra o URL do host local mostrado no terminal - no meu caso, http://localhost:5678.

Entendendo o n8n

Antes de criarmos nossa primeira automação, é bom que você entenda como o n8n funciona. Um fluxo de trabalho n8n consiste em uma sequência de nós. Ele começa com um nó de acionamento que especifica uma condição para que o fluxo de trabalho seja executado.

Os nós se conectam para mover e processar dados. Neste exemplo, o nó de acionamento do Gmail se conecta a um nó da OpenAI. Isso significa que o e-mail é fornecido ao ChatGPT para processamento. Por fim, a saída do ChatGPT é enviada para um nó do Google Sheet, que se conecta a um Google Sheet em nosso Google Drive e grava uma nova linha em uma planilha.

Esse fluxo de trabalho específico usa o ChatGPT para identificar faturas que precisam ser pagas e atribui uma linha na planilha com o ID da fatura e o preço.

Os fluxos de trabalho da n8n podem ser muito mais complexos. A n8n oferece suporte a mais de 1.047 integrações, portanto, não podemos abordar todas elas em um tutorial. Em vez disso, vou me concentrar em dar a você uma ideia geral de como ele funciona e a base necessária para explorá-lo por conta própria. Se houver uma ferramenta que você usa regularmente, é provável que o n8n seja compatível com ela ou que você possa integrá-la manualmente.

Exemplo 1: Automatização do processamento de faturas por e-mail

Nesta seção, aprenderemos como criar o fluxo de trabalho acima.

Esse é um caso de uso real que utilizo para gerenciar minhas faturas de aluguel. Tenho uma casa com alguns quartos que alugo. As contas são divididas igualmente entre todos os locatários. Sempre que recebo uma fatura, preciso adicionar o total a uma planilha que é compartilhada com meus locatários.

Tenho um endereço de e-mail específico para o qual as faturas relacionadas às contas da casa são encaminhadas. Dessa forma, sei que todos os e-mails dessa caixa de correio correspondem a uma fatura. Eu envio o conteúdo do e-mail para o ChatGPT para que você identifique o ID da fatura e o valor total a ser pago. Em seguida, essas informações são adicionadas a uma nova linha na planilha compartilhada.

Configuração do acionador de e-mail

Para iniciar um novo fluxo de trabalho, você precisa clicar no botão "Adicionar primeira etapa...".

Como esse é o primeiro nó, ele deve ser um acionador, portanto, você verá um painel para selecionar um nó de acionador. Um nó de acionamento define as condições para que o fluxo de trabalho seja executado.

Há uma ampla gama de possíveis nós de acionamento. Vamos selecionar um nó de acionamento do Gmail digitando "gmail" na caixa de pesquisa e clicando no nó Gmail.

Em seguida, escolhemos o único acionador disponível para o Gmail: "Na mensagem recebida".

Isso abrirá o painel de configuração do nó, onde precisamos configurar nossas credenciais do Gmail para permitir que o fluxo de trabalho do n8n acesse nossa conta do Gmail. Para fazer isso, clique em "New credential" (Nova credencial). Isso abrirá a seguinte janela:

No lado direito (1), há um guia de configuração que explica as etapas necessárias para configurar as credenciais no Nuvem do Google. Os guias fornecidos pela n8n são bastante abrangentes, portanto, não repetiremos as etapas aqui. Certifique-se também de ativar a API do Gmail no Google Cloud Console.

Quando estiver configurado, você precisará copiar o ID do cliente (2) e o segredo do cliente (3) do Google Cloud para a configuração de credenciais do n8n.

Para garantir que tudo esteja configurado corretamente, podemos testar o nó clicando em "Fetch Test Event".

Após o teste, devemos ver o e-mail mais recente que recebemos em nossa caixa de entrada na seção de saída. O conteúdo do e-mail é o campo snippet.

O campo snippet armazena o conteúdo do e-mail. Ele diz que minha fatura de internet de abril está disponível. Ele fornece o ID da fatura e o valor total a ser pago. Essas são as informações que queremos adicionar à planilha. 

Para fins de teste, recomendo que você fixe a saída clicando no botão de fixação no canto superior direito:

Isso bloqueará o resultado para o acionador, o que significa que sempre que executarmos esse fluxo de trabalho, essa mesma saída será usada, facilitando o teste do fluxo de trabalho porque os resultados não serão afetados por nenhum novo e-mail que possamos receber. Você poderá retirá-lo do pino assim que o fluxo de trabalho for configurado corretamente.

Nesse estágio, nosso fluxo de trabalho deve ter um único nó de acionamento (podemos ver que é um nó de acionamento por causa do pequeno marcador de raio à esquerda).

Observe que, como você provavelmente não terá uma fatura de e-mail em sua caixa de correio, mais tarde, o ChatGPT provavelmente lhe dará uma resposta que não faz sentido. Se quiser testar exatamente esse fluxo de trabalho, você pode enviar a si mesmo um e-mail de teste com o seguinte conteúdo (ou algo semelhante):

Dear customer,

Your internet invoice number FT 2025**/****** for April is now available in the attachment.

Amount

€**.**
This invoice must be paid by 19/05/2025.

Depois de enviar isso, você deve retirar a fixação do resultado, executar novamente o nó do Gmail e fixar o novo resultado.

Configurando o nó do ChatGPT

A próxima etapa é configurar o nó do OpenAI. Comece clicando no botão "+" à direita do nó do acionador do Gmail:

Digite "OpenAI" e selecione a opção correspondente na lista.

Em seguida, em "Text Actions" (Ações de texto), selecione o nó "Message a model" (Mensagem para um modelo). Esse nó é usado para enviar mensagens a um LLM.

Como antes, precisamos criar uma credencial para acessar o OpenAI. Observe que, depois que uma credencial é criada, ela pode ser reutilizada em qualquer fluxo de trabalho. Você não precisa configurá-lo todas as vezes.

Para a credencial da OpenAI, tudo o que você precisa é de uma chave de API. Se não tiver um, você pode criar um aqui. Se você tiver problemas para fazer isso, o n8n também fornece um guia para isso.

Em termos de configuração, precisamos selecionar o modelo de IA que queremos usar e a mensagem que enviamos ao modelo. Para o modelo, podemos usar o GPT 4.1:

No campo de mensagem, precisamos fornecer o prompt. Neste exemplo, fornecemos ao modelo o conteúdo do e-mail e pedimos que ele identifique o ID da fatura e o valor total a ser pago. Aqui está o prompt que usei:

O conteúdo do e-mail é fornecido como {{ $json.snippet }}. No n8n, o prompt pode conter variáveis que são preenchidas a partir da saída de nós anteriores, o e-mail no nosso caso. A lista de campos disponíveis pode ser vista à esquerda. Você pode digitar o campo manualmente ou arrastá-lo e soltá-lo no prompt.

Para testar isso, clicamos no botão "Test Step" (Etapa de teste) na parte superior do painel de configuração. O resultado é exibido à direita:

O resultado é uma cadeia de caracteres com a resposta do modelo. Gostaríamos de ter os dois campos separadamente, para não precisarmos processar a mensagem posteriormente. Você pode conseguir isso alterando a saída do LLM para JSON:

Ao testar essa etapa novamente, você obtém os dois campos como dados JSON:

Enviando os dados para uma planilha do Google

A etapa final desse fluxo de trabalho é enviar o ID e o preço da fatura para uma nova linha em uma planilha do Google. Nesta etapa, precisamos conectar a saída do nó do OpenAI ao Google Sheets. Fazemos isso como antes, clicando no botão "+" à esquerda do nó:

Aqui, você deve digitar Google Sheets e selecionar o nó "Append row in sheet" (Anexar linha na planilha):

Você pode usar as mesmas credenciais que usou para acessar o Gmail. Mas precisamos ativar as seguintes APIs no Console do Google Cloud:

• Google Sheets API
• API do Google Drive

Para configurar o nó do Google Sheets, precisamos selecionar a planilha e os valores para preencher os campos. A planilha deve ser criada manualmente com duas colunas, uma para conter o ID da fatura e outra para o total da fatura.

Esses valores são obtidos da saída do nó OpenAI. Você pode arrastá-los e soltá-los nas colunas.

Executar o fluxo de trabalho

É isso aí! Temos um fluxo de trabalho que processa automaticamente nossas faturas em uma planilha do Google. Você pode testá-lo clicando em "Testar fluxo de trabalho" na parte inferior:

Depois de executá-lo, se você acessar a Planilha do Google, verá uma nova linha com os dados:

Por padrão, um fluxo de trabalho será executado a cada minuto. Dependendo do fluxo de trabalho, devemos configurar uma frequência apropriada para que ele seja executado. Nesse exemplo específico, uma vez por minuto é muito frequente. Uma vez por dia é uma frequência mais apropriada. 

Você pode configurar isso clicando duas vezes no nó do acionador e definindo um valor diferente no campo "Poll Times":

Exemplo 2: Criação de um agente RAG

Nesta seção, criamos um fluxo de trabalho de agente RAG mais complexo. RAG significa geração aumentada por recuperação, uma técnica que combina a recuperação de informações relevantes de um banco de dados ou documento e, em seguida, o uso de um modelo de linguagem para gerar respostas com base nas informações recuperadas.

Isso é muito útil quando temos uma base de conhecimento específica, como um documento de texto longo, e queremos criar um agente de IA capaz de responder a perguntas sobre ele. 

Gosto de jogar jogos de tabuleiro, mas meus amigos e eu geralmente discutimos sobre as regras e passamos o tempo procurando as regras corretas em vez de jogar, o que pode ser frustrante. A criação de um agente RAG com base nas regras do jogo é uma boa solução para resolver esse problema porque, da próxima vez que tivermos uma dúvida, podemos simplesmente perguntar ao agente.

Para criar esse agente, faremos dois fluxos de trabalho:

1. Um fluxo de trabalho que será executado apenas uma vez para carregar os dados em um banco de dados Pinecone.
2. Outro que alimenta o agente RAG e usa o banco de dados Pinecone para responder às nossas perguntas.

Carregando os dados no Pinecone

Pinecone é um tipo de banco de dados que gerencia dados na forma de vetores. Um banco de dados vetorial como o Pinecone é ótimo para nosso agente RAG porque ajuda o agente a procurar e entender rapidamente as informações relevantes, tornando-o mais eficiente no fornecimento de respostas precisas.

Como só precisamos executar esse fluxo de trabalho uma vez, podemos usar um nó de acionamento manual. Esse é um nó de acionamento usado para executar manualmente um fluxo de trabalho. 

Conecte o nó de acionamento manual a um nó do "Google Drive" para fazer o download dos dados do Google Drive. 

Use a seguinte configuração:

Usei o arquivo mtgrules.txt disponível publicamente com as regras do jogo de cartas Magic: The Gathering. Você pode usar qualquer arquivo sobre o qual gostaria de fazer perguntas; o fluxo de trabalho é o mesmo.

Para configurar o Pinecode, faça login no Pineconecopie a chave da API e crie um índice clicando no botão "Criar índice". Liguei para o meu índice rules e selecionei o modelo text-embedding-3-small.

De volta ao n8n, conecte a saída do nó do Google Drive a um nó do Pinecone Vector Store para a ação "Add documents to vector store" (Adicionar documentos ao armazenamento de vetores):

Para configurar o nó, precisamos criar uma credencial colando a chave da API e selecionando o Pinecone Index que acabamos de criar. Abaixo do nó Pinecone Vector Store, vemos duas coisas que precisamos configurar: um modelo de incorporação e um carregador de dados.

Para a incorporação, crie um nó OpenAI Embedding com o modelo text-embedding-3-small:

Para o carregador de dados, criamos um nó Default Data Loader com um tipo de dados binário:

Por fim, o carregador de dados requer um nó Text Splitter, que especifica como os dados do arquivo devem ser divididos ao criar o armazenamento de vetores. Usamos o nó Recursive Character Text Splitter, que é o nó recomendado para a maioria dos aplicativos.

Nós o configuramos para usar um tamanho de bloco de 1.000 e uma sobreposição de bloco de 200:

Ao escolher o tamanho e a sobreposição dos pedaços, considere o uso de um tamanho de pedaço maior para documentos extensos a fim de capturar o conteúdo adequado e uma sobreposição menor para manter o contexto entre os segmentos sem redundância.

Esta é a aparência do fluxo de trabalho final:

Você pode executá-lo clicando em "Test workflow" (Testar fluxo de trabalho) e, uma vez concluído, podemos verificar no Pinecone se os dados foram carregados.

Criação de um agente RAG

Aqui está o esquema final do agente RAG:

Como exercício, incentivo você a tentar entendê-la e talvez até recriá-la localmente antes de continuar lendo.

Começamos com um nó de acionamento "On chat message". Isso é usado para criar um fluxo de trabalho de bate-papo.

Em seguida, conectamos o acionador de bate-papo a um nó "AI Agent" com as opções padrão.

Abaixo do AI Agent, vemos que podemos configurar três coisas:

• O modelo de IA usado pelo agente.
• A memória define como o agente se lembra do contexto da conversa
• As ferramentas às quais o agente tem acesso. Nesse caso, forneceremos o banco de dados Pinecone como uma ferramenta para que o agente possa responder a perguntas sobre nosso documento.

Para o modelo de IA, selecionamos um nó "OpenAI Chat Model" e usamos o modelo gpt-4.1:

Para a memória, usamos um nó "Memória simples" com uma janela de contexto de comprimento 5. Isso significa que o agente se lembrará e considerará as cinco interações anteriores ao responder.

Por fim, na ferramenta, adicionamos um nó "Pinecone Vector Store" com a seguinte configuração:

No campo de descrição, é importante especificar quando as ferramentas devem ser usadas. Isso é o que o agente usará para determinar se deve chamar a ferramenta.

A última coisa de que precisamos é configurar a incorporação usada pelo armazenamento de vetores. Como antes, usamos um nó OpenAI Embedding com o modelo text-embedding-3-small:

O fluxo de trabalho está concluído e você pode conversar com o agente. Aqui está um exemplo:

Podemos ver à direita as etapas que o agente realizou para responder à nossa pergunta. Em particular, ele acessou o banco de dados Pinecone para buscar as informações relevantes sobre as regras.

Modelos n8n

O n8n oferece um recurso útil que pode acelerar significativamente o processo de criação do fluxo de trabalho: a biblioteca de modelos do n8n.

Essa biblioteca é uma coleção de fluxos de trabalho pré-construídos, criados pela comunidade e por especialistas da n8n. Quer estejamos tentando automatizar tarefas simples ou processos mais complexos, é provável que alguém já tenha criado um fluxo de trabalho adequado às nossas necessidades.

Importar um fluxo de trabalho para nossa configuração da n8n significa que nem sempre precisamos começar do zero. Em vez disso, podemos aproveitar as soluções criativas que outros usuários desenvolveram. Depois de importar um fluxo de trabalho, tudo o que precisamos fazer é configurá-lo com nossas credenciais e ajustá-lo para atender às nossas necessidades exatas.

Para qualquer tarefa que desejamos automatizar, desde o processamento de e-mails até o gerenciamento de mídias sociais, é muito provável que haja um modelo disponível na biblioteca.

Conclusão

A n8n oferece um vasto ecossistema de integrações, o que nos permite conectar mais de mil serviços e ferramentas para criar agentes de IA. Neste tutorial, você só viu a superfície do que o n8n pode fazer. Ao explorar como usar o n8n para criar agentes de IA para automatizar tarefas cotidianas, estamos apenas começando a explorar seu potencial.