Checkpoints e Persistência de Estado
Ir para notas que citam estaCheckpoints e Persistência de Estado é o mecanismo do LangGraph que grava em banco, por conversa, o estado e as mensagens de cada passo do fluxo, para retomá-los depois.
No LangGraph, o estado é um dicionário que vive enquanto o programa roda: guarda a pergunta do usuário, a resposta de cada nó e um campo padrão com o histórico das mensagens da execução. Quando o programa é encerrado, tudo isso some. A próxima mensagem seria tratada como conversa nova, sem memória do que veio antes, e não haveria como analisar o que os agentes fizeram. O checkpointer salva o estado de forma estruturada e ordenada fora do processo, o que dá ao agente memória entre interações.
O nome vem dos jogos: um checkpoint é um ponto salvo ao qual se pode voltar sem refazer as fases anteriores. Outra imagem útil é a de uma thread de rede social ou do histórico de um chat: a partir da primeira mensagem, as seguintes ficam ligadas a ela e em ordem.
Thread ID: a identificação de cada conversa
Cada conversa persistida é identificada por um thread ID único, ao qual ficam ligadas todas as mensagens trocadas com o agente. Ao lado dele, checkpoint_ns e checkpoint_id completam o conjunto de identificadores de um checkpoint.
O thread ID vai na chamada de execução do grafo, numa configuração em forma de dicionário: a chave configurable contém outro dicionário com thread_id. Se o grafo foi compilado com checkpointer e a execução não recebe essa configuração, o LangGraph lança um erro pedindo thread_id, checkpoint_ns e checkpoint_id. Um descuido típico é montar a configuração e esquecer de passá-la ao grafo.
Sem front-end, um inteiro aleatório serve para testar. Numa aplicação real, o thread ID vem do chat criado pelo usuário na interface, para que cada conversa tenha o próprio histórico.
Memória para teste, banco de dados para uso real
Há checkpointer em memória, suficiente para experimentar, mas que não sobrevive ao encerramento do programa. Para persistir de verdade, usa-se um banco. Com PostgreSQL, são quatro passos:
- Instalar o pacote de checkpoint do LangGraph para Postgres e o driver psycopg com o extra binary, porque o pacote de checkpoint não se conecta sozinho ao banco.
- Guardar host, porta, nome do banco, usuário e senha em variáveis de ambiente (DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD), carregadas com load_dotenv, e criar a conexão num módulo utilitário, com autocommit ligado.
- Instanciar o PostgresSaver com essa conexão e passá-lo no parâmetro
checkpointerao compilar o grafo. - Chamar
setup()no checkpointer, que cria as tabelas se ainda não existirem, sem esquema desenhado à mão.
Daí em diante, cada execução grava nas tabelas cada mensagem trocada entre os agentes, sem mudar nada na saída do programa. Em troca, cada passo do fluxo passa a gerar escrita no banco.
DB_NAME precisa ser um banco que existe de fato no serviço. Se ele foi criado por um Docker Compose com outro nome, a conexão falha antes de qualquer checkpoint.
O que a persistência permite fazer
A primeira vantagem é retomar sem reprocessar. Se um agente produziu parte de um relatório, dá para consultar o trecho direto no checkpoint, sem que os agentes refaçam o trabalho. Num fluxo longo que falha no meio, por exemplo com um HTTP 404 numa chamada de API, volta-se ao ponto salvo anterior, vê-se qual chamada falhou e tenta-se de novo, em vez de reiniciar tudo. Um assistente também pode voltar o contexto a uma mensagem passada e refazer o atendimento dali. Pelo mesmo motivo, o estado salvo por thread é a base para pausar um fluxo à espera de decisão em padrões de Human in the Loop.
A segunda vantagem é analisar. As tabelas não guardam logs soltos, e sim a resposta gerada em cada ponto da conversa, ligada ao thread ID. Isso permite rastrear ponto a ponto a execução e achar em que nó do grafo um agente respondeu mal, o que liga o checkpoint à observabilidade. Sem essa persistência, um protótipo de agente esquece o contexto a cada mensagem; por isso ela é um dos pontos que tornam agentes viáveis em produção.