Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

Estado do Grafo

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Estado do grafo é a estrutura de dados compartilhada que guarda todo o contexto de um agente no LangGraph durante a execução, lida e atualizada por cada nó do fluxo.

Se o grafo é o corpo do agente, o estado é o coração. Sem ele o agente não tem contexto nenhum: não sabe quem é, por que foi acionado nem o que precisa fazer. É o estado que permite a um chat responder, no fim da conversa, o nome que o usuário informou na primeira mensagem.

Um dicionário tipado que atravessa todos os nós

O estado é um dicionário Python de chave e valor, declarado como uma classe que herda de TypedDict. Cada campo tem nome e tipo, como a pergunta do usuário em str. A tipagem existe porque o grafo não infere a forma do estado: ao criar o StateGraph é obrigatório informar a classe de estado, e assim todos os nós concordam sobre quais chaves existem e o que cada uma guarda.

Cada nó recebe o estado inteiro como parâmetro, lê o que precisa como se lê qualquer dicionário (state["user_query"]) e devolve apenas os campos que mudou, num dicionário parcial. O LangGraph mescla esse retorno no estado global. Um nó pode não alterar nada, mas sempre tem acesso a tudo, e esse acesso não se limita ao que o nó anterior escreveu: qualquer nó lê qualquer campo em qualquer ponto do fluxo. É isso que permite encadear agentes, como um validador que lê a resposta de um consultor para julgá-la, ou um avaliador que junta o plano e o código gerado numa única mensagem ao modelo. Como nem todo campo está preenchido o tempo todo, vale verificar antes de usar.

Histórico de mensagens e um campo por agente

Os dois campos mais comuns são a mensagem que chegou do usuário e o histórico total das mensagens. O histórico costuma morar no estado porque é dele que o agente tira o contexto da conversa. Ele é declarado como Annotated[list, add_messages]: a função add_messages faz cada nova mensagem ser acumulada à lista em vez de substituí-la. Um campo simples, sem função de acumulação, guarda só o valor mais recente.

Daí a convenção de dar a cada agente o seu próprio campo de resposta, como uma chave para o identificador de intenção e outra para o agente de saudação. Dois nós que escrevem em sequência no mesmo campo simples fazem o segundo apagar o que o primeiro gravou; com um campo por agente, ninguém sobrescreve ninguém, e a última resposta de um agente específico fica à mão sem vasculhar o histórico.

O número de campos não está preso ao número de nós. Um grafo de nove nós pode ter onze campos (a mensagem do usuário, o histórico e uma resposta por nó) e ainda outros, como um resumo da conversa ou o nome do interlocutor. Num agente que avalia atendimentos de customer service, três campos bastaram: a entrada do cliente, a resposta do atendente e uma avaliação de bom ou mau atendimento, usada depois para métricas de qualidade.

Estado em memória e o preço do contexto

Por padrão o estado vive só em memória. Quando o programa é encerrado, tudo se perde, e cada nova mensagem passa a ser tratada como uma conversa nova, sem lembrança da anterior. Guardar o estado entre execuções é o papel dos checkpoints, que o salvam em banco de dados associado a um identificador de conversa.

Grave só o que vai ser usado

O estado registra apenas o que for pedido explicitamente. Guardar só o texto da resposta do modelo é o caso comum; guardar a estrutura completa da resposta ajuda a analisar cada passo, ao custo de código mais complexo. Um modelo que lida mal com contexto extenso aproveita pouco um estado inchado de informação sem utilidade.

No N8N, o equivalente são as execuções guardadas no banco interno da ferramenta, de acesso pouco direto. No LangGraph o estado inteiro está ao alcance de qualquer nó, e essa gerência de contexto é o ponto mais forte do framework.