Grafo de Agentes
Ir para notas que citam estaGrafo de agentes é a representação de um fluxo como nós que executam trabalho e arestas que definem para onde a execução segue, com um ponto de entrada e um de saída explícitos.
É a estrutura central do LangGraph, que tira dela o próprio nome, e se apoia na teoria dos grafos da matemática. Funciona como o esqueleto do agente: toda a arquitetura mora nele, com as etapas, o que cada uma faz, a ordem e os caminhos possíveis. O contexto que circula entre as etapas não pertence ao grafo em si, e sim ao estado que ele carrega de nó em nó.
Nós: onde a inteligência reside
Um nó é uma função Python. Dentro dela ficam a chamada ao LLM, a consulta a uma base de conhecimento, a execução de uma ação ou de uma ferramenta. O nó recebe o estado como parâmetro, faz seu trabalho e devolve a atualização de uma parte dele.
A recomendação de desenho é manter os nós pequenos e específicos, pela mesma lógica dos sistemas multiagente: agentes trabalham melhor com pedaços pequenos. Num cadastro, é preferível um nó para o nome, outro para o telefone e outro para o endereço a um nó único que faz tudo.
Um nó só existe de fato dentro do grafo. A função pode estar definida, mas nunca roda se não estiver conectada na sequência. O mesmo vale depois de montado: um nó sem aresta que leve até ele nunca é alcançado, mesmo declarado. Isso dá previsibilidade ao fluxo e faz das conexões faltantes um erro típico de montagem.
Arestas: o caminho entre os nós
A aresta (edge) diz de onde a execução sai e para onde vai. A aresta normal é sequencial e não tem lógica: terminou este nó, segue para aquele. Quando o caminho depende de um valor, entra a Aresta Condicional, que funciona como um if sobre o estado: uma saudação vai para um nó, uma dúvida técnica para outro. Uma aresta também pode rotear a execução para duas operações ao mesmo tempo, o que dá paralelismo, e o fluxo pode ser cíclico, voltando a um ponto anterior para refazer uma etapa que falhou.
Um fluxo de exemplo mostra as peças juntas: um identificador de intenção decide entre três caminhos, saudação e fim; consulta de dúvida, validador e fim; ou plano de código, geração de código, avaliação e fim. Ao inserir um nó no meio de um fluxo existente, como o validador depois da consulta, é preciso redirecionar a aresta do nó anterior para o novo e criar outra aresta do novo nó até onde o fluxo continua.
Declarar, compilar e executar
Em código, a montagem segue sempre a mesma ordem. Cria-se um StateGraph informando a classe de estado. Cada agente vira um nó com add_node, que recebe um nome e a função; os nós são ligados com add_edge. As constantes START e END, nativas do LangGraph, marcam o começo e o fim para que o fluxo não se perca. Por fim o grafo é compilado com compile(), etapa obrigatória antes de executar e o ponto em que se liga a persistência. A execução com stream() recebe um dicionário com os dados iniciais e devolve os eventos um a um.
O nome passado em add_node é o identificador do nó; é ele que as arestas usam, não o nome da função Python. Envolver a função numa lambda permite repassar o estado e também parâmetros extras, como o resultado de uma consulta a banco para compor o prompt. Um erro comum é esquecer de retornar o grafo na função que o compila.
Grafo em código versus fluxo visual
Numa ferramenta visual, os nós equivalem às caixinhas do editor e as arestas às linhas que as ligam. Lá as caixinhas já existem prontas; no grafo em código é preciso primeiro prepará-las, com estado e agentes, e só então conectá-las. Em troca, o desenho do grafo vira uma barreira estrutural: se a validação falha, o fluxo simplesmente não tem aresta para as etapas seguintes, em vez de depender só do prompt para impedir o avanço. O trade-off completo está em N8N versus LangGraph.