Checkpointers de LangGraph para persistir estado en Postgres

Evita que tu agente olvide cada interacción: con los checkpointers de Landgraph puedes guardar y derivar el estado de la conversación en una base de datos Postgres usando Docker, y controlar la concurrencia con un thread ID bien definido. Aquí aprenderás a instalar la librería, levantar Postgres y aplicar políticas de threads para que tu endpoint recuerde a cada usuario.

¿Qué resuelve un checkpointer de Landgraf y por qué importa?

Un agente sin memoria no avanza ni recuerda el nombre del usuario. Durante el debugging en Landgraph Studio hay memoria temporal, pero en un endpoint real el estado no se guarda. Un checkpointer crea un snapshot o screenshot del diálogo, lo asocia a un thread ID y lo persiste en una base de datos para restaurar: mensajes, memoria compartida y el nodo en el que quedó la ejecución.

• El agente no recuerda por defecto: sin estado persistente, cada pregunta empieza de cero.
• Checkpointer: guarda snapshots por thread para saber hacia dónde continuar o devolver la conversación.
• Base de datos: necesaria para recuperar el estado al consultar por thread ID.
• Concurrencia: cada usuario mantiene su propio estado sin interferir con otros.

¿Cómo funciona el guardado del estado por thread ID?

El thread ID define a quién pertenece la conversación y cuál estado cargar. Se pasa en la invocación del agente: “lo vamos a pasar a nivel de invoke, entonces siempre lo vamos a pasar aquí”. Cambias de conversación cambiando el ID; retomas un chat reutilizando el mismo ID.

¿Qué bases de datos e integraciones se mencionan?

• Oficialmente mantenidos por el equipo: Postgres y uno para SQL Lite. Recomendado usar Postgres por fiabilidad.
• Integraciones de la comunidad: Django, Dynamo, Firestore, entre otras, no mantenidas directamente por el equipo.

¿Cómo instalar la librería y levantar Postgres con Docker?

Primero instala la librería del checkpointer y prepara una base de datos Postgres con Docker. Luego conecta la librería a la base de datos para que persista los estados.

• Instalar la librería con UV.
• Crear un archivo dockercompose.yaml para Postgres.
• Quitar servicios innecesarios del compose como el visualizador.
• Levantar contenedores en segundo plano.
• Verificar que Postgres está arriba.
• Opcional: revisar en docker dashboard qué está corriendo.

¿Qué comandos necesitas?

# Instalar la librería del checkpointer
uv add landgraf checkpoint postgres

# Levantar Postgres con Docker en modo detach
docker compose up -d

# Verificar servicios activos
docker compose ps

¿Cómo pasar el thread ID al agente?

Configura el agente para recibir el thread ID en cada invoke. Es el identificador que decide qué estado cargar, de quién es la conversación y dónde retomar. Cambia el ID para empezar un hilo nuevo o reutilízalo para continuar el mismo.

¿Qué políticas de thread ID mejoran memoria y concurrencia?

Definir políticas de threads es clave para equilibrar recuerdo, rendimiento y costos. Elige la lógica que mejor se adapte a tu caso de uso.

• Relación uno a uno: usuario → un solo thread. Recuerda conversaciones aunque pase mucho tiempo. Puede degradar el contexto si el historial crece demasiado.
• Caducidad por tiempo: si el hilo supera 24 h, 48 h o una semana, se crea un nuevo thread. Mantiene al usuario enlazado, pero reinicia historial y estado de memoria compartida.
• Finalización por objetivo: cuando se resuelve la solicitud del usuario, se marca como finalizado y el siguiente mensaje abre un hilo desde cero, como en un call center.
• Concurrencia por usuario: el thread ID permite que “Juanito”, “Pepito” y “Fulanito” mantengan estados separados, cada uno con sus propios checkpoints.

¿Tú qué política aplicarías para tu agente y por qué? Comparte tu enfoque en los comentarios.