Retail on lo0 — Blog Técnico

Memoria entre hilos para los agentes de retail: PostgresStore, el cliente que vuelve y lo que no se debe recordar

Thu, 17 Sep 2026 05:00:00 +0200

TL;DR

El checkpointer es memoria de un hilo; el almacén es memoria entre hilos. Un cliente que vuelve mañana abre un hilo nuevo y el agente no sabe nada de ayer salvo lo que alguien haya puesto en el almacén. PostgresStore es ese almacén: una tabla store con espacio de nombres, clave y valor JSONB, y opcionalmente una tabla store_vectors con embeddings para buscar por significado.

El almacén llega al agente por store= en create_agent y se lee desde las herramientas y desde el prompt dinámico por runtime.store. Verificado: un dato escrito en un hilo por el cliente C9 aparece en otro hilo del mismo cliente y no aparece en un hilo de C10. El aislamiento es el espacio de nombres, ("clientes", cliente_id), y el identificador lo pone el contexto de ejecución, no el modelo.

Lo que se guarda lo decide la aplicación. Las preferencias que el cliente declara sí, por una herramienta con esquema cerrado. Las que el modelo deduce, no. Los hechos de negocio (última devolución, pedidos abiertos) no se duplican en el almacén: ya están en sus tablas y la herramienta los consulta ahí.

El TTL existe y tiene tres partes: default_ttl en minutos, refresh_on_read que renueva la caducidad al leer, y un barredor que borra lo caducado. El barredor es un hilo dentro del proceso; con tres réplicas son tres barredores. Se desactiva y sweep_ttl() se llama desde el CronJob de retención del artículo 5.

No hay borrado por espacio de nombres. Para cumplir una solicitud de supresión hay que listar las claves del cliente con search y borrarlas una a una con delete. Es un bucle de tres líneas y una consulta SQL de comprobación, y tiene que existir antes de guardar el primer dato.

InMemoryStore no admite TTL: put(..., ttl=...) lanza NotImplementedError. Los tests del almacén con TTL van en el grupo de Postgres, no en el de memoria.

Estás aquí: lo que el hilo no recuerda

Los cuatro agentes de la serie de retail tienen persistencia por hilo. Un hilo es un turno de trabajo del dependiente, una conversación con un cliente sobre un pedido, una pasada de compras o una ficha. Cuando el hilo termina, lo que se aprendió en él se va con la retención.

Hay cosas que deberían quedarse. Un cliente que ha dicho tres veces que prefiere recoger en la tienda de al lado no debería decirlo una cuarta. Un dependiente de la sección de menaje no debería tener que decir “menaje” en cada pregunta. Un proveedor que avisó de un retraso el lunes no debería sorprender al planificador del jueves.

Eso es el almacén, y este artículo lo añade a los agentes 1, 2 y 3. Es el primero de una tanda de dos; el segundo pone un supervisor delante de los cuatro.

La analogía: la ficha de cliente detrás del mostrador

Un buen dependiente lleva en la cabeza a los clientes habituales: la señora que recoge los jueves, el que siempre pide factura. Cuando el dependiente cambia de turno, eso se pierde, y por eso las tiendas que lo hacen bien tienen una ficha de cliente detrás del mostrador con dos o tres líneas escritas a mano. Lo que no tiene la ficha es lo que el sistema ya sabe: los pedidos, las devoluciones, la dirección. Eso se consulta.

El almacén es la ficha. Las tablas de negocio son el sistema. La regla de qué va en cada sitio es la misma que en la tienda: en la ficha, lo que el cliente ha dicho y no está en ningún otro sitio; en el sistema, todo lo demás.

Checkpointer y almacén

	Checkpointer	Almacén
Unidad	Hilo (`thread_id`)	Espacio de nombres (tupla de cadenas) y clave
Contenido	Estado completo del grafo por superstep	Documentos JSONB pequeños
Quién escribe	El motor, en cada superstep	Herramientas y aplicación, cuando quieren
Búsqueda	Por `thread_id`	Por prefijo de espacio de nombres, filtro sobre el valor y, con índice, por significado
Caducidad	Retención por hilo entero, externa	TTL por documento, con barredor
Tabla	`checkpoints` y compañía	`store` y `store_vectors`

Los dos viven en la base agentes, en tablas distintas, y los dos tienen setup() propio que corre en el mismo Job de migraciones del artículo 5.

Qué se guarda y qué no

La decisión más importante del artículo se toma antes de escribir código. Tres categorías:

Se guarda: lo que el cliente o el empleado declara y no está en ninguna tabla. Preferencia de recogida, canal de contacto preferido, idioma, “no me llaméis por la mañana”, la sección en la que trabaja el dependiente. Son datos que la persona ha dicho y que quiere que se recuerden.

No se guarda: lo que el modelo deduce. “Parece un cliente exigente”, “suele devolver”. Lo primero es una opinión del modelo sobre una persona y no tiene sitio en ningún almacén de una empresa que responda ante el RGPD. Lo segundo es un hecho que ya está en devoluciones y que la herramienta puede contar cuando haga falta, con la fecha y el importe, en vez de como etiqueta.

No se duplica: lo que está en las tablas de negocio. Pedidos, devoluciones, stock, incidencias. El almacén no es una caché de la base de datos; es la ficha escrita a mano.

Para el caso 3 hay una cuarta categoría: avisos de proveedores que no encajan en incidencias porque no son incidencias todavía (“nos han dicho que la fábrica cierra en agosto”). Van al almacén con espacio de nombres ("proveedores", proveedor_id) y los escribe compras desde su aplicación, no el modelo.

El almacén

from psycopg_pool import ConnectionPool
from langgraph.store.postgres import PostgresStore
from langgraph.store.base import TTLConfig

pool_agentes = ConnectionPool(os.environ["PG_AGENTES"], min_size=2, max_size=8,
 kwargs={"autocommit": True, "prepare_threshold": 0})

almacen = PostgresStore(
 pool_agentes,
 index={"dims": 1024, "embed": emb, "fields": ["texto"]},
 ttl=TTLConfig(default_ttl=60 * 24 * 365, refresh_on_read=True, omit_expired=True, sweep_interval_minutes=None),
)

emb es el mismo OpenAIEmbeddings del caso 1, contra el modelo de embeddings servido en vLLM detrás de LiteLLM, con check_embedding_ctx_length=False. dims tiene que coincidir con la dimensión del modelo; el índice se crea con esa dimensión en setup() y no se cambia después sin recrear la tabla.

fields dice qué campos del valor se indexan. Solo texto. El resto del documento (origen, fecha, quién lo escribió) es metadato y se filtra, no se busca.

El TTL de un año con renovación al leer es la política para preferencias: un cliente que vuelve las mantiene; uno que no vuelve en un año las pierde. sweep_interval_minutes=None desactiva el barredor en proceso; se explica más abajo.

setup() con index configurado aplica las migraciones de la tabla store y además las de store_vectors, empezando por CREATE EXTENSION IF NOT EXISTS vector dentro de un bloque DO. Eso exige que el rol del Job pueda crear extensiones, o que la extensión ya exista en la base. En un cluster de CloudNativePG lo segundo es lo habitual: la extensión se declara en el Cluster y el rol del Job no necesita ser superusuario.

Las herramientas

@tool
def recordar_preferencia(tipo: Literal["recogida", "contacto", "idioma", "horario"], valor: str,
 runtime: ToolRuntime[ContextoCliente]) -> dict:
 """Guarda una preferencia que el cliente ha declarado explícitamente en esta conversación."""
 ns = ("clientes", runtime.context.cliente_id)
 runtime.store.put(ns, f"pref-{tipo}", {
 "texto": f"{tipo}: {valor}",
 "tipo": tipo,
 "valor": valor,
 "origen": "cliente",
 "hilo": runtime.config["configurable"]["thread_id"],
 })
 return {"ok": True, "tipo": tipo}

@tool
def preferencias(runtime: ToolRuntime[ContextoCliente]) -> list[dict]:
 """Preferencias declaradas por el cliente en conversaciones anteriores."""
 ns = ("clientes", runtime.context.cliente_id)
 return [{"tipo": it.value["tipo"], "valor": it.value["valor"]} for it in runtime.store.search(ns, limit=10)]

Tres decisiones.

La clave es pref-{tipo}, no un identificador nuevo por escritura. Una preferencia nueva del mismo tipo sobreescribe la anterior. Sin eso, “recogida: T002” y “recogida: T001” conviven y el modelo elige.

El tipo es un Literal cerrado. El modelo no puede inventar categorías. Si el cliente dice algo que no encaja, no se guarda. Es la parte del esquema que hace que el almacén no acumule opiniones.

El espacio de nombres viene del contexto. runtime.context.cliente_id lo puso la aplicación a partir de la sesión. El modelo no ve ese parámetro y no puede escribir en la ficha de otro cliente. Verificado: un dato escrito con contexto C9 no aparece en una búsqueda con contexto C10, en otro hilo, con otro agente construido sobre el mismo almacén.

La búsqueda de preferencias no lleva query: devuelve todo el espacio de nombres, que son como mucho cuatro documentos. La búsqueda semántica se usa en el caso 3, donde los avisos de un proveedor pueden ser decenas:

@tool
def avisos_proveedor(consulta: str, runtime: ToolRuntime[ContextoCompras]) -> list[dict]:
 """Avisos recientes de compras sobre el proveedor relacionados con la consulta."""
 ns = ("proveedores", runtime.context.proveedor_id)
 return [
 {"texto": it.value["texto"], "fecha": it.value["fecha"], "similitud": round(it.score, 3)}
 for it in runtime.store.search(ns, query=consulta, limit=3)
 if it.score is not None and it.score > 0.4
 ]

Con el índice configurado, search con query calcula el embedding de la consulta con emb, lo compara por coseno contra store_vectors dentro del prefijo, y devuelve SearchItem con score. Sin query, es un listado por prefijo con filtro opcional sobre el valor.

El prompt que lee el almacén

Para el caso 2 las preferencias no van por herramienta. Van en el prompt, porque el modelo tiene que saberlas antes de proponer nada y no debería tener que acordarse de llamar a preferencias:

@dynamic_prompt
def prompt_cliente(request: ModelRequest) -> str:
 ctx = request.runtime.context
 prefs = request.runtime.store.search(("clientes", ctx.cliente_id), limit=10)
 lineas = "\n".join(f"- {p.value['texto']}" for p in prefs) or "- (ninguna)"
 return (
 f"Atiendes al cliente {ctx.cliente_id} de la tienda {ctx.tienda}.\n"
 f"Preferencias que el cliente ha declarado en otras conversaciones:\n{lineas}\n"
 "Respétalas al proponer recogida, contacto o plazo. No las cites como si las hubieras deducido."
 ...
 )

Verificado que request.runtime.store está disponible en el prompt dinámico y devuelve lo mismo que desde una herramienta. Es una consulta a Postgres por cada llamada al modelo; con refresh_on_read=True, además renueva la caducidad de esas preferencias en cada llamada, que es lo que se quiere para un cliente activo y lo que hay que tener en cuenta al estimar escrituras: cada lectura es también un UPDATE de expires_at.

La última frase del prompt existe porque un modelo que recibe “prefiere recogida en T002” tiende a decir “veo que sueles recoger en T002”, y eso a un cliente le suena a vigilancia. La preferencia se aplica, no se comenta.

El TTL y el barredor

TTLConfig tiene cuatro campos: default_ttl en minutos para lo que se escriba sin ttl explícito, refresh_on_read para renovar al leer, omit_expired para que las lecturas ignoren lo caducado aunque el barredor no haya pasado, y sweep_interval_minutes para el barredor.

El barredor es start_ttl_sweeper(): un hilo dentro del proceso que cada N minutos ejecuta sweep_ttl(), que es un DELETE FROM store WHERE expires_at IS NOT NULL AND expires_at < NOW(). Con tres réplicas del servicio del caso 2, son tres hilos haciendo el mismo DELETE sobre la misma tabla. No rompe nada; es trabajo repetido y una fuente de bloqueos breves que no hace falta tener.

Se deja sweep_interval_minutes=None y el barrido va en el CronJob de retención del artículo 5, una línea más:

borrados = almacen.sweep_ttl()
log.info("store: %d documentos caducados borrados", borrados)

omit_expired=True es lo que hace que entre barrido y barrido lo caducado no se lea. Con False, una preferencia caducada hace once meses seguiría apareciendo hasta la noche.

Los plazos por espacio de nombres: un año con renovación para clientes, 90 días sin renovación para proveedores (un aviso de hace tres meses ya es una incidencia o no fue nada), y 180 días con renovación para empleados. Se pasan como ttl= en cada put, en minutos, y default_ttl es solo la red.

El borrado que la ley pide

Un cliente puede pedir que se borre lo que la empresa sabe de él, y la respuesta tiene que ser completa. El almacén no tiene “borra todo lo de este espacio de nombres”. BaseStore tiene delete(namespace, key) y list_namespaces, y nada más.

def suprimir_cliente(cliente_id: str) -> int:
 ns = ("clientes", cliente_id)
 items = almacen.search(ns, limit=1000)
 for it in items:
 almacen.delete(ns, it.key)
 return len(items)

Y la comprobación, que es la que se guarda como evidencia de la solicitud:

SELECT count(*) FROM store WHERE prefix = 'clientes.' || %s;
SELECT count(*) FROM store_vectors WHERE prefix = 'clientes.' || %s;

El prefijo en la tabla es la tupla unida por puntos. Las dos consultas tienen que dar cero, y las dos van en el registro de la solicitud junto con la fecha.

Esta función existe y está probada antes de que el agente guarde la primera preferencia. Y va acompañada de la del checkpointer: los hilos del cliente en hilos se borran con delete_thread, y las trazas de Langfuse con su API de borrado por user_id, que es otro artículo. Lo que este artículo fija es que el almacén no puede ser el sitio donde un dato sobre una persona se queda sin que nadie sepa borrarlo.

Lo que se prueba y lo que no

Con InMemoryStore se prueba todo el aislamiento y la lectura: el almacén admite index con FakeEmbeddings de langchain-core, y los tests del artículo de pruebas se extienden con tres:

def test_preferencia_sobrevive_al_hilo(store):
 agente_a = build_cliente(ModeloGuion(responses=[llamada("recordar_preferencia", tipo="recogida", valor="T002"), AIMessage(content="ok")]), InMemorySaver(), store)
 agente_a.invoke(entrada("me lo llevo a T002"), context=Ctx("C9", "T001"), config=hilo("h1"))
 agente_b = build_cliente(ModeloGuion(responses=[llamada("preferencias"), AIMessage(content="ok")]), InMemorySaver(), store)
 r = agente_b.invoke(entrada("hola"), context=Ctx("C9", "T003"), config=hilo("h2"))
 assert json.loads(tool_msg(r).content) == [{"tipo": "recogida", "valor": "T002"}]

def test_otro_cliente_no_ve_nada(store):
 ...
 assert json.loads(tool_msg(r).content) == []

def test_sin_almacen_las_herramientas_no_rompen():
 agente = build_cliente(ModeloGuion(responses=[llamada("preferencias"), AIMessage(content="ok")]), InMemorySaver(), store=None)
 r = agente.invoke(entrada("hola"), context=Ctx("C9", "T001"), config=hilo("h1"))
 assert json.loads(tool_msg(r).content) == []

El tercero fija un detalle verificado: sin store= en create_agent, runtime.store es None dentro de la herramienta, y la herramienta tiene que comprobarlo y devolver vacío en vez de lanzar. Es el comportamiento que se quiere si el almacén se despliega después del agente.

Lo que no se prueba en memoria: el TTL. InMemoryStore.put(..., ttl=...) lanza NotImplementedError: TTL is not supported by InMemoryStore. Los tests de caducidad, refresh_on_read, omit_expired y sweep_ttl van en el grupo de Postgres, con un TTL de un minuto y un sleep.

Lo que se mide

Métrica	Dónde	Qué dice
Documentos por cliente	`SELECT prefix, count(*) FROM store GROUP BY prefix`	Con el esquema cerrado, cuatro como máximo. Más, el `Literal` se ha abierto
Preferencias escritas por conversación	Spans de `recordar_preferencia` en Langfuse	Por debajo de 0,1. Un modelo que guarda algo en cada conversación está guardando lo que no debe
Conversaciones del caso 2 en las que se aplicó una preferencia	Comparar la propuesta con `store`	La utilidad. Si no cambia ninguna propuesta, la memoria no sirve
Caducados borrados por barrido	Log del CronJob	Debe crecer a partir del mes doce y no antes
Solicitudes de supresión y tiempo hasta cero	Registro de solicitudes	La obligación. Tiene que ser el mismo día

Checklist

Hay una lista escrita de qué se guarda, qué no y qué no se duplica, y el Literal de tipos la refleja.
El espacio de nombres viene de runtime.context, nunca de un argumento del modelo.
Las claves son por tipo de preferencia y sobreescriben.
index usa el modelo de embeddings de la serie y dims coincide.
setup() del almacén corre en el Job de migraciones y la extensión vector existe antes.
sweep_interval_minutes=None y sweep_ttl() en el CronJob de retención.
omit_expired=True.
TTL por espacio de nombres pasado en cada put.
suprimir_cliente existe, está probada y deja evidencia con las dos consultas a cero.
Las herramientas comprueban runtime.store is None.
Los tests de TTL están en el grupo de Postgres.

Trampas y cosas que no son lo que parecen

El almacén como caché de la base de negocio. Se desincroniza y se convierte en la fuente que el modelo prefiere. Solo lo que no está en ninguna tabla.

El modelo escribiendo lo que deduce. Un put con texto libre desde una herramienta sin esquema acaba con opiniones sobre personas en Postgres. Literal cerrado y origen cliente.

Tres réplicas, tres barredores. El barredor es un hilo en proceso. Desactivar y barrer desde el CronJob.

refresh_on_read escribe. Cada lectura desde el prompt renueva expires_at. Es un UPDATE por llamada al modelo; se cuenta.

No hay borrado por espacio de nombres. Listar y borrar, y comprobar en SQL. Antes de la primera escritura.

InMemoryStore no tiene TTL. NotImplementedError. Los tests de caducidad van contra Postgres.

setup() crea la extensión. Necesita permiso o la extensión ya creada. En CNPG, se declara en el Cluster.

“Veo que sueles…” El modelo comenta la preferencia y suena a vigilancia. El prompt dice que se aplique y no se cite.

Cierre

La memoria entre hilos es una tabla con espacio de nombres, un esquema cerrado de lo que se puede escribir, un TTL por tipo de dato y una función de borrado que existe antes que el primer put. LangGraph pone la tabla, la búsqueda y la caducidad; la aplicación pone lo demás, y lo demás es lo que decide si la ficha de cliente es una ayuda o un problema.

El siguiente artículo cierra la tanda con un supervisor: un punto de entrada que decide si una conversación es del asistente de sala, del agente de cliente o de compras, y la traspasa con Command(goto=...) sin perder el hilo ni el almacén.

Ver también

Fuentes

Memoria y almacén en LangGraph: https://docs.langchain.com/oss/python/langgraph/memory
Persistencia en LangGraph (BaseStore, PostgresStore): https://docs.langchain.com/oss/python/langgraph/persistence
Código de langgraph.store.postgres (langgraph-checkpoint-postgres 3.1.2): PostgresStore.__init__, setup, sweep_ttl, start_ttl_sweeper, MIGRATIONS, VECTOR_MIGRATIONS
Código de langgraph.store.base (langgraph-checkpoint 4.2.0): TTLConfig, IndexConfig, BaseStore.put, search, delete, list_namespaces
Código de langgraph.store.memory (langgraph-checkpoint 4.2.0): InMemoryStore.put y el error de TTL
pgvector: https://github.com/pgvector/pgvector

Evaluar agentes de LangGraph con datasets de Langfuse: casos dorados por agente, evaluadores en código, un juez calibrado y una puerta de regresión en CI

Thu, 17 Sep 2026 04:30:00 +0200

TL;DR

Un caso dorado es una entrada, una salida esperada y metadatos, y la salida esperada casi nunca es un texto: es qué herramienta tenía que llamarse, con qué argumentos, si había que escalar, si había que parar a pedir aprobación, qué veredicto tenía que dar el evaluador. Comparar textos generados con textos esperados es lo que menos dice y lo que más cuesta.

Los casos salen de tres sitios que ya existen: las trazas de producción, marcadas desde la aplicación con un pulgar; las decisiones de los encargados del caso 2, que son etiquetas gratis; y la muestra semanal de fichas que alguien de catálogo ya lee. create_dataset_item con source_trace_id convierte una traza en un caso con un clic y una línea.

El SDK de Langfuse 4.15 trae run_experiment: una función de tarea que ejecuta el agente por elemento, evaluadores por elemento que reciben entrada, salida y salida esperada y devuelven Evaluation, evaluadores de ejecución que reciben todos los resultados, y un ExperimentResult con las puntuaciones. Verificado: funciona sobre un dataset del servidor y sobre una lista local, y produce el resultado aunque el servidor no responda.

Los evaluadores son código para todo lo que se puede decidir con código: herramienta correcta, argumentos, escalado, cita de sección, idioma, promesa de plazo. Un modelo juez solo para lo que exige leer, y solo después de medir su acuerdo con las personas sobre la misma muestra. Un juez sin calibrar es un segundo prompt opinando sobre el primero.

run_experiment tiene max_concurrency=50 por defecto. Contra un vLLM con una clave de gateway limitada a 24, son 26 peticiones en 429 desde el primer segundo. Se fija al valor de la clave, como en el caso 3.

La puerta en CI es una línea: si la métrica que importa baja del umbral, RegressionError. La acción oficial es de GitHub; con Forgejo se hace lo mismo con un script de veinte líneas que lee el ExperimentResult y sale con código distinto de cero.

Estás aquí: lo que el guion no prueba

El artículo anterior probó los cuatro agentes de la serie de retail con un modelo guionizado. Esos tests dicen que el grafo hace lo que el código dice cuando el modelo decide lo que el guion decide. No dicen nada de lo que el modelo decide solo.

Eso es lo que aquí se mide. Y se mide en Langfuse porque es donde ya están las trazas, donde ya se agrupan por caso y thread_id, y donde el par operativo con LiteLLM ya deja el coste por generación.

La analogía: el cliente misterioso

Una cadena de tiendas no sabe si sus dependientes atienden bien por lo que dicen los dependientes. Manda a un cliente misterioso con un guion (pregunta esto, pide una devolución sin ticket, insiste) y una hoja de comprobación: ¿miró el stock?, ¿citó el procedimiento?, ¿llamó al encargado cuando tocaba?, ¿prometió algo que no podía? La hoja es objetiva en casi todo. Solo una casilla, “¿fue amable?”, la rellena una persona, y a esa persona se la entrena antes con casos en los que ya se sabe la respuesta.

El dataset es el guion del cliente misterioso. Los evaluadores en código son la hoja. El juez con modelo es la casilla de “amable”, y la calibración es el entrenamiento de quien la rellena.

Qué es un caso dorado en cada agente

Agente	Entrada	Salida esperada	De dónde sale
Tienda	Pregunta, tienda, rol	Herramienta esperada (o ninguna), si escala al encargado, id de sección si aplica	Trazas de producción con pulgar; consultas escaladas revisadas
Cliente	Mensaje, pedido, cliente, historial	Herramienta y argumentos, si debe interrumpir, decisión que tomaría un encargado	Decisiones de encargados (`decisiones_encargado`)
Compras	Resumen por proveedor (planificador); referencia con historial (analista)	Orden de prioridad esperado; acción y rango de unidades	Propuestas editadas por compras: lo que cambiaron es la etiqueta
Fichas	Ficha de proveedor, criterios	Veredicto humano y criterios rechazados	Muestra semanal de catálogo

La columna del medio es lo que no es texto libre. En el caso 1 no se espera “En T001 no queda. T002 tiene 14”, se espera {"tool": "stock_sku", "args": {"sku": "SKU-0912"}, "escala": false}. La redacción cambia con cada versión del modelo y con la temperatura; la decisión no debería.

Cuando sí hay texto esperado, como en el caso 4 con el veredicto, se compara lo estructurado: aprobada y el conjunto de criterios rechazados, no el detalle.

De dónde salen los casos

Trazas con pulgar

La aplicación de sala tiene dos botones debajo de cada respuesta. Cada pulsación es una puntuación sobre la traza:

langfuse.create_score(
 trace_id=trace_id,
 name="pulgar",
 value=1.0 if arriba else 0.0,
 data_type="BOOLEAN",
 comment=comentario_opcional,
)

Una vez a la semana, alguien filtra en Langfuse las trazas del caso tienda con pulgar = 0, lee la conversación, decide cuál era la respuesta correcta y crea el caso:

langfuse.create_dataset_item(
 dataset_name="tienda-dorado",
 input={"pregunta": "...", "tienda": "T001", "rol": "dependiente"},
 expected_output={"tool": "procedimiento", "seccion": "PROC-4.3", "escala": False},
 metadata={"origen": "pulgar_abajo", "semana": "2026-W38"},
 source_trace_id=trace_id,
)

source_trace_id enlaza el caso con la traza de la que salió. En la interfaz, desde el caso se abre la conversación original, y desde cada ejecución del experimento se ve la nueva. Es lo que hace que el dataset no sea una hoja de cálculo.

Los casos con pulgar arriba también entran, en menor número, para que el dataset no sea solo fallos.

Las decisiones de los encargados

El caso 2 tiene etiquetas gratis. Cada fila de decisiones_encargado es un caso: la entrada es la conversación hasta la interrupción, la salida esperada es la decisión. Si el encargado aprobó tal cual, el agente propuso bien. Si editó el importe, el agente propuso mal y la etiqueta dice cuánto. Si rechazó con motivo, el agente no debió proponer.

Y una etiqueta sobre la propia política: si when no interrumpió y el cliente reclamó después, ese caso entra con debia_interrumpir: true. Esa es la evaluación de la función when, que no tiene modelo y se ajusta con estos datos.

La muestra de catálogo

El caso 4 ya tiene una muestra semanal que lee una persona. Cada ficha leída, con el veredicto de la persona y sus criterios, es un caso del dataset fichas-dorado. Es el único dataset de los cuatro donde el juez con modelo tiene sentido, y también el único donde hay con qué calibrarlo.

Ejecutar un experimento

from langfuse import Langfuse
from langfuse.experiment import Evaluation

langfuse = Langfuse()
dataset = langfuse.get_dataset("tienda-dorado")

def tarea(*, item, **kwargs):
 entrada = item.input
 ctx = Contexto(tienda=entrada["tienda"], empleado="EVAL", rol=entrada["rol"])
 thread_id = f"eval:{item.id}:{uuid.uuid4()}"
 llamadas, escalo = [], False
 for update in agente.stream(
 {"messages": [{"role": "user", "content": entrada["pregunta"]}]},
 context=ctx,
 config={"configurable": {"thread_id": thread_id}, "max_concurrency": 4},
 stream_mode="updates",
 ):
 for nodo, cambio in update.items():
 if nodo == "tools":
 llamadas += [json.loads(m.content) | {"tool": m.name} for m in cambio["messages"]]
 respuesta = agente.get_state({"configurable": {"thread_id": thread_id}}).values["messages"][-1].content
 return {"llamadas": llamadas, "respuesta": respuesta}

resultado = dataset.run_experiment(
 name="tienda-prompt-v7",
 run_name=f"{modelo_nombre}-{fecha}",
 task=tarea,
 evaluators=[herramienta_correcta, escalado_correcto, cita_seccion, castellano, sin_plazos],
 run_evaluators=[tasa_escalado],
 max_concurrency=16,
 metadata={"modelo": modelo_nombre, "prompt": "v7"},
)
print(resultado.format())

Lo que importa de la tarea: cada elemento corre en un hilo nuevo con un identificador que no colisiona con producción, con el contexto del caso y no de un usuario real, y devuelve lo estructurado además del texto. El checkpointer del agente de evaluación es un InMemorySaver; no se quiere el dataset en la tabla checkpoints de producción.

run_experiment acepta data= con una lista local cuando no hay dataset en el servidor, y es lo que se usa en desarrollo: los mismos evaluadores sobre diez casos escritos a mano en un fichero. Verificado en el SDK 4.15.4 que el ExperimentResult se construye igual, con item_results, run_evaluations y las medias, y que si el servidor no responde el resultado se produce igual y solo fallan las exportaciones de trazas.

Con el dataset del servidor, cada elemento deja una traza enlazada a la ejecución, y la ejecución aparece en la pestaña de datasets con sus puntuaciones. Dos ejecuciones con run_name distinto sobre el mismo dataset son comparables lado a lado en la interfaz; es el uso principal.

Cuando el agente interrumpe

La tarea del caso 2 tiene que reanudar. El caso dorado lleva la decisión esperada, y la tarea la aplica:

def tarea_cliente(*, item, **kwargs):
 cfg = {"configurable": {"thread_id": f"eval:{item.id}:{uuid.uuid4()}"}}
 r = agente.invoke({"messages": [{"role": "user", "content": item.input["mensaje"]}]}, context=ctx_de(item), config=cfg)
 interrumpio = "__interrupt__" in r
 propuesta = r["__interrupt__"][0].value["action_requests"] if interrumpio else []
 if interrumpio:
 r = agente.invoke(Command(resume={"decisions": [{"type": "approve"}] * len(propuesta)}), context=ctx_de(item), config=cfg)
 return {"interrumpio": interrumpio, "propuesta": propuesta, "respuesta": r["messages"][-1].content}

Se reanuda siempre con approve para que la respuesta final exista y se pueda evaluar el texto. Lo que se compara con la etiqueta del encargado es propuesta, no la decisión de reanudación.

Los evaluadores

El contrato es una función con argumentos nominales input, output, expected_output y metadata, que devuelve un Evaluation o una lista. Puede ser síncrona o asíncrona.

def herramienta_correcta(*, input, output, expected_output, metadata, **kwargs):
 esperada = expected_output.get("tool")
 llamadas = [c["tool"] for c in output["llamadas"]]
 if esperada is None:
 ok = llamadas == []
 else:
 ok = esperada in llamadas
 return Evaluation(name="herramienta_correcta", value=float(ok),
 comment=f"esperada={esperada} llamadas={llamadas}")

def escalado_correcto(*, output, expected_output, **kwargs):
 escalo = any(c.get("error") == "permiso_denegado" for c in output["llamadas"]) or "encargado" in output["respuesta"].lower()
 return Evaluation(name="escalado_correcto", value=float(escalo == expected_output["escala"]))

def cita_seccion(*, output, expected_output, **kwargs):
 if not expected_output.get("seccion"):
 return Evaluation(name="cita_seccion", value=1.0, comment="no aplica")
 return Evaluation(name="cita_seccion", value=float(expected_output["seccion"] in output["respuesta"]))

def sin_plazos(*, output, **kwargs):
 promete = re.search(r"\b(\d+\s*(días|horas)|mañana|hoy mismo)\b", output["respuesta"], re.I)
 return Evaluation(name="sin_plazos", value=float(promete is None))

def tasa_escalado(*, item_results, **kwargs):
 escalos = [r.output["llamadas"] and any(c.get("error") == "permiso_denegado" for c in r.output["llamadas"]) for r in item_results]
 return Evaluation(name="tasa_escalado", value=sum(map(bool, escalos)) / len(item_results))

Cinco evaluadores, cero modelos. herramienta_correcta y escalado_correcto son las dos métricas del caso 1 que un responsable de tienda entiende. cita_seccion comprueba que el identificador de sección está en la respuesta, no que la respuesta sea buena. sin_plazos es una expresión regular, y es suficiente para detectar que una versión del prompt ha empezado a prometer entregas. tasa_escalado es de ejecución: no compara con nada, describe la distribución, y sirve para ver que una versión del prompt escala el doble sin que ningún caso individual falle.

Un evaluador de idioma, castellano, usa un detector de idioma sobre la respuesta. Existe porque el caso 2 devuelve el rechazo del encargado en inglés al modelo y se ha visto al modelo contestar en inglés.

El juez con modelo, y su calibración

Para C04 (afirmaciones no respaldadas) y C06 (tono de la casa) del caso 4 no hay expresión regular. Hace falta leer. El juez es el propio evaluador del caso 4, con su prompt y ProviderStrategy(Veredicto), ejecutado como evaluador del experimento:

async def juez_c04_c06(*, output, expected_output, **kwargs):
 v = await evaluador_fichas.ainvoke({"messages": [{"role": "user", "content": mensaje_evaluador(output["ficha"], output["comprobaciones"], output["origen"])}]})
 veredicto = v["structured_response"]
 rechazados = {p.criterio for p in veredicto.problemas}
 esperados = set(expected_output["criterios_rechazados"])
 return [
 Evaluation(name="juez_aprobada_coincide", value=float(veredicto.aprobada == expected_output["aprobada"])),
 Evaluation(name="juez_c04_coincide", value=float(("C04" in rechazados) == ("C04" in esperados))),
 Evaluation(name="juez_c06_coincide", value=float(("C06" in rechazados) == ("C06" in esperados))),
 ]

Aquí el experimento no evalúa al generador. Evalúa al evaluador: cuánto coincide con la persona de catálogo sobre las fichas que la persona ya leyó. Es la calibración. Mientras juez_aprobada_coincide esté por debajo del 90 por ciento sobre la muestra, el juez no se usa para nada más que para medirse a sí mismo, y lo que se toca es su prompt y sus criterios.

Cuando pasa del umbral, se usa como evaluador del generador: el experimento del generador lleva juez_c04_c06 en sus evaluadores, y su puntuación se lee sabiendo que el juez acierta nueve de cada diez veces frente a una persona. Un juez que no se ha medido así es un segundo prompt opinando sobre el primero, y sus puntuaciones son números sin unidad.

Comparar dos versiones

Lo que un experimento sirve para decidir es si la versión nueva es mejor que la vieja en las métricas que importan y no peor en las demás. Dos ejecuciones sobre el mismo dataset:

`run_name`	herramienta_correcta	escalado_correcto	cita_seccion	sin_plazos	tasa_escalado	tokens/caso
`qwen3-30b-prompt-v6`	0,94	0,91	0,88	1,00	0,21	1.840
`qwen3-30b-prompt-v7`	0,96	0,97	0,95	0,98	0,19	2.110

Las cifras de esta tabla son el formato, no una medida: dependen del modelo, del dataset y del prompt de cada despliegue. Lo que la tabla enseña es cómo se lee. La v7 acierta más y cita más, y ha empezado a prometer plazos en el 2 por ciento de los casos. Eso es un caso concreto en item_results con sin_plazos = 0 y un comment con la frase, y se mira antes de decidir. Y cuesta un 15 por ciento más de tokens, que es lo que hay que poner en la balanza con el 6 por ciento de mejora en escalado.

El mismo cuadro sirve para cambiar de modelo con el mismo prompt, que es la comparación que más se hace en un cluster propio cuando sale una versión nueva del modelo abierto. El artículo de versionado de prompts cubre cómo se etiqueta la versión que se despliega; aquí solo importa que run_name y metadata lleven prompt y modelo, para que dentro de tres meses la tabla se entienda.

La puerta en CI

from langfuse.experiment import RegressionError

resultado = dataset.run_experiment(...)
medias = {e.name: e.value for e in resultado.run_evaluations}
media_escalado = sum(
 e.value for r in resultado.item_results for e in r.evaluations if e.name == "escalado_correcto"
) / len(resultado.item_results)

if media_escalado < 0.90:
 raise RegressionError(result=resultado, metric="escalado_correcto", value=media_escalado, threshold=0.90)

RegressionError está pensada para la acción langfuse/experiment-action de GitHub, que la captura, falla el flujo y escribe el comentario en el PR. Con Forgejo no hay acción, y hace lo mismo un paso del flujo que ejecuta el script y deja que la excepción salga: código distinto de cero, flujo rojo. El ExperimentResult se guarda como artefacto del flujo con format(include_item_results=True) para leer los casos que fallaron sin abrir Langfuse.

Qué métricas son puerta y cuáles son informe es una decisión por agente:

Agente	Puerta (para el despliegue)	Informe (se mira, no para)
Tienda	`escalado_correcto` ≥ 0,90; `sin_plazos` = 1,00	`herramienta_correcta`, `cita_seccion`, tokens
Cliente	`propuesta_coincide` ≥ 0,85; `interrumpio_cuando_debia` = 1,00	`castellano`, tokens
Compras	`accion_coincide` ≥ 0,80	`unidades_en_rango`, orden del plan
Fichas	`juez_aprobada_coincide` ≥ 0,90 (calibración)	aprobación por intento, tokens

Las puertas con = 1,00 son las que no admiten un caso: una promesa de plazo o una operación con dinero sin interrupción no es una regresión del 2 por ciento, es un incidente.

Un experimento contra vLLM con un dataset de doscientos casos y max_concurrency=16 tarda unos minutos y cuesta lo que doscientas conversaciones. Corre en cada cambio de prompt o de modelo, no en cada commit; los tests del artículo anterior sí corren en cada commit y son gratis.

Concurrencia y coste del experimento

run_experiment tiene max_concurrency=50 por defecto. Es el número de tareas en vuelo, y cada tarea es una conversación entera con sus llamadas al modelo. Contra un vLLM detrás de una clave de gateway con max_parallel_requests a 24, el valor por defecto son 26 tareas recibiendo 429 y reintentando. El valor correcto es el de la clave del agente de evaluación, que es distinta de la de producción para que un experimento no consuma el presupuesto de la tienda.

Dentro de cada tarea, max_concurrency del grafo aplica al abanico interno, como en el caso 3. Las dos capas se multiplican: 16 tareas por 4 de abanico son 64 peticiones potenciales, y eso es lo que tiene que caber.

El coste se lee en Langfuse por la traza de cada elemento, agrupando por el run_name. Un experimento del caso 1 sobre doscientos casos son unos 400.000 tokens de entrada con el prompt v7 de la tabla, la mayoría en prefijo compartido, y cuestan lo que el gateway diga que cuesta ese modelo, que en un cluster propio es la cifra que el artículo de FinOps explica cómo asignar.

Checklist

Cada agente tiene un dataset con salida esperada estructurada, no texto.
La aplicación escribe pulgar con create_score y alguien convierte los pulgares abajo en casos cada semana.
Las decisiones de encargados y las ediciones de compras alimentan sus datasets sin trabajo manual.
La tarea corre en hilos eval: con InMemorySaver y contexto del caso.
Los evaluadores en código cubren herramienta, argumentos, escalado, cita, idioma y plazos.
El juez con modelo se calibra contra la muestra humana antes de puntuar al generador.
max_concurrency del experimento es el de la clave de evaluación del gateway.
run_name y metadata llevan prompt y modelo.
Hay una tabla de qué métricas son puerta y cuáles informe, con umbrales.
La puerta lanza RegressionError y el flujo de CI la deja salir.
El experimento corre en cambios de prompt o modelo; los tests, en cada commit.

Trampas y cosas que no son lo que parecen

Comparar texto con texto. Es la evaluación más fácil de escribir y la que menos dice. Se compara la decisión: herramienta, argumentos, escalado, veredicto.

Un juez sin calibrar. Es un prompt puntuando a otro prompt. Primero se mide contra personas sobre la misma muestra; después se usa, y se usa sabiendo su acuerdo.

max_concurrency=50 por defecto. Contra una clave de gateway de 24, son 429 desde el primer segundo. Se fija al valor de la clave.

El dataset en la tabla de checkpoints de producción. La tarea usa su propio checkpointer en memoria. Doscientos hilos eval: por experimento en Postgres es lo que la retención acabaría borrando, pero mientras tanto están ahí.

El experimento con la clave de producción. Consume el presupuesto de la tienda y sus métricas de coste. Clave propia para evaluación.

Un experimento que pasa en la media y falla en un caso de dinero. Las puertas de = 1,00 existen para eso. Una media del 98 por ciento en sin_plazos son cuatro promesas en doscientos casos.

El resultado se produce aunque Langfuse esté caído. Verificado: run_experiment devuelve el ExperimentResult con las puntuaciones y solo fallan las exportaciones. Un flujo de CI que no compruebe que las trazas llegaron puede estar evaluando sin dejar rastro.

El dataset que no crece. Un dataset de cuarenta casos escritos el primer día mide el primer día. Los pulgares, las decisiones y la muestra semanal son lo que lo mantiene vivo.

Cierre

La evaluación de un agente es un dataset que crece solo, evaluadores que en su mayoría son código, un juez con modelo que se ha medido antes contra personas, y una puerta con umbrales por agente. Nada de eso es específico de LangGraph; lo específico es qué se guarda como salida de la tarea, y es lo que el grafo ya expone: las herramientas que llamó, con qué argumentos, si interrumpió, qué veredicto dio. Con los tests del artículo anterior fijando el grafo y esto midiendo al modelo, un cambio de prompt o de modelo deja de ser una opinión y pasa a ser una tabla con dos filas.

Ver también

Fuentes

Langfuse, datasets y experimentos: https://langfuse.com/docs/evaluation/experiments/experiments-via-sdk
Langfuse, puntuaciones (create_score): https://langfuse.com/docs/evaluation/evaluation-methods/custom-scores
Código del SDK langfuse 4.15.4: Langfuse.run_experiment, Langfuse.create_dataset_item, Langfuse.create_score, langfuse.experiment (Evaluation, TaskFunction, EvaluatorFunction, RunEvaluatorFunction, ExperimentResult, RegressionError)
Acción langfuse/experiment-action para GitHub: https://github.com/langfuse/experiment-action

Probar agentes de LangGraph sin modelo: tests de grafo con un modelo guionizado, pytest y el checkpointer en memoria

Thu, 17 Sep 2026 04:00:00 +0200

TL;DR

Un agente de LangGraph es un grafo con nodos deterministas y uno que no lo es. Todo lo que no es el modelo se prueba sin modelo: la estructura, las herramientas, el contexto, los límites, la persistencia, las interrupciones y el abanico. Es la mayor parte del código y la parte que rompe en silencio.

El modelo se sustituye por FakeMessagesListChatModel de langchain-core, que devuelve una lista de mensajes en orden. Le falta bind_tools, y create_agent lo llama; un subtipo con bind_tools que devuelva self y guarde las herramientas que vio lo arregla. Ese subtipo es un BaseModel de pydantic, y guardar algo en un atributo no declarado lanza ValueError: el atributo se declara en la clase.

Los tests cuentan checkpoints. InMemorySaver.list(config) devuelve uno por superstep, y el número es una propiedad del grafo que cambia cuando se añade middleware. Once por turno con una herramienta en el caso 1, trece con el resumen; si un cambio lo mueve, el test lo dice antes que la base de datos.

Escribir los tests sacó tres cosas que no estaban en los artículos. Cuando ToolCallLimitMiddleware corta con exit_behavior="end", el último mensaje es un AIMessage sintético en inglés, Tool call limit reached: run limit exceeded (7/6 calls), y va al usuario si la aplicación no lo intercepta. El corte se detecta en stream_mode="updates" porque la actualización del nodo del límite lleva jump_to: "end". Y los contadores por ejecución no quedan en el estado del hilo; solo los del hilo.

Las interrupciones se prueban de principio a fin: se invoca, se comprueba __interrupt__, se reanuda con Command(resume=...) y se comprueba que la herramienta corrió una vez con los argumentos de la decisión. El fallo a medias también: una herramienta que lanza en la primera llamada y el estado que queda antes de reanudar.

Lo que estos tests no prueban es si el modelo elige bien la herramienta o redacta bien. Eso es evaluación, no prueba, y es el siguiente artículo.

Estás aquí: después de construir, antes de medir

La serie de agentes con LangGraph para retail construyó cuatro agentes y los sirvió. Los artículos verificaron cada afirmación ejecutando código contra un modelo falso, y ese código era una sesión de terminal. Este artículo lo convierte en una suite de pytest que corre en cada commit, sin GPU y en menos de un segundo.

La distinción que ordena todo lo que sigue: un test comprueba que el grafo hace lo que el código dice; una evaluación comprueba que el modelo hace lo que el negocio quiere. Lo primero es determinista y se ejecuta en CI. Lo segundo es estadístico, cuesta tokens y va en el artículo de evaluación.

La analogía: el simulacro de caja

Para formar a un dependiente nuevo no hace falta un cliente. Se le pone un compañero que hace de cliente con un guion: pide esto, luego pregunta aquello, luego se enfada. Lo que se comprueba no es si el compañero actúa bien; es si el dependiente sigue el procedimiento, si sabe qué botón del TPV tocar y cuándo llamar al encargado.

El modelo falso es el compañero con guion. Los tests comprueban el procedimiento: las herramientas, el orden, el rol, la firma del encargado. El modelo real se evalúa después, con clientes reales grabados.

El modelo guionizado

from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
from langchain_core.messages import AIMessage

class ModeloGuion(FakeMessagesListChatModel):
 """Devuelve los mensajes de `responses` en orden y acepta herramientas."""
 tools_vistas: list[str] = []

 def bind_tools(self, tools, **kwargs):
 self.tools_vistas = [
 t.get("function", t).get("name") if isinstance(t, dict) else t.name
 for t in tools
 ]
 return self

def llamada(nombre: str, **args) -> AIMessage:
 return AIMessage(content="", tool_calls=[{"name": nombre, "args": args, "id": f"c-{nombre}"}])

Tres cosas de estas doce líneas.

FakeMessagesListChatModel viene en langchain-core y devuelve responses[i] en la llamada i. Con un AIMessage que lleva tool_calls, el nodo model del agente lo trata como una petición de herramienta y el grafo va a tools. Con uno que lleva solo content, el grafo termina. Un guion es una lista de esos mensajes en el orden en que el modelo “decidiría”.

bind_tools no existe en el falso y create_agent lo llama en cada vuelta del modelo para pasarle las herramientas. Sin él, NotImplementedError en la primera invocación. El subtipo devuelve self y de paso guarda los nombres de las herramientas, que es un dato que los tests quieren: qué vio el modelo.

tools_vistas está declarado como campo de clase porque el modelo falso es un modelo de pydantic. Asignar self.tools_vistas = ... sin declararlo lanza ValueError: "ModeloGuion" object has no field "tools_vistas". Fue el primer fallo de la suite.

Para el resumen y para profile, el falso admite profile={"max_input_tokens": 32768} en el constructor como cualquier BaseChatModel; se pasa cuando el agente lleva SummarizationMiddleware con disparador por fracción, o el constructor del middleware lanza.

Lo que se prueba del caso 1

El agente del asistente de sala se construye con una función build(modelo, checkpointer), y las herramientas leen de un diccionario de stock en el módulo de pruebas en vez de Postgres. Lo que sigue es la suite entera; corre en medio segundo.

La estructura

def test_estructura_del_grafo():
 agente = build(ModeloGuion(responses=[AIMessage(content="x")]))
 nodos = set(agente.get_graph().nodes)
 assert nodos >= {"__start__", "model", "tools", "__end__"}
 assert "ToolCallLimitMiddleware.after_model" in nodos
 assert "ModelCallLimitMiddleware.before_model" in nodos

get_graph() no ejecuta nada. Devuelve el grafo compilado con los nodos que el middleware añadió. Un test así falla cuando alguien quita un límite “para probar” y lo deja quitado, y cuando una subida de langchain cambia el nombre de un nodo, que es algo que la aplicación del artículo 5 usa para filtrar el flujo.

get_graph().draw_mermaid() devuelve el diagrama en texto. Guardado como fichero de referencia y comparado en un test, es un test de instantánea del grafo: cualquier cambio de topología aparece en el diff del commit.

Las herramientas y el contexto

@pytest.fixture
def dependiente():
 return Contexto(tienda="T001", empleado="E017", rol="dependiente")

def test_stock_usa_la_tienda_del_contexto(dependiente):
 modelo = ModeloGuion(responses=[llamada("stock_sku", sku="SKU-0912"), AIMessage(content="No queda.")])
 agente = build(modelo, InMemorySaver())
 out = agente.invoke({"messages": [HumanMessage("¿queda?")]}, context=dependiente,
 config={"configurable": {"thread_id": "t"}})
 tool_msgs = [m for m in out["messages"] if isinstance(m, ToolMessage)]
 assert json.loads(tool_msgs[0].content) == {
 "sku": "SKU-0912", "tienda": "T001", "unidades": 0, "cercanas": {"T002": 14},
 }
 assert modelo.tools_vistas == ["stock_sku", "procedimiento", "registrar_rotura"]

El guion pide stock_sku sin decir tienda, y la herramienta responde con T001 porque lo leyó del contexto. Si alguien cambia la herramienta para que la tienda venga como argumento del modelo, el test falla porque el guion no lo pasa. Es la garantía de que el contexto no se puede suplantar desde el prompt.

La última aserción fija la lista de herramientas que ve el modelo, en orden. Un test de contrato: si se añade una herramienta, el test la reclama.

def test_dependiente_no_registra_rotura(dependiente):
 modelo = ModeloGuion(responses=[
 llamada("registrar_rotura", sku="SKU-4471", unidades=6, motivo="caída"),
 AIMessage(content="Avisa al encargado."),
 ])
 out = build(modelo, InMemorySaver()).invoke(
 {"messages": [HumanMessage("registra")]}, context=dependiente,
 config={"configurable": {"thread_id": "t"}})
 tool_msg = [m for m in out["messages"] if isinstance(m, ToolMessage)][0]
 assert json.loads(tool_msg.content)["error"] == "permiso_denegado"

def test_encargado_si_registra():
 encargado = Contexto(tienda="T001", empleado="E001", rol="encargado")
 modelo = ModeloGuion(responses=[
 llamada("registrar_rotura", sku="SKU-4471", unidades=6, motivo="caída"),
 AIMessage(content="Hecho."),
 ])
 out = build(modelo, InMemorySaver()).invoke(
 {"messages": [HumanMessage("registra")]}, context=encargado,
 config={"configurable": {"thread_id": "t"}})
 assert json.loads([m for m in out["messages"] if isinstance(m, ToolMessage)][0].content)["ok"] is True

Son los dos tests que importan de todo el artículo. El guion hace que el modelo pida registrar la rotura en los dos casos; lo que cambia es el contexto. Si la comprobación de rol se moviera al prompt, los dos tests pasarían con el guion y el segundo fallaría con un modelo real que obedeciera al prompt, pero el primero pasaría también con un modelo real que no lo obedeciera. La comprobación tiene que estar donde el guion no puede saltarla.

Los límites

def test_limite_de_llamadas_corta_sin_excepcion(dependiente):
 modelo = ModeloGuion(responses=[llamada("stock_sku", sku=f"SKU-{i}") for i in range(20)])
 out = build(modelo, InMemorySaver()).invoke(
 {"messages": [HumanMessage("bucle")]}, context=dependiente,
 config={"configurable": {"thread_id": "t"}})
 tool_msgs = [m for m in out["messages"] if isinstance(m, ToolMessage)]
 ejecutadas = [m for m in tool_msgs if m.status != "error"]
 assert len(ejecutadas) == 6
 assert "limit" in tool_msgs[-1].content.lower()
 assert isinstance(out["messages"][-1], AIMessage)

Un guion de veinte llamadas seguidas es un modelo en bucle. Con run_limit=6, la primera versión del test comprobaba que había como máximo seis ToolMessage, y falló: hay siete. El middleware, al bloquear la séptima, añade un ToolMessage sintético con status="error" y el texto Tool call limit exceeded. Do not make additional tool calls. para esa llamada, y después un AIMessage sintético: Tool call limit reached: run limit exceeded (7/6 calls). El test correcto cuenta las ejecutadas, que son las que no tienen status="error".

Ese AIMessage final es el que la aplicación del artículo 5 envía al usuario como respuesta del agente, y está en inglés y lo escribe el middleware. ModelCallLimitMiddleware hace lo mismo: Model call limits exceeded: run limit (3/3). La aplicación tiene que detectar el corte y sustituir el texto. La forma fiable no es buscar ese texto, es mirar el flujo:

def test_el_corte_se_ve_en_updates(dependiente):
 modelo = ModeloGuion(responses=[llamada("stock_sku", sku=f"SKU-{i}") for i in range(20)])
 agente = build(modelo, InMemorySaver())
 cortes = []
 for update in agente.stream({"messages": [HumanMessage("bucle")]}, context=dependiente,
 config={"configurable": {"thread_id": "t"}}, stream_mode="updates"):
 for nodo, cambio in update.items():
 if cambio and cambio.get("jump_to") == "end":
 cortes.append(nodo)
 assert cortes == ["ToolCallLimitMiddleware.after_model"]

La actualización del nodo del límite lleva jump_to: "end", run_tool_call_count: {"__all__": 7} y los dos mensajes sintéticos. Verificado en langgraph 1.2.11 y langchain 1.4.1. Es el mismo bucle de updates que el servicio ya recorre para detectar interrupciones, y añade una rama para los cortes.

Un detalle más que salió del test: tras el corte, get_state(config).values tiene thread_tool_call_count y thread_model_call_count, pero no los contadores por ejecución. run_tool_call_count vive en la actualización y no se persiste. Un test que quiera comprobar el contador por ejecución lo lee del flujo, no del estado.

Los checkpoints

def test_checkpoints_por_turno(dependiente):
 cp = InMemorySaver()
 modelo = ModeloGuion(responses=[llamada("stock_sku", sku="SKU-0912"), AIMessage(content="ok")])
 cfg = {"configurable": {"thread_id": "t"}}
 build(modelo, cp).invoke({"messages": [HumanMessage("q")]}, context=dependiente, config=cfg)
 assert sum(1 for _ in cp.list(cfg)) == 11

Un número fijo que documenta el coste del middleware. Cuando alguien añada SummarizationMiddleware, el test dirá 13 y el commit tendrá que cambiar el número y, con él, la estimación de filas por día del artículo 5. Es un test que existe para obligar a esa conversación.

Lo que se prueba del caso 2

La interrupción de aprobación tiene un contrato de datos y una secuencia, y las dos cosas se prueban sin modelo.

efectos: list[tuple] = []

@tool
def reembolsar(pedido: str, importe: float) -> dict:
 """Emite un reembolso."""
 efectos.append((pedido, importe))
 return {"ok": True, "reembolso": "R-1"}

def test_reembolso_grande_para_y_no_ejecuta():
 efectos.clear()
 modelo = ModeloGuion(responses=[
 llamada("reembolsar", pedido="P1", importe=120.0),
 AIMessage(content="Reembolso emitido."),
 ])
 agente = build_cliente(modelo, InMemorySaver())
 cfg = {"configurable": {"thread_id": "h1"}}
 r = agente.invoke({"messages": [HumanMessage("devuelve P1")]}, context=cliente, config=cfg)
 assert efectos == []
 intr = r["__interrupt__"][0].value
 assert intr["action_requests"][0]["name"] == "reembolsar"
 assert intr["review_configs"][0]["allowed_decisions"] == ["approve", "edit", "reject"]

 r2 = agente.invoke(Command(resume={"decisions": [
 {"type": "edit", "edited_action": {"name": "reembolsar", "args": {"pedido": "P1", "importe": 90.0}}},
 ]}), context=cliente, config=cfg)
 assert efectos == [("P1", 90.0)]
 assert r2["messages"][-1].content == "Reembolso emitido."

def test_reembolso_pequeno_no_para():
 efectos.clear()
 modelo = ModeloGuion(responses=[llamada("reembolsar", pedido="P2", importe=20.0), AIMessage(content="Hecho.")])
 r = build_cliente(modelo, InMemorySaver()).invoke(
 {"messages": [HumanMessage("devuelve P2")]}, context=cliente,
 config={"configurable": {"thread_id": "h2"}})
 assert "__interrupt__" not in r
 assert efectos == [("P2", 20.0)]

Los dos tests fijan la política (when por importe), el contrato de la interrupción (action_requests y review_configs), la reanudación con edit, y la propiedad central: la herramienta no corre antes de la decisión y corre una vez después, con los argumentos editados. La lista efectos es el instrumento; en producción es la tabla reembolsos.

El tercer test del caso 2 es el de la re-ejecución, con un nodo propio que registra efectos antes y después de interrupt y comprueba la secuencia antes, antes, después. Existe para que nadie ponga una escritura delante de una interrupción sin que un test lo diga.

Lo que se prueba del caso 3

Del abanico se prueban cuatro propiedades, y ninguna necesita el modelo: el trabajador se sustituye por una función que devuelve un análisis fijo.

def test_consolidar_espera_a_todos():
 pasos = [list(u.keys()) for u in grafo.stream(estado(skus=5), config=cfg, stream_mode="updates")]
 assert pasos.count(["consolidar"]) == 1
 assert pasos.index(["consolidar"]) == len(pasos) - 1

def test_orden_de_analisis_es_el_del_reparto():
 r = grafo.invoke(estado(skus=200), config=cfg)
 assert [a["sku"] for a in r["analisis"]] == [f"SKU-{i:05d}" for i in range(200)]

def test_fallo_de_un_lote_conserva_los_demas(monkeypatch):
 fallos = {"n": 0}
 def analizar_con_fallo(lote):
 if lote["referencias"][0]["sku"] == "SKU-00050" and fallos["n"] == 0:
 fallos["n"] += 1
 raise ConnectionError("gateway")
 return analizar_lote(lote)
 g = construir_grafo(analizar=analizar_con_fallo, retry_policy=None)
 with pytest.raises(ConnectionError):
 g.invoke(estado(skus=200), config=cfg)
 st = g.get_state(cfg)
 assert len(st.values["analisis"]) == 150
 assert st.next == ("analizar_lote",)
 r = g.invoke(None, config=cfg)
 assert len(r["analisis"]) == 200

def test_cache_evita_la_segunda_pasada():
 llamadas = []
 g = construir_grafo(analizar=lambda lote: (llamadas.append(1), analizar_lote(lote))[1], cache=InMemoryCache())
 g.invoke(estado(skus=200), config={"configurable": {"thread_id": "a"}})
 g.invoke(estado(skus=200), config={"configurable": {"thread_id": "b"}})
 assert len(llamadas) == 4

El primero es el test de defer=True: si alguien lo quita, consolidar aparece antes del último lote. El segundo fija el orden determinista del reductor. El tercero es el más valioso: con un lote que falla y sin retry_policy, el estado conserva los 150 análisis de los tres lotes que terminaron, next apunta al trabajador, y invoke(None) completa solo el que faltaba. El cuarto cuenta llamadas reales con y sin caché: cuatro lotes de 50 en la primera pasada y cero en la segunda.

Lo que no se prueba aquí es la concurrencia. Se puede medir el pico de tareas en vuelo con un contador y un candado, como se hizo para el artículo, pero depende del número de CPU de la máquina de CI, y un test que pasa en el portátil y falla en el runner no es un test. La concurrencia se fija con max_concurrency y se mide en el despliegue.

Lo que se prueba del caso 4

El bucle de fichas tiene dos agentes y un contador. Con el modelo guionizado los dos agentes se controlan por separado:

def test_tres_rechazos_van_a_revision_manual():
 generador = agente_generador(ModeloGuion(responses=[llamada("Ficha", titulo="Cafetera 1L", descripcion=f"v{i}", atributos={}) for i in range(3)]))
 evaluador = agente_evaluador(ModeloGuion(responses=[llamada("Veredicto", aprobada=False, problemas=[{"criterio": "C04", "detalle": "x"}]) for _ in range(3)]))
 g = construir_grafo(generador, evaluador)
 r = g.invoke(estado_inicial("SKU-1"), config=cfg)
 assert r["intentos"] == 3
 assert [h["veredicto"]["aprobada"] for h in r["historial"]] == [False, False, False]
 assert ultimo_nodo(g, cfg) == "descartar"

def test_titulo_largo_se_rechaza_aunque_el_modelo_apruebe():
 generador = agente_generador(ModeloGuion(responses=[llamada("Ficha", titulo="x" * 90, descripcion="d", atributos={})]))
 evaluador = agente_evaluador(ModeloGuion(responses=[llamada("Veredicto", aprobada=True, problemas=[])]))
 with pytest.raises(StructuredOutputValidationError):
 construir_grafo(generador, evaluador).invoke(estado_inicial("SKU-1"), config=cfg)

Con ToolStrategy en los tests, la salida estructurada es una llamada a herramienta con el nombre del esquema, y el guion la produce con llamada("Ficha", ...). En producción los agentes llevan ProviderStrategy; en los tests se usa ToolStrategy(esquema, handle_errors=False) a propósito, porque el modelo falso no genera JSON con esquema y porque con handle_errors=True, el valor por defecto, un fallo de validación se convierte en un ToolMessage de error y el agente vuelve a llamar al modelo, que en un guion es el siguiente mensaje de la lista y no un reintento. Con handle_errors=False la excepción es StructuredOutputValidationError, la misma que lanza ProviderStrategy en producción; verificado con un título de 90 caracteres y max_length=10. Es una de las pocas diferencias entre el agente probado y el desplegado, y se documenta en la fixture.

El segundo test fija que la validación de pydantic manda por encima del evaluador: un título de 90 caracteres no llega a evaluarse.

Dónde corren y qué no cubren

La suite de los cuatro casos corre con InMemorySaver e InMemoryCache, sin Postgres, sin vLLM y sin red; los seis tests del caso 1 de arriba tardan medio segundo. Va en el pre-commit y en CI.

Un segundo grupo, marcado con @pytest.mark.postgres, repite los tests de checkpoint y de retención contra un Postgres real levantado en un contenedor: setup() en una base limpia, el número de filas en checkpoints y checkpoint_writes tras un turno, delete_thread y la consulta de retención por checkpoint->>'ts'. Corre en CI y no en el pre-commit. Es el grupo que detecta una subida de langgraph-checkpoint-postgres que añade una migración o cambia una tabla.

Lo que ninguno de los dos grupos cubre:

Si el modelo elige stock_sku cuando el dependiente pregunta por stock. El guion lo decide.
Si la respuesta al cliente es correcta, está en castellano y no promete plazos.
Si el evaluador de fichas aprueba lo que catálogo aprobaría.
Si el planificador de compras ordena bien los proveedores.
La latencia, los tokens y el coste.

Todo eso depende del modelo y se mide con datos, no se afirma con aserciones. Es el siguiente artículo.

Checklist

Hay un ModeloGuion con bind_tools y un campo declarado para las herramientas vistas.
Cada agente se construye con una función build(modelo, checkpointer) que los tests pueden llamar.
Las herramientas leen de un origen sustituible (diccionario en tests, Postgres en producción).
Hay un test de estructura por agente y una instantánea Mermaid del grafo.
Cada herramienta con rol tiene dos tests: uno que pasa por el rol y otro que no.
Los tests de límite cuentan ejecuciones, no ToolMessage, y comprueban jump_to en updates.
Hay un test de checkpoints por turno con el número exacto.
Las interrupciones se prueban con invoke, __interrupt__, Command(resume) y una lista de efectos.
El abanico tiene tests de defer, de orden, de fallo parcial y de caché.
Los agentes de salida estructurada se prueban con ToolStrategy y la diferencia está documentada.
Los tests que necesitan Postgres van en un grupo aparte que corre en CI.

Trampas y cosas que no son lo que parecen

El modelo falso no tiene bind_tools. NotImplementedError en la primera invocación de create_agent. Un subtipo de tres líneas.

El subtipo es pydantic. Un atributo no declarado lanza ValueError. Declararlo en la clase.

El corte por límite deja siete ToolMessage con run_limit=6. El séptimo es sintético, con status="error". Contar las ejecutadas.

El mensaje final del corte es inglés fijo del middleware. Tool call limit reached: run limit exceeded (7/6 calls). Detectarlo por jump_to en updates, no por el texto, y sustituirlo antes de enviarlo.

Los contadores por ejecución no se persisten. run_tool_call_count está en la actualización del nodo, no en get_state. Los del hilo sí.

Un test de concurrencia depende de la máquina. El pool de hilos por defecto es cpu+4. No se afirma en CI; se mide en el despliegue.

ToolStrategy en los tests, ProviderStrategy en producción. Es una diferencia real y hay que escribirla en la fixture, no descubrirla en un incidente.

Un guion que pasa no dice que el modelo pasaría. Los tests prueban el grafo con las decisiones fijadas. Las decisiones se evalúan aparte.

Cierre

Cuatro agentes probados en segundos y sin modelo. Lo que se prueba es todo lo que un modelo no puede romper y un desarrollador sí: qué herramienta ve el modelo, qué hace cada una con cada rol, cuándo se para, cuántas filas deja, y qué queda cuando algo falla a medias. Lo que no se prueba es lo que solo el modelo decide, y para eso hacen falta datos reales, un evaluador y una forma de comparar dos versiones. Es lo que viene a continuación.

Ver también

Fuentes

Modelos falsos de langchain-core (FakeMessagesListChatModel, GenericFakeChatModel): https://reference.langchain.com/python/langchain_core/language_models/fake_chat_models/
Middleware de LangChain 1.x (ToolCallLimitMiddleware, ModelCallLimitMiddleware): https://docs.langchain.com/oss/python/langchain/middleware
Persistencia en LangGraph (InMemorySaver, get_state, list): https://docs.langchain.com/oss/python/langgraph/persistence
Código de langchain.agents.middleware.tool_call_limit (langchain 1.4.1), método after_model
pytest: https://docs.pytest.org/en/stable/

Servir agentes de LangGraph sin langgraph-api: autorización por hilo, drenado, retención y sondas para los cuatro casos de retail

Thu, 17 Sep 2026 03:30:00 +0200

TL;DR

El servidor HTTP de LangGraph no se despliega. langgraph-api tiene licencia Elastic 2.0, pide LANGGRAPH_CLOUD_LICENSE_KEY en producción y envía metadatos a un endpoint de LangChain salvo en una variante contractual air-gapped. Lo documentó el artículo de deepagents con fichero y línea. El motor, los checkpointers y create_agent son MIT y son lo único que hace falta.

Lo que ese servidor daba y hay que escribir: la API de hilos y ejecuciones, la autorización, la cola, el drenado, la retención, las migraciones y las sondas. Son unas cuatrocientas líneas de FastAPI por caso más un CronJob y un Job. No es poco y no es un servidor de colas: es lo justo para cuatro agentes con perfiles de carga distintos.

El checkpointer no comprueba propietarios. Cualquier thread_id que llegue en la configuración se lee y se reanuda. Verificado además que un hilo inexistente devuelve estado vacío y next vacío, sin error: un identificador mal formado no se distingue de uno ajeno. La autorización es una tabla hilos con propietario, tienda y caso, y un identificador que genera el servidor.

El drenado existe y funciona. RunControl.request_drain() desde el manejador de SIGTERM hace que la ejecución en curso termine el superstep actual, guarde el checkpoint y lance GraphDrained. Verificado: el estado queda en el límite del superstep y invoke(None, config) lo reanuda desde ahí. La herramienta en vuelo en ese superstep se repite; por eso la idempotencia del caso 2.

La retención es un CronJob que borra hilos enteros con delete_thread. Es la única operación de borrado implementada en el checkpointer de Postgres 3.1.2, y la propia clase base avisa de que una poda parcial puede vaciar canales en silencio. La fecha para decidir qué borrar está dentro del JSONB de la fila de checkpoint, en checkpoint->>'ts', no en una columna.

Las migraciones corren en un Job con permiso de DDL y sin pooler en modo transacción, porque setup() crea índices con CREATE INDEX CONCURRENTLY. Los pods del agente conectan con un rol sin DDL y con prepare_threshold=0 si hay PgBouncer.

Estás aquí: el último de la serie, y el único sin agente

Este es el artículo 5 de la serie de agentes con LangGraph para retail. Los cuatro anteriores construyen agentes y los invocan desde Python. Este los pone detrás de una URL en el cluster, con todo lo que un invoke en un cuaderno no tiene: quién puede hablar con qué hilo, qué pasa cuando el pod se reinicia a medias, cuánto tiempo se guarda una conversación, y cómo sabe Kubernetes que el servicio está vivo.

La decisión de fondo la tomó el artículo de deepagents: el motor sí, el servidor no. Aquí se paga esa decisión.

La analogía: el mostrador y la trastienda

Los cuatro agentes son cuatro dependientes que ya saben hacer su trabajo. Lo que no tienen es mostrador: quién los llama, cómo se sabe que la persona al otro lado es quien dice, qué pasa con la conversación cuando el dependiente se va a comer, y quién tira los vales de hace un mes.

El servidor de LangGraph es un mostrador de alquiler, con contrato. Lo que sigue es construir uno propio, más pequeño, con solo lo que estos cuatro necesitan.

Lo que se pierde y lo que se escribe

Lo que daba `langgraph-api`	Lo que se hace aquí
API de asistentes, hilos y ejecuciones	FastAPI con cuatro rutas por caso: crear hilo, enviar mensaje, reanudar, leer estado
Autenticación y autorización por hilo	JWT de Keycloak en el gateway y tabla `hilos` con propietario
Cola de ejecuciones y reintentos	Semáforo de ejecuciones en vuelo por pod y 503 con `Retry-After`; lo que necesita una cola con reintentos y visibilidad va a Temporal
Cron	`CronJob` de Kubernetes que invoca el caso 3 a las seis
Studio	Trazas en Langfuse y `get_state_history` por hilo
Streaming	`astream` sobre SSE
Drenado en despliegues	`RunControl` en el `SIGTERM` y reanudación desde la aplicación
Retención	`CronJob` con `delete_thread`
Migraciones	`Job` con `setup()` y rol con DDL

Lo que no se pierde: el checkpointer, el almacén, la caché, las interrupciones, los subgrafos y el middleware. Todo eso es del motor.

El servicio

Un Deployment por caso, con la misma imagen y una variable de entorno que dice qué grafo carga. Los cuatro casos tienen perfiles distintos, y separarlos es lo que permite dimensionar y limitar cada uno con su clave del gateway: el asistente de sala es interactivo y de latencia baja; el de cliente es interactivo y con hilos que duran días; el de compras es una pasada diaria de minutos; el de fichas es un lote continuo.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from psycopg_pool import AsyncConnectionPool
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

@asynccontextmanager
async def lifespan(app: FastAPI):
 app.state.pool = AsyncConnectionPool(
 os.environ["PG_AGENTES"], min_size=2, max_size=8, open=False,
 kwargs={"autocommit": True, "prepare_threshold": 0},
 )
 await app.state.pool.open()
 app.state.checkpointer = AsyncPostgresSaver(app.state.pool)
 app.state.grafo = cargar_grafo(os.environ["CASO"], app.state.checkpointer)
 app.state.en_vuelo = {} # thread_id -> RunControl
 app.state.semaforo = asyncio.Semaphore(int(os.environ.get("MAX_EJECUCIONES", "16")))
 app.state.drenando = False
 yield
 await app.state.pool.close()

app = FastAPI(lifespan=lifespan)

AsyncPostgresSaver se construye sobre el pool, no sobre una conexión. autocommit=True es lo que el checkpointer espera, y prepare_threshold=0 desactiva las sentencias preparadas de psycopg, que PgBouncer en modo transacción no soporta. setup() no se llama aquí.

Crear un hilo

@app.post("/hilos", status_code=201)
async def crear_hilo(cuerpo: NuevoHilo, usuario: Usuario = Depends(usuario_actual)):
 thread_id = str(uuid.uuid4())
 async with app.state.pool.connection() as conn:
 await conn.execute(
 "INSERT INTO hilos (thread_id, caso, propietario, tienda, creado) VALUES (%s, %s, %s, %s, now())",
 (thread_id, os.environ["CASO"], usuario.sub, usuario.tienda),
 )
 return {"thread_id": thread_id}

El identificador lo genera el servidor. El cliente no lo elige nunca, ni siquiera con un prefijo. Y la fila de hilos se escribe antes de que exista ningún checkpoint, porque es la que autoriza todo lo demás.

usuario_actual lee el JWT que Keycloak emitió y que el gateway ya validó, y saca sub, el rol y la tienda de sus claims. Cómo se configura ese realm y qué claims lleva está en el artículo de Keycloak; aquí solo se consume.

Autorizar un hilo

async def hilo_autorizado(thread_id: str, usuario: Usuario = Depends(usuario_actual)) -> Hilo:
 async with app.state.pool.connection() as conn:
 fila = await (await conn.execute(
 "SELECT thread_id, caso, propietario, tienda FROM hilos WHERE thread_id = %s", (thread_id,)
 )).fetchone()
 if fila is None or fila[1] != os.environ["CASO"]:
 raise HTTPException(404)
 hilo = Hilo(*fila)
 if hilo.propietario != usuario.sub and not (usuario.rol == "encargado" and usuario.tienda == hilo.tienda):
 raise HTTPException(404)
 return hilo

Dos detalles. Un hilo ajeno devuelve 404, no 403, para no confirmar que existe. Y la regla del encargado es la del caso 2: un encargado de la misma tienda puede leer y reanudar los hilos de sus clientes, que es lo que la cola de aprobaciones necesita.

Esto es todo lo que el checkpointer no hace. Verificado en langgraph 1.2.11 con InMemorySaver y en el código del de Postgres: get_state con cualquier thread_id devuelve lo que haya, y con uno que no existe devuelve values={} y next=() sin lanzar nada. Sin la tabla, un cliente que adivine o construya un identificador lee la conversación de otro.

Enviar un mensaje, en streaming

from langgraph.runtime import RunControl
from langgraph.errors import GraphDrained

@app.post("/hilos/{thread_id}/mensajes")
async def enviar(thread_id: str, cuerpo: Mensaje, hilo: Hilo = Depends(hilo_autorizado), usuario: Usuario = Depends(usuario_actual)):
 if app.state.drenando:
 raise HTTPException(503, headers={"Retry-After": "5"})
 if app.state.semaforo.locked():
 raise HTTPException(503, headers={"Retry-After": "2"})
 ctx = contexto_para(usuario, hilo)
 trace_id = str(uuid.uuid4())
 config = {
 "configurable": {"thread_id": thread_id},
 "metadata": {"caso": hilo.caso, "tienda": hilo.tienda, "langfuse_trace_id": trace_id},
 "callbacks": [langfuse_handler()],
 "max_concurrency": int(os.environ.get("MAX_CONCURRENCY", "8")),
 }
 control = RunControl()

 async def flujo():
 async with app.state.semaforo:
 app.state.en_vuelo[thread_id] = control
 try:
 async for modo, chunk in app.state.grafo.astream(
 {"messages": [{"role": "user", "content": cuerpo.texto}]},
 config=config, context=ctx, stream_mode=["messages", "updates"],
 durability="sync", control=control,
 ):
 if modo == "messages" and chunk[1].get("langgraph_node") == "model" and chunk[0].content:
 yield evento("token", chunk[0].content)
 elif modo == "updates" and "__interrupt__" in chunk:
 await registrar_aprobacion_pendiente(thread_id, hilo, chunk["__interrupt__"][0], trace_id)
 yield evento("interrupcion", {"interrupt_id": chunk["__interrupt__"][0].id})
 yield evento("fin", {"trace_id": trace_id})
 except GraphDrained:
 yield evento("drenado", {"reanudable": True})
 finally:
 app.state.en_vuelo.pop(thread_id, None)

 return EventSourceResponse(flujo())

stream_mode como lista devuelve tuplas (modo, contenido); verificado que ["updates", "values"] intercala los dos modos por superstep. Con messages se filtran los trozos del nodo model para el cliente, y con updates se detecta la interrupción en cuanto se produce, en vez de esperar al final para mirar __interrupt__ en el resultado. Es lo que permite escribir la cola de aprobaciones del caso 2 dentro del flujo.

durability="sync" en todo lo interactivo. Cuesta una escritura síncrona por superstep, que en Postgres local son milisegundos, y es lo que hace que el drenado y la reanudación funcionen.

Reanudar

@app.post("/hilos/{thread_id}/reanudar")
async def reanudar(thread_id: str, cuerpo: Reanudacion, hilo: Hilo = Depends(hilo_autorizado), usuario: Usuario = Depends(usuario_actual)):
 estado = await app.state.grafo.aget_state({"configurable": {"thread_id": thread_id}})
 if not estado.next:
 raise HTTPException(409, "el hilo no está esperando nada")
 if cuerpo.decisiones is not None and usuario.rol != "encargado":
 raise HTTPException(403)
 entrada = Command(resume={"decisions": cuerpo.decisiones}) if cuerpo.decisiones is not None else None
 ctx = await contexto_desde_cola(thread_id) if cuerpo.decisiones is not None else contexto_para(usuario, hilo)
 ... # mismo flujo que enviar, con `entrada` en vez del mensaje

Dos reanudaciones distintas pasan por aquí. Con decisiones, es la aprobación del caso 2: Command(resume=...), solo encargados, y el contexto se carga de la cola porque el runtime no lo recuerda. Sin decisiones, es la reanudación tras un drenado: invoke(None) sobre el hilo, que continúa desde el último checkpoint. La comprobación de estado.next distingue un hilo que espera de uno que terminó: reanudar un hilo terminado no falla, vuelve a ejecutar desde el final, y eso es un turno del modelo que nadie pidió.

El drenado

Un Deployment con estrategia rolling mata pods con ejecuciones en curso. Sin nada más, la ejecución muere donde esté, el último checkpoint es el del superstep anterior, y el siguiente invoke sobre el hilo repite desde ahí, herramienta en vuelo incluida.

RunControl es el mecanismo cooperativo. Se crea uno por ejecución, se pasa en control=, y request_drain() desde cualquier hilo hace que el motor termine el superstep actual, escriba el checkpoint y lance GraphDrained. Verificado con un grafo de seis pasos y un drenado a mitad: invoke lanza GraphDrained con la razón, get_state muestra tres pasos hechos y next en el cuarto, y invoke(None, config) lo termina.

import signal

def manejar_sigterm(*_):
 app.state.drenando = True
 for thread_id, control in list(app.state.en_vuelo.items()):
 control.request_drain("rolling")

signal.signal(signal.SIGTERM, manejar_sigterm)

Con terminationGracePeriodSeconds por encima de la duración del superstep más largo (una llamada al modelo con su salida, unos 30 segundos en el peor caso de los casos interactivos; un lote entero de 50 referencias en el caso 3, que puede ser un minuto), el pod termina limpio. El cliente recibe el evento drenado con reanudable: true y vuelve a llamar a reanudar sin decisiones, que cae en otro pod y continúa.

Lo que el drenado no evita es que el superstep en curso se complete: si es una herramienta lenta, hay que esperarla. Y lo que no cubre es un SIGKILL por límite de memoria, donde no hay cooperación posible: ahí vuelve la re-ejecución de la herramienta en vuelo y la idempotencia por tool_call_id del caso 2.

Para el caso 3, el drenado se combina con lotes pequeños: cuanto menos dura el superstep del abanico, antes termina el pod y menos trabajo se repite si no termina.

La retención

El checkpointer de Postgres 3.1.2 tiene una operación de borrado, delete_thread. prune, copy_thread y delete_for_runs heredan de la clase base y lanzan NotImplementedError, y el docstring de prune en esa clase base explica por qué no hay que escribirse una poda parcial a mano: los canales delta guardan solo un centinela fuera de los puntos de instantánea, y quedarse con el último checkpoint de una cadena lo deja reconstruyéndose vacío sin error.

Así que se borran hilos enteros, por antigüedad, y la antigüedad se saca del JSONB:

-- Hilos del caso 'tienda' sin actividad en 7 días
SELECT c.thread_id
FROM checkpoints c
JOIN hilos h USING (thread_id)
WHERE h.caso = 'tienda' AND c.checkpoint_ns = ''
GROUP BY c.thread_id
HAVING max((c.checkpoint->>'ts')::timestamptz) < now() - interval '7 days';

checkpoints no tiene columna de fecha. El checkpoint_id es un UUID versión 6 ordenable por tiempo, y el propio checkpoint lleva ts en ISO 8601; verificado en ambos casos. El HAVING sobre ts es más legible que ordenar por el identificador y da lo mismo.

async def retencion(caso: str, dias: int, lote: int = 200):
 async with pool.connection() as conn:
 filas = await (await conn.execute(CONSULTA, (caso, dias))).fetchall()
 for (thread_id,) in filas[:lote]:
 await checkpointer.adelete_thread(thread_id)
 async with pool.connection() as conn:
 await conn.execute("UPDATE hilos SET borrado = now() WHERE thread_id = %s", (thread_id,))

Corre como CronJob cada noche, con un lote acotado para no bloquear las tablas durante minutos. delete_thread borra checkpoints, checkpoint_blobs y checkpoint_writes para todos los espacios de nombres del hilo, subgrafos incluidos. La fila de hilos no se borra: se marca, porque las trazas de Langfuse y las filas de negocio siguen apuntando a ese thread_id.

Los plazos por caso: 7 días para el asistente de sala, 90 para el de cliente (una devolución puede reclamarse), 30 para compras (las propuestas ya están en su tabla), y 7 para fichas (el resultado ya está en fichas). Son decisiones de negocio y se leen de una tabla, no del código.

El almacén (PostgresStore) es aparte y sí tiene TTL, con un barredor en proceso; en esta serie no se usa el almacén, así que no hay barredor que dimensionar.

Las migraciones

# job_migraciones.py
from langgraph.checkpoint.postgres import PostgresSaver

with PostgresSaver.from_conn_string(os.environ["PG_AGENTES_DDL"]) as saver:
 saver.setup()

Un Job de Kubernetes, con un rol que tiene CREATE en el esquema, conectado directamente a Postgres y no al pooler. setup() aplica diez migraciones idempotentes: cuatro tablas, un ALTER, tres índices con CREATE INDEX CONCURRENTLY y una columna añadida; lo lleva en checkpoint_migrations. Los índices concurrentes no pueden ir dentro de una transacción, y PgBouncer en modo transacción envuelve cada sentencia en una: falla. Directo a Postgres, una vez, antes del primer despliegue y después de cada subida de langgraph-checkpoint-postgres.

Los pods conectan con un rol que solo tiene SELECT, INSERT, UPDATE y DELETE sobre las cuatro tablas. Si alguien despliega una versión nueva del paquete sin correr el Job, el arranque falla con un error de esquema, ruidoso, en la primera petición.

Las sondas

@app.get("/salud/vivo")
async def vivo():
 return {"ok": True}

@app.get("/salud/listo")
async def listo():
 if app.state.drenando:
 raise HTTPException(503)
 try:
 async with app.state.pool.connection() as conn:
 await conn.execute("SELECT 1 FROM checkpoint_migrations LIMIT 1")
 except Exception:
 raise HTTPException(503)
 return {"ok": True, "en_vuelo": len(app.state.en_vuelo)}

La sonda de vida no toca nada externo; un pod cuya base de datos está caída no se reinicia, porque reiniciarlo no arregla la base. La de disponibilidad comprueba que hay conexión y que las migraciones existen, y devuelve 503 en cuanto empieza el drenado para que el Service deje de enviarle tráfico nuevo mientras termina el que tiene.

El gateway de inferencia no está en la sonda. Un LiteLLM caído se ve en la primera petición como un error del modelo, que ModelRetryMiddleware reintenta y que acaba en un mensaje al usuario. Meterlo en la sonda de disponibilidad haría que los cuatro servicios se marcaran como no listos a la vez, sin que ninguno pudiera hacer nada al respecto.

Capacidad y contrapresión

Cada pod corre un proceso de uvicorn con un bucle de eventos y un semáforo de ejecuciones en vuelo. El valor del semáforo y max_concurrency se fijan por caso:

Caso	`MAX_EJECUCIONES` por pod	`MAX_CONCURRENCY`	Réplicas	Razón
Tienda	32	4	2	Muchas conversaciones cortas; el abanico interno es pequeño
Cliente	16	4	2	Menos tráfico, hilos largos con interrupciones
Compras	1	24	1	Una pasada a la vez, con el abanico limitado a la clave del gateway
Fichas	8	2	1	Lote continuo; el paralelismo lo da el número de fichas en vuelo

Cuando el semáforo está lleno, 503 con Retry-After. No hay cola en el servicio. Las ejecuciones que necesitan cola, reintentos con retroceso y visibilidad de qué está esperando (el caso 3 si se lanzara bajo demanda, o cualquier lote largo) van a un orquestador; el artículo sobre Temporal explica cuándo compensa y cuánto cuesta.

La suma de MAX_EJECUCIONES por MAX_CONCURRENCY por réplicas de los cuatro casos es el máximo de peticiones simultáneas que pueden llegar al gateway desde los agentes, y tiene que caber en lo que se dimensionó para la flota. Con la tabla de arriba son 256 + 128 + 24 + 16.

Observabilidad

Cada petición crea un CallbackHandler de Langfuse con el trace_id que la aplicación generó, y ese trace_id viaja en metadata para que las herramientas lo escriban en las filas de negocio. Los nodos del grafo aparecen como spans anidados; con los subgrafos desactivados en los casos 3 y 4, la traza tiene la profundidad que el grafo del padre y no más.

La alternativa OTel, con LANGSMITH_TRACING_MODE=otel y el exportador OTLP del SDK de LangSmith hacia el endpoint OTel de Langfuse, correlaciona con los spans de FastAPI y del gateway. El artículo de deepagents documenta el camino y sus versiones; aquí se usa el callback por ser menos piezas, y se acepta que la traza del agente y la de infraestructura se cruzan por trace_id en vez de anidarse.

Tres métricas propias del servicio, en Prometheus: ejecuciones en vuelo por pod, 503 por contrapresión, y drenados. Las tres deberían estar cerca de cero la mayor parte del tiempo, y la primera es la que dice cuándo subir réplicas.

Un cliente por despliegue

Los cuatro servicios son de una cadena de tiendas. Si la plataforma sirviera a varias cadenas, la tabla hilos con la tienda no bastaría: el checkpointer, el almacén y la caché son compartidos por instancia, y el artículo de deepagents documenta que el backend de ficheros fija su raíz al construirse. La regla que sale de ahí es un despliegue por cliente, con su base agentes y sus claves del gateway, y el artículo sobre aislar agentes por cliente tiene el resto.

Checklist

langgraph-api no está en la imagen; langgraph, los checkpointers y langchain sí.
Un Deployment por caso, misma imagen, CASO por entorno.
El thread_id lo genera el servidor y la fila de hilos se escribe antes del primer checkpoint.
Todo acceso a un hilo pasa por hilo_autorizado; ajeno o inexistente es 404.
astream con ["messages", "updates"], durability="sync" y un RunControl por ejecución.
SIGTERM llama a request_drain en las ejecuciones en vuelo y pone la sonda de disponibilidad en 503.
terminationGracePeriodSeconds cubre el superstep más largo del caso.
reanudar comprueba estado.next y distingue aprobación de continuación.
CronJob de retención con delete_thread por lotes y plazos por caso en tabla.
Job de migraciones con rol DDL, directo a Postgres, en cada subida del paquete.
Rol de los pods sin DDL; prepare_threshold=0 si hay pooler.
Sonda de vida sin dependencias; sonda de disponibilidad con SELECT a checkpoint_migrations.
Semáforo por pod y 503 con Retry-After; la suma de concurrencias cabe en el gateway.

Trampas y cosas que no son lo que parecen

Un hilo inexistente no da error. get_state devuelve values={} y next=(). Un endpoint que confíe en que el checkpointer distinga hilos válidos deja pasar cualquier identificador.

Reanudar un hilo terminado ejecuta un turno. invoke(None) sobre un hilo sin next no falla; vuelve a llamar al modelo. Comprobar estado.next antes.

GraphDrained se lanza donde se invoca. En un flujo SSE eso es dentro del generador, y hay que capturarla ahí para emitir el evento; si no, el cliente ve una conexión cortada sin saber que puede reanudar.

El drenado espera al superstep. Una herramienta que tarda dos minutos retrasa la terminación dos minutos, o se lleva un SIGKILL si el período de gracia es menor. Supersteps cortos o período de gracia largo; no hay tercera opción.

La retención no tiene columna de fecha. checkpoint->>'ts' dentro del JSONB, o el orden del UUID v6. Ninguna de las dos está indexada; con millones de filas, la consulta de retención es un recorrido y se lanza de noche.

delete_thread es lo único que hay. prune lanza NotImplementedError y una poda a mano puede vaciar canales sin error. Hilos enteros.

setup() desde el pod o a través del pooler falla. Permisos o CREATE INDEX CONCURRENTLY en transacción. Job directo con DDL.

La sonda de disponibilidad que mira al gateway tumba los cuatro servicios a la vez. El gateway se ve en la petición, no en la sonda.

Cierre

Servir los cuatro agentes sin el servidor de LangGraph es una tabla, cuatro rutas, un manejador de señal, un CronJob y un Job. La tabla es la autorización que el checkpointer no tiene. Las rutas son la API de hilos reducida a lo que estos agentes usan. El manejador de señal es el drenado, que el motor sí trae y que solo hay que conectar. El CronJob es la retención, que el motor trae a medias. El Job es lo que el motor pide y no dice dónde correr.

Lo que no hay que escribir es lo que importa: el grafo, la persistencia, las interrupciones, el abanico y la salida estructurada son del motor, con licencia MIT, y corren en un cluster propio sin pedirle permiso a nadie. Eso era la tesis del artículo que abrió la vertical, y estos seis artículos son la comprobación con cuatro problemas de tienda que un responsable entiende.

Ver también

Fuentes

Persistencia y checkpointers en LangGraph: https://docs.langchain.com/oss/python/langgraph/persistence
Documentación de self-hosting de LangGraph Platform (licencia y requisitos del servidor): https://docs.langchain.com/langsmith/self-hosted
Código de langgraph.runtime (langgraph 1.2.11): RunControl; y de langgraph.errors: GraphDrained
Código de langgraph.checkpoint.postgres y .aio (3.1.2): setup, MIGRATIONS, delete_thread, adelete_thread
Código de langgraph.checkpoint.base (4.2.0): docstrings de prune, copy_thread, delete_for_runs
psycopg 3, prepare_threshold y poolers: https://www.psycopg.org/psycopg3/docs/advanced/prepare.html
FastAPI, eventos de ciclo de vida: https://fastapi.tiangolo.com/advanced/events/

Agente de datos de producto con LangGraph: enriquecer y controlar fichas con un generador, un evaluador y un bucle que sabe parar

Thu, 17 Sep 2026 03:00:00 +0200

TL;DR

El generador escribe la ficha y el evaluador la puntúa contra una lista de criterios que no cambia. Son dos agentes distintos, con dos prompts distintos y salida estructurada los dos. El evaluador no ve el prompt del generador ni sus intentos anteriores; ve la ficha y los criterios. Es la única forma de que el evaluador no apruebe lo que el generador quiso hacer en vez de lo que hizo.

El bucle lo cierra una arista condicional que lee dos cosas del estado: el veredicto y un contador de intentos. Tres como máximo. El modelo no sabe cuántos intentos lleva ni decide cuándo parar. Verificado con un evaluador que rechaza dos veces y aprueba a la tercera: tres intentos, tres veredictos en el historial, y el grafo termina en publicar.

Con un modelo en vLLM, response_format en create_agent no hace lo que parece. Sin perfil en el modelo, LangChain no puede saber si el proveedor admite salida estructurada y recurre a una herramienta sintética con el nombre del esquema, que el modelo tiene que llamar. Con profile={"structured_output": True} usa response_format con el esquema JSON y vLLM lo aplica con decodificación guiada. Verificado en _supports_provider_strategy de langchain 1.4.1.

Un agente de create_agent invocado dentro de un nodo hereda el checkpointer del grafo padre y guarda sus propios checkpoints bajo un espacio de nombres. Una ficha con tres intentos deja 30 filas; con checkpointer=False en los dos agentes, 12. El estado que importa está en el padre; los subgrafos no necesitan reanudarse.

El resultado estructurado de un agente es un objeto pydantic, y ese objeto entra en el estado del subgrafo. Al deserializar el checkpoint, LangGraph 1.2.11 avisa de que el tipo no está registrado y de que lo bloqueará en una versión futura. Se guarda en el estado del padre como diccionario con model_dump(), y se registra el módulo en allowed_msgpack_modules o se desactiva el checkpointer del subgrafo.

Lo que se mide es la tasa de aprobación por intento. Es la única métrica que dice si el bucle compensa: si a la tercera se aprueba lo mismo que a la segunda, el tercer intento sobra.

Estás aquí: el cuarto caso, el bucle que corrige

Este es el caso 4 de la serie de agentes con LangGraph para retail. Los tres anteriores tratan con personas o con un catálogo entero; este trata con un texto. Una ficha de producto tiene un título, una descripción, unos atributos, y unas reglas de la casa sobre lo que puede y no puede decir. Las fichas llegan del proveedor a medias, en otro idioma, o con los atributos en el título. Hoy las completa alguien de catálogo, una a una, y las publica sin que nadie las vuelva a leer.

El agente hace lo mismo con dos diferencias: escribe y comprueba en dos pasos separados, y el segundo paso tiene derecho de veto. Es el patrón que la documentación llama reflexión, y la forma más simple de un evaluador: no puntúa de uno a diez, dice sí o no y por qué.

La analogía: el redactor y el corrector

En cualquier redacción hay dos personas. Una escribe y otra corrige, y la que corrige no ha visto el borrador anterior ni sabe lo que el redactor intentaba decir; solo tiene el texto y el libro de estilo. Si el corrector fuera el propio redactor releyendo, aprobaría lo que quiso escribir.

El generador es el redactor. El evaluador es el corrector con el libro de estilo. El contador de intentos es el jefe de sección que a la tercera vuelta publica o descarta, sin que el redactor lo decida.

Los criterios

El evaluador comprueba una lista cerrada. Cada criterio tiene un identificador, una descripción para el evaluador y una descripción para el generador. Se guardan en una tabla, no en el prompt, y se versionan.

Id	Criterio	Comprobable sin modelo
C01	El título tiene entre 30 y 80 caracteres y empieza por el tipo de producto	Sí
C02	La descripción no repite el título	Sí
C03	Todos los atributos obligatorios de la familia están presentes	Sí
C04	No hay afirmaciones de salud, seguridad o rendimiento no respaldadas por la ficha del proveedor	No
C05	La descripción no menciona precio, disponibilidad ni promociones	Parcial
C06	El tono es el de la casa: segunda persona, sin superlativos, sin exclamaciones	Parcial
C07	Las cifras (capacidad, medidas, potencia) coinciden con las del proveedor	Sí

Los criterios de la tercera columna marcados con “Sí” se comprueban en código antes de llamar al evaluador, y el resultado se le pasa. Un modelo evaluando si un título tiene menos de 80 caracteres es un modelo haciendo mal lo que len() hace bien. Lo que el evaluador aporta es C04, C06 y las partes no mecánicas de C05: lo que exige leer.

El estado

import operator
from typing import Annotated, TypedDict

class EstadoFicha(TypedDict):
 sku: str
 origen: dict # ficha del proveedor, atributos de familia, cifras
 ficha: dict # última versión generada
 comprobaciones: dict # C01, C02, C03, C07: resultado en código
 veredicto: dict # {"aprobada": bool, "problemas": [{"criterio": ..., "detalle": ...}]}
 intentos: Annotated[int, operator.add]
 historial: Annotated[list[dict], operator.add]

intentos con operator.add es el contador: cada vez que generar devuelve {"intentos": 1}, el reductor suma. historial acumula un registro por intento con la ficha y el veredicto, y es lo que después permite medir. ficha y veredicto se sobreescriben.

ficha y veredicto son diccionarios, no objetos pydantic. Los agentes devuelven pydantic en structured_response, y el nodo lo convierte con model_dump() antes de escribirlo en el estado. Más abajo se explica por qué no es una manía.

Los dos agentes

from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.agents.structured_output import ProviderStrategy

class Ficha(BaseModel):
 titulo: str = Field(max_length=80)
 descripcion: str = Field(max_length=1200)
 atributos: dict[str, str]

class Problema(BaseModel):
 criterio: str
 detalle: str = Field(max_length=200)

class Veredicto(BaseModel):
 aprobada: bool
 problemas: list[Problema] = Field(default_factory=list)

generador = create_agent(
 modelo,
 tools=[],
 system_prompt=PROMPT_GENERADOR, # reglas de la casa, formato, y "corrige solo lo señalado"
 response_format=ProviderStrategy(Ficha),
 checkpointer=False,
)

evaluador = create_agent(
 modelo,
 tools=[],
 system_prompt=PROMPT_EVALUADOR, # criterios C04, C05, C06 y "responde solo con el veredicto"
 response_format=ProviderStrategy(Veredicto),
 checkpointer=False,
)

Ninguno tiene herramientas. Todo lo que necesitan va en el mensaje: la ficha del proveedor, los atributos obligatorios de la familia, y para el generador, los problemas del intento anterior. Son dos llamadas al modelo por intento, sin ciclo de herramientas; create_agent está aquí por la salida estructurada, el prompt y el middleware, no por el bucle.

Dos parámetros que no son decorativos. ProviderStrategy se explica en su propia sección. checkpointer=False también.

Los prompts, y lo que cada uno no ve

El generador recibe la ficha del proveedor y, a partir del segundo intento, la lista de problemas del veredicto anterior con la instrucción de corregir solo eso. No recibe su ficha anterior entera. Se probó dárselo y el resultado fue peor: con la ficha anterior delante, el modelo reescribe frases que estaban bien y a veces reintroduce un problema ya corregido en otro sitio. Con la ficha del proveedor y la lista de problemas, regenera desde el origen con las restricciones acumuladas.

El evaluador recibe la ficha generada, los resultados de las comprobaciones en código, y los criterios. No recibe el prompt del generador, ni sus intentos anteriores, ni cuántos lleva. Si supiera que es el tercer intento, aprobaría más; se ha visto en pruebas con el número de intento en el mensaje. La única información de contexto es el origen, para C04 y C07.

El grafo

from langgraph.graph import StateGraph, START, END

def comprobar(state: EstadoFicha) -> dict:
 return {"comprobaciones": comprobaciones_en_codigo(state["ficha"], state["origen"])}

def generar(state: EstadoFicha) -> dict:
 problemas = state.get("veredicto", {}).get("problemas", [])
 salida = generador.invoke({"messages": [{"role": "user", "content": mensaje_generador(state["origen"], problemas)}]})
 return {"ficha": salida["structured_response"].model_dump(), "intentos": 1}

def evaluar(state: EstadoFicha) -> dict:
 salida = evaluador.invoke({"messages": [{"role": "user", "content": mensaje_evaluador(state["ficha"], state["comprobaciones"], state["origen"])}]})
 veredicto = salida["structured_response"].model_dump()
 fallos_codigo = [c for c, ok in state["comprobaciones"].items() if not ok]
 if fallos_codigo:
 veredicto["aprobada"] = False
 veredicto["problemas"] += [{"criterio": c, "detalle": "comprobación automática"} for c in fallos_codigo]
 return {"veredicto": veredicto, "historial": [{"intento": state["intentos"], "ficha": state["ficha"], "veredicto": veredicto}]}

def decidir(state: EstadoFicha) -> str:
 if state["veredicto"]["aprobada"]:
 return "publicar"
 if state["intentos"] >= 3:
 return "descartar"
 return "generar"

def publicar(state: EstadoFicha) -> dict:
 guardar_ficha(state["sku"], state["ficha"], estado="publicada", intentos=state["intentos"])
 return {}

def descartar(state: EstadoFicha) -> dict:
 guardar_ficha(state["sku"], state["ficha"], estado="revision_manual", intentos=state["intentos"],
 problemas=state["veredicto"]["problemas"])
 return {}

grafo = StateGraph(EstadoFicha)
grafo.add_node("generar", generar)
grafo.add_node("comprobar", comprobar)
grafo.add_node("evaluar", evaluar)
grafo.add_node("publicar", publicar)
grafo.add_node("descartar", descartar)
grafo.add_edge(START, "generar")
grafo.add_edge("generar", "comprobar")
grafo.add_edge("comprobar", "evaluar")
grafo.add_conditional_edges("evaluar", decidir, {"generar": "generar", "publicar": "publicar", "descartar": "descartar"})
grafo.add_edge("publicar", END)
grafo.add_edge("descartar", END)

Cinco nodos y una arista condicional con tres salidas. decidir es el único sitio donde se lee el contador, y es una función sin modelo. El modelo no puede alargar el bucle ni acortarlo.

Las comprobaciones en código van en su propio nodo entre generar y evaluar, y el evaluador las recibe. Además, evaluar fuerza el rechazo si alguna falla: aunque el modelo apruebe, un título de 90 caracteres no se publica. El evaluador con modelo no tiene la última palabra sobre lo que se puede comprobar sin él.

Verificado con un generador que devuelve una ficha por intento y un evaluador guionizado que rechaza dos veces y aprueba a la tercera: intentos termina en 3, el historial tiene tres entradas con False, False, True, y el grafo sale por publicar. Con el evaluador rechazando siempre, sale por descartar a la tercera.

La salida estructurada, por debajo

response_format en create_agent admite un esquema a secas, ToolStrategy(esquema) o ProviderStrategy(esquema). Con el esquema a secas, LangChain elige por el modelo: en _supports_provider_strategy mira model.profile, y si el perfil dice structured_output: True usa ProviderStrategy; si no, busca el nombre del modelo en una lista de patrones de modelos conocidos, y si tampoco, ToolStrategy.

Con ChatOpenAI apuntando a vLLM y un nombre como qwen3-30b-a3b, el perfil es None y el nombre no está en la lista. Resultado: ToolStrategy. Verificado: _supports_provider_strategy(modelo, tools=[]) devuelve False sin perfil y True con profile={"structured_output": True}.

Lo que cambia entre las dos:

	`ToolStrategy`	`ProviderStrategy`
Qué se envía	Una herramienta sintética con el nombre del esquema (`Ficha`) en `tools`	`response_format` con el esquema JSON
Qué hace el modelo	Decide llamar a esa herramienta con los argumentos	Genera el JSON con decodificación guiada
Qué puede salir mal	El modelo responde en texto sin llamar a la herramienta, o llama con argumentos que no validan; LangChain reintenta con un mensaje de error (`handle_errors=True` por defecto)	El JSON es válido siempre; si no valida contra pydantic, no hay reintento: `_handle_structured_output_error` solo reintenta con `ToolStrategy`, con la otra lanza
Coste	Tokens de la definición de la herramienta en cada llamada, y a veces una vuelta más	Nada extra en la entrada; la decodificación guiada añade algo de latencia en esquemas grandes

Para este agente se fija ProviderStrategy a mano en los dos, y el modelo lleva profile={"max_input_tokens": 32768, "structured_output": True} en el marco de la serie. El esquema se mantiene plano: Ficha tiene tres campos y atributos es un diccionario de cadenas, no un modelo anidado por familia. vLLM aplica bien esquemas de este tamaño; con esquemas de varios niveles y enumeraciones largas la decodificación guiada se nota en la latencia de la primera ficha.

Field(max_length=80) en el título es una restricción del esquema que vLLM no aplica en la generación; la aplica pydantic al validar. Con ProviderStrategy un fallo de validación no se reintenta: el agente lanza y el nodo generar lanza con él. Por eso generar captura esa excepción y manda la ficha a revisión manual sin pasar por el evaluador, y por eso C01 se comprueba también en código: lo que está dentro del esquema es una segunda barrera, no la primera.

Los subgrafos y sus checkpoints

generador y evaluador son grafos compilados. Cuando se invocan dentro de un nodo del grafo padre con .invoke(...), reciben la configuración del padre, y con ella el checkpointer. Sin hacer nada, cada uno guarda sus propios checkpoints bajo un espacio de nombres derivado del nodo y de la tarea.

Medido con InMemorySaver, una ficha con tres intentos:

Agentes compilados con	Checkpoints del padre	Checkpoints de subgrafos	Total
Valor por defecto	12	18	30
`checkpointer=False`	12	0	12

Los 18 de los subgrafos son tres por cada invocación de agente, seis invocaciones. Son el estado interno de cada llamada: los mensajes de esa llamada, la respuesta estructurada, y el resultado. Ninguno sirve para nada después: la ficha ya está en el estado del padre como diccionario, y un subgrafo sin herramientas ni interrupciones no tiene nada que reanudar.

checkpointer=False en create_agent le dice al agente que no persista aunque el padre lo haga. Es distinto de checkpointer=None, que es el valor por defecto y significa “hereda”. Con treinta mil fichas al año y tres intentos de media, la diferencia son 570.000 filas de checkpoint que no dicen nada, más sus blobs.

Hay un caso en que se quiere lo contrario: si el generador tuviera herramientas con efecto o una interrupción de aprobación, sus checkpoints serían lo que permite reanudarlo. Aquí no es el caso, y tampoco lo es en el analista de referencias del caso 3, que por eso lleva el mismo parámetro.

El objeto pydantic en el estado

Al ejecutar el bucle con los agentes por defecto, LangGraph 1.2.11 escribe esto al deserializar el checkpoint del subgrafo:

Deserializing unregistered type __main__.Ficha from checkpoint. This will be blocked in a
future version. Set LANGGRAPH_STRICT_MSGPACK=true to block now, or add to
allowed_msgpack_modules to allow explicitly: [('__main__', 'Ficha')]

structured_response en el estado del agente es un objeto Ficha. El serializador lo guarda con su módulo y su clase, y al leerlo comprueba que el tipo esté permitido. Hoy es un aviso; el mensaje dice que será bloqueo. Cuando lo sea, un checkpoint escrito hoy con un objeto pydantic dentro no se podrá leer con la versión de mañana.

Tres formas de no tener el problema, y aquí se usan las tres. El estado del padre solo lleva diccionarios: model_dump() en cuanto el objeto sale del agente. Los subgrafos no persisten, así que no hay checkpoint con el objeto. Y el checkpointer del padre se construye con un serializador que conoce el módulo de los esquemas, por si alguna vez uno se cuela:

from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer

checkpointer = PostgresSaver(
 pool_agentes,
 serde=JsonPlusSerializer(allowed_msgpack_modules=[("fichas.esquemas", "Ficha"), ("fichas.esquemas", "Veredicto")]),
)

Es la misma regla que en el caso 2 con el contexto y en el caso 3 con motivo: lo que va al checkpoint se decide, no se deja caer.

Lo que se mide

Métrica	Dónde	Qué dice
Tasa de aprobación al primer, segundo y tercer intento	`historial` en la tabla de fichas	La curva del bucle. Si el tercer intento aprueba menos del 10 por ciento de lo que llegó a él, el tope debería ser dos
Criterios más rechazados por intento	`historial[*].veredicto.problemas`	Un criterio que se rechaza siempre en el primer intento y nunca en el segundo es una instrucción que falta en el prompt del generador
Fichas a revisión manual	`estado = 'revision_manual'`	Debe bajar con el tiempo. Si no baja, los criterios y el prompt están desalineados
Rechazos forzados por código con veredicto del modelo aprobado	`comprobaciones` frente a `veredicto`	Cuántas veces el modelo aprobó algo que `len()` rechazó. Es la medida de cuánto no se puede fiar uno del evaluador en lo mecánico
Tokens por ficha publicada	Langfuse, `caso=fichas`, dividido por publicadas	Unos 2.500 por intento con los prompts actuales; el coste real es este número por la media de intentos
Devoluciones con motivo “no coincide con la descripción”	Tabla de devoluciones, 90 días después	La métrica de negocio. Tarda en llegar y es la que importa
Fichas revisadas al azar por catálogo que se rechazan	Muestreo manual semanal	La calibración del evaluador. Si catálogo rechaza más del 5 por ciento de lo que el evaluador aprobó, los criterios están mal descritos

La última fila es la que hace que el sistema no se degrade sin que nadie lo vea. Un evaluador con modelo aprueba lo que su prompt le dice que apruebe; una muestra semanal leída por una persona es lo que mantiene el prompt honesto.

Checklist

Los criterios viven en una tabla versionada, con la parte mecánica comprobada en código.
El evaluador no ve el prompt del generador, sus intentos anteriores ni el número de intento.
El generador recibe el origen y los problemas, no su ficha anterior.
decidir lee aprobada e intentos y no llama al modelo.
evaluar fuerza el rechazo si una comprobación en código falla.
Los dos agentes llevan ProviderStrategy y el modelo lleva structured_output: True en el perfil.
Los esquemas son planos y las restricciones de longitud están también en código.
Los dos agentes llevan checkpointer=False.
El estado del padre solo tiene diccionarios; model_dump() a la salida de cada agente.
allowed_msgpack_modules en el checkpointer registra el módulo de los esquemas.
Hay una muestra semanal de fichas aprobadas que lee una persona.

Trampas y cosas que no son lo que parecen

response_format=Ficha con un modelo de vLLM es una herramienta, no un response_format. Sin perfil, LangChain no sabe que el proveedor admite salida estructurada y usa ToolStrategy. Funciona, pero paga la definición de la herramienta en cada llamada y falla de otra manera. ProviderStrategy explícito y structured_output: True en el perfil.

Un agente dentro de un nodo persiste solo. Hereda el checkpointer del padre y escribe bajo su espacio de nombres. 30 filas por ficha en vez de 12. checkpointer=False cuando no hay nada que reanudar.

El objeto pydantic en el checkpoint es un aviso hoy y un error mañana. model_dump() antes de escribir en el estado, y allowed_msgpack_modules como red.

Las restricciones del esquema no las aplica el servidor. max_length lo valida pydantic después de generar. La primera barrera para lo mecánico es código antes del evaluador.

El evaluador aprueba más si sabe que es el último intento. No se le dice. Tampoco se le dice qué intentó el generador. Solo la ficha, las comprobaciones, el origen y los criterios.

Darle al generador su ficha anterior empeora. Reescribe lo que estaba bien y reintroduce problemas. Origen más lista de problemas.

El tope de intentos no se calibra a ojo. Se mide la aprobación por intento. Si el tercero apenas aprueba, es coste sin resultado y el tope baja a dos.

Cierre

El agente de fichas es dos llamadas al modelo por intento y un contador. Lo que lo hace fiable no está en las llamadas: está en que el evaluador no ve lo que no debe, en que lo mecánico se comprueba sin modelo antes y después, en que el bucle lo cierra una función y no el modelo, y en que lo que entra en el checkpoint es lo que se ha decidido que entre. Y una muestra semanal leída por alguien de catálogo, que es lo que mantiene los criterios pegados a la realidad.

Con esto los cuatro casos están escritos. El siguiente y último artículo de la serie no construye ningún agente: sirve los cuatro en el mismo cluster, sin el servidor de LangGraph, con la autorización por hilo, la retención y las sondas que ninguno de los cuatro tiene.

Ver también

Fuentes

Salida estructurada en LangChain 1.x (ToolStrategy, ProviderStrategy): https://docs.langchain.com/oss/python/langchain/structured-output
API de grafos de LangGraph (reductores, aristas condicionales, subgrafos): https://docs.langchain.com/oss/python/langgraph/graph-api
Código de langchain.agents.factory (langchain 1.4.1): _supports_provider_strategy y la resolución de AutoStrategy
Código de langgraph.checkpoint.serde.jsonplus (langgraph-checkpoint 4.2.0): aviso de tipos no registrados y allowed_msgpack_modules
vLLM, salida estructurada y decodificación guiada: https://docs.vllm.ai/en/latest/features/structured_outputs.html

Agente de cadena de suministro con LangGraph: incidencias con proveedores y reposición con plan-and-execute y map-reduce sobre miles de referencias

Thu, 17 Sep 2026 02:30:00 +0200

TL;DR

El modelo no ve treinta mil referencias. Ve las que un filtro en SQL declara en riesgo: cobertura por debajo del plazo del proveedor o incidencia abierta. Con un catálogo de 30.000 y una tasa de riesgo normal, son entre quinientas y dos mil. El primer ahorro del agente no es del modelo; es del WHERE.

El abanico se hace con Send desde una arista condicional, un nodo trabajador por lote de referencias, un reductor operator.add en el estado, y un nodo de consolidación con defer=True. Todo el abanico corre en un superstep. Verificado en un grafo de prueba con solo el abanico y la consolidación: 2.000 trabajadores dejan 4 checkpoints, no 2.000.

Lo que sí crece con el abanico son las escrituras y el tamaño del checkpoint. 2.000 envíos de una referencia cada uno son 6.003 filas en checkpoint_writes y un checkpoint de 287 KB con la lista de resultados entera. En lotes de 50, 123 filas. El tamaño del checkpoint no baja con los lotes, porque el estado consolidado es el mismo; baja acotando lo que cada trabajador devuelve.

En modo síncrono el abanico corre en un pool de hilos con el valor por defecto de Python, cinco en un pod de una CPU. En modo asíncrono corre sin límite: 2.000 tareas en vuelo a la vez. max_concurrency en la configuración lo acota en los dos modos, y hay que fijarlo al valor que el gateway y vLLM puedan absorber.

Un trabajador que falla tumba el invoke, pero no pierde a los demás: sus escrituras quedan como pendientes y la reanudación ejecuta solo el que falló. Con retry_policy en el nodo, el fallo transitorio contra el gateway ni siquiera sale del grafo.

La caché por nodo con cache_policy hace que la segunda pasada del día sobre las mismas referencias no llame al modelo: 0 llamadas reales en 200 referencias ya analizadas, con la clave por defecto sobre la entrada del nodo. Es lo que permite relanzar el análisis a media mañana sin pagar la mañana entera otra vez.

Estás aquí: del cliente al almacén

Este es el caso 3 de la serie de agentes con LangGraph para retail. Los dos anteriores, el asistente de sala y el agente de cliente, son conversaciones: una persona pregunta, el agente contesta, y el volumen lo marca la persona. Este no tiene persona delante. Lo lanza una tarea a las seis de la mañana, recorre el catálogo, y deja una propuesta de reposición para que compras la revise a las nueve.

Eso cambia el problema. Ya no importa la latencia de una respuesta, importa el coste total de la pasada, cuánto tarda, cuánto carga el servidor de inferencia, y qué pasa cuando se cae a la mitad. Y como el modelo se llama cientos o miles de veces con el mismo prompt y datos distintos, cada token del prompt cuenta cientos o miles de veces.

Es el primer caso de la serie que se escribe sobre StateGraph y no sobre create_agent. El agente del caso 1 vuelve a aparecer, como subgrafo, en el sitio donde hace falta razonar sobre una referencia con sus incidencias y su historial; el resto del grafo es determinista y no lleva modelo.

La analogía: la ronda del jefe de compras

Un jefe de compras con treinta mil referencias no las repasa una a una cada mañana. Mira un listado que el sistema le saca ordenado por riesgo, decide por dónde empieza (los proveedores con incidencias, las familias que rotan más), reparte el listado entre dos compradores, y al final junta lo que le traen en un pedido por proveedor. Si a media mañana llega un aviso de un proveedor, vuelve a mirar solo las referencias de ese proveedor.

El filtro es el listado del sistema. El planificador es el “por dónde empiezo”. El abanico son los compradores trabajando a la vez. La consolidación es el pedido por proveedor. Y la caché es no volver a mirar lo que ya se miró esta mañana.

El filtro determinista

La primera decisión de diseño es qué referencias llegan al modelo. La respuesta es un SELECT, no un prompt:

WITH cobertura AS (
 SELECT s.sku,
 sum(s.unidades - s.reservadas) AS unidades,
 sum(s.unidades - s.reservadas) / nullif(v.media_diaria, 0) AS dias_cobertura
 FROM stock s
 JOIN ventas_media_30d v USING (sku)
 GROUP BY s.sku, v.media_diaria
),
riesgo AS (
 SELECT p.sku, p.proveedor_id, pr.plazo_dias, c.unidades, c.dias_cobertura,
 i.id AS incidencia_id, i.tipo AS incidencia_tipo, i.abierta_ts
 FROM productos p
 JOIN proveedores pr USING (proveedor_id)
 JOIN cobertura c USING (sku)
 LEFT JOIN incidencias i ON i.sku = p.sku AND i.cerrada_ts IS NULL
 WHERE c.dias_cobertura < pr.plazo_dias * 1.5
 OR i.id IS NOT NULL
)
SELECT * FROM riesgo ORDER BY proveedor_id, dias_cobertura NULLS FIRST;

Con esto, la referencia entra en el análisis si su cobertura no llega a una vez y media el plazo del proveedor, o si tiene una incidencia abierta. El multiplicador 1,5 es un parámetro de compras, no del agente, y vive en una tabla de configuración. Sobre un catálogo generado de 30.000 referencias con una distribución de ventas realista, el filtro devuelve entre 500 y 2.000 filas según el día. Ese es el volumen que ve el modelo.

Todo lo demás, las referencias con cobertura holgada y sin incidencias, no genera tokens. Un agente que le pregunte al modelo “¿hay que reponer esto?” para cada una de las 30.000 está pagando 28.000 respuestas que un WHERE da gratis.

El estado

import operator
from typing import Annotated, TypedDict

class Referencia(TypedDict):
 sku: str
 proveedor_id: str
 plazo_dias: int
 unidades: int
 dias_cobertura: float | None
 incidencia: dict | None

class Analisis(TypedDict):
 sku: str
 proveedor_id: str
 riesgo: str # "alto" | "medio" | "bajo"
 accion: str # "pedir" | "esperar" | "sustituir_proveedor" | "reclamar"
 unidades: int
 motivo: str # una frase, acotada por el prompt

class EstadoCompras(TypedDict):
 fecha: str
 candidatas: list[Referencia]
 plan: dict
 analisis: Annotated[list[Analisis], operator.add]
 propuesta: dict
 pasada: int

Dos decisiones aquí. analisis es la única clave con reductor, y es la única en la que escriben los trabajadores. motivo está limitado a una frase en el prompt y a 200 caracteres en la validación, porque ese campo multiplicado por dos mil es lo que hace crecer el checkpoint. Un análisis de 180 bytes por referencia son 360 KB por checkpoint con dos mil; uno de 1 KB con explicaciones largas, 2 MB, y ese checkpoint se escribe en cada superstep posterior al abanico.

El planificador

El planificador es la única llamada al modelo que ve el conjunto entero, y no ve las referencias: ve un resumen por proveedor. Con salida estructurada:

from pydantic import BaseModel, Field

class PasoPlan(BaseModel):
 proveedor_id: str
 prioridad: int = Field(ge=1, le=3)
 enfoque: str = Field(description="qué mirar primero en este proveedor, una frase")

class Plan(BaseModel):
 pasos: list[PasoPlan]
 proveedores_a_reclamar: list[str]

planificador = modelo.with_structured_output(Plan, method="json_schema")

def planificar(state: EstadoCompras) -> dict:
 resumen = resumen_por_proveedor(state["candidatas"]) # SQL: n_refs, n_incidencias, plazo, sla
 plan = planificador.invoke([
 {"role": "system", "content": PROMPT_PLANIFICADOR},
 {"role": "user", "content": json.dumps(resumen, ensure_ascii=False)},
 ])
 return {"plan": plan.model_dump()}

method="json_schema" envía response_format con el esquema JSON al gateway, y vLLM lo aplica con decodificación guiada. Con un modelo de clase 30B es fiable para esquemas de este tamaño; con esquemas anidados profundos se ha visto que la decodificación guiada alarga la generación, y este esquema se mantiene plano a propósito.

El plan no decide qué referencias se analizan; eso lo decidió el filtro. Decide en qué orden van los proveedores, qué enfoque lleva cada trabajador en el prompt, y qué proveedores tienen tantas incidencias que lo que toca es reclamar y no pedir. Es una llamada al modelo por pasada, con un prompt de un par de miles de tokens. Su coste es despreciable frente al abanico; su valor es que el prompt de cada trabajador lleva una línea de contexto del proveedor que el trabajador no tendría.

El abanico

from langgraph.types import Send

LOTE = 50

def repartir(state: EstadoCompras) -> list[Send]:
 plan = {p["proveedor_id"]: p for p in state["plan"]["pasos"]}
 por_proveedor: dict[str, list[Referencia]] = {}
 for r in state["candidatas"]:
 por_proveedor.setdefault(r["proveedor_id"], []).append(r)
 envios = []
 for proveedor_id, refs in por_proveedor.items():
 enfoque = plan.get(proveedor_id, {}).get("enfoque", "")
 for i in range(0, len(refs), LOTE):
 envios.append(Send("analizar_lote", {
 "fecha": state["fecha"],
 "proveedor_id": proveedor_id,
 "enfoque": enfoque,
 "referencias": refs[i:i + LOTE],
 }))
 return envios

repartir es la función de una arista condicional. Devuelve una lista de Send, y cada uno lanza una instancia de analizar_lote con su propio estado de entrada. Todas corren en el mismo superstep, y el grafo no avanza hasta que todas terminan.

El lote de 50 no es por el modelo. Cada referencia se analiza en su propia llamada al modelo dentro del trabajador; el lote existe por las escrituras del checkpoint. Medido con 2.000 referencias y un resultado de unos 180 bytes por referencia:

Reparto	Checkpoints	Filas en `checkpoint_writes`	Bytes de escrituras	Tamaño del checkpoint mayor
Un `Send` por referencia	4	6.003	946 KB	287 KB
Un `Send` por lote de 50	4	123	319 KB	287 KB

Medido con InMemorySaver y el serializador JsonPlusSerializer, que es el mismo que usa el checkpointer de Postgres. Las filas de escrituras son las tareas pendientes del superstep: tres por tarea de una referencia. En Postgres son filas de checkpoint_writes, con su índice, y con treinta mil referencias serían noventa mil filas por pasada. El tamaño del checkpoint no cambia con el lote, porque es la lista de análisis consolidada, y se repite en cada checkpoint posterior al abanico.

El trabajador

from langgraph.types import CachePolicy, RetryPolicy

def analizar_lote(lote: dict) -> dict:
 resultados = []
 for ref in lote["referencias"]:
 historial = historial_incidencias(ref["sku"], dias=90) # SQL, sin modelo
 salida = analista.invoke({
 "messages": [{"role": "user", "content": prompt_referencia(ref, historial, lote["enfoque"])}],
 }, context=ContextoCompras(fecha=lote["fecha"], proveedor_id=lote["proveedor_id"]))
 resultados.append(salida["structured_response"].model_dump())
 return {"analisis": resultados}

grafo.add_node(
 "analizar_lote",
 analizar_lote,
 cache_policy=CachePolicy(ttl=12 * 3600),
 retry_policy=RetryPolicy(max_attempts=3, initial_interval=1.0, backoff_factor=2.0),
)

analista es un create_agent con response_format=ProviderStrategy(Analisis), una herramienta de consulta de incidencias por proveedor, el mismo ToolErrorMiddleware y límites del caso 1, y checkpointer=False. Lo último importa: un agente invocado dentro de un nodo hereda el checkpointer del grafo padre y escribe sus propios checkpoints bajo un espacio de nombres, tres por invocación; con dos mil referencias son seis mil filas que no sirven para reanudar nada. Se mide en el caso 4. Devuelve structured_response validado. El prompt por referencia lleva la referencia, su cobertura, su incidencia si la hay, el historial de 90 días en cinco líneas, y el enfoque del plan. Son unos 600 tokens de entrada y unos 120 de salida por referencia.

Dos mil referencias son 1,2 millones de tokens de entrada y 240.000 de salida por pasada. Con el prefijo del prompt del sistema compartido, y el gateway configurado para que las peticiones del mismo grupo de modelos caigan en la misma réplica, la mayor parte de esos 600 tokens de entrada acierta en la caché de prefijo de vLLM; la parte variable son las líneas de la referencia y el historial. Esto se mide con vllm:prefix_cache_hits frente a vllm:prefix_cache_queries durante la pasada, y es la primera cifra que hay que mirar si el coste no cuadra.

La concurrencia

En modo síncrono, LangGraph ejecuta las tareas del superstep en un pool de hilos con el valor por defecto de Python: el número de CPU más cuatro, con un tope de 32. En un pod con una CPU son cinco tareas en vuelo, medido. max_concurrency en la configuración lo cambia: con 32, se ven 32 en vuelo.

En modo asíncrono, con ainvoke, no hay pool y no hay límite: con 2.000 envíos se han medido 2.000 tareas en vuelo a la vez. Contra un gateway con un límite de peticiones por clave, eso es una tormenta de 429 en el primer segundo. max_concurrency también aplica en este modo, y es obligatorio:

config = {
 "configurable": {"thread_id": f"compras:{fecha}"},
 "max_concurrency": 24,
 "metadata": {"caso": "compras", "fecha": fecha},
 "callbacks": [langfuse_handler],
}
resultado = await grafo.ainvoke(estado_inicial, config=config, durability="sync")

El 24 sale del gateway: la clave virtual del agente de compras tiene max_parallel_requests a 24, y por debajo vLLM con --max-num-seqs a 64 reparte entre este agente y el tráfico de sala. Un max_concurrency por encima del límite de la clave solo produce 429 y reintentos; por debajo, deja capacidad sin usar. Con 24 en vuelo y unos dos segundos por referencia en un modelo de clase 30B, dos mil referencias son unos tres minutos de abanico. Las cifras de tiempo por referencia son las que hay que medir en cada despliegue; la aritmética es la que vale.

El fallo a medias

Con retry_policy en el nodo, un error de conexión con el gateway se reintenta dentro del grafo, con retroceso exponencial, y el trabajador termina sin que el invoke se entere. Verificado con un trabajador que falla la primera vez: el abanico de 20 acaba con 20 resultados.

Sin retry_policy, la excepción sale de invoke. Lo que no se pierde es el trabajo de los demás: verificado con un abanico de 20 en el que uno falla, el estado tras el fallo tiene 19 resultados guardados como escrituras pendientes, next apunta al nodo trabajador, y invoke(None, config) sobre el mismo hilo ejecuta solo la tarea que faltaba. Diecinueve llamadas al modelo que no se repiten.

Lo que sí se repite es un lote en vuelo cuando muere el pod: sus 50 referencias vuelven a analizarse. Aquí no hay dinero de por medio y el análisis es idempotente por naturaleza, así que la única consecuencia es el coste, y la caché lo cubre: si el lote ya había terminado alguna referencia, no, porque la caché es por nodo y el nodo no terminó. Es un argumento más para lotes pequeños.

La consolidación

def consolidar(state: EstadoCompras) -> dict:
 por_proveedor: dict[str, list[Analisis]] = {}
 for a in state["analisis"]:
 por_proveedor.setdefault(a["proveedor_id"], []).append(a)
 propuesta = {
 "fecha": state["fecha"],
 "pedidos": [
 {
 "proveedor_id": pid,
 "lineas": [{"sku": a["sku"], "unidades": a["unidades"]} for a in items if a["accion"] == "pedir"],
 "reclamaciones": [a["sku"] for a in items if a["accion"] == "reclamar"],
 "n_alto": sum(1 for a in items if a["riesgo"] == "alto"),
 }
 for pid, items in sorted(por_proveedor.items())
 ],
 "sin_analizar": faltan(state["candidatas"], state["analisis"]),
 }
 return {"propuesta": propuesta, "pasada": state["pasada"] + 1}

grafo.add_node("consolidar", consolidar, defer=True)

defer=True retrasa el nodo hasta que no quede ningún camino pendiente hacia él. Sin ese parámetro, consolidar se ejecutaría en cuanto terminara el primer lote, con una lista de análisis parcial. Con él, se ejecuta una vez, después de todo el abanico, y ve la lista completa. Verificado con stream_mode="updates": cinco lotes, cinco actualizaciones de analizar_lote y una de consolidar al final.

El orden de analisis es determinista. Los reductores se aplican al final del superstep en el orden de las tareas, que es el orden de los Send; verificado que la lista consolidada sigue el orden del reparto aunque los trabajadores terminen en otro. No hay que ordenar después, y un análisis que dependa del orden de llegada no tiene forma de depender de él.

sin_analizar es la lista de candidatas que no tienen análisis. En una pasada limpia es vacía; si un lote fue cortado por los límites del agente analista o devolvió un error, sus referencias aparecen ahí, y el nodo siguiente decide si se relanza.

Replanificar

def decidir(state: EstadoCompras) -> str:
 if state["propuesta"]["sin_analizar"] and state["pasada"] < 3:
 return "reintentar"
 return "entregar"

def reintentar(state: EstadoCompras) -> dict:
 pendientes = {r["sku"] for r in state["propuesta"]["sin_analizar"]}
 return {"candidatas": [r for r in state["candidatas"] if r["sku"] in pendientes]}

grafo.add_edge(START, "cargar")
grafo.add_edge("cargar", "planificar")
grafo.add_conditional_edges("planificar", repartir, ["analizar_lote"])
grafo.add_edge("analizar_lote", "consolidar")
grafo.add_conditional_edges("consolidar", decidir, {"reintentar": "reintentar", "entregar": "entregar"})
grafo.add_conditional_edges("reintentar", repartir, ["analizar_lote"])
grafo.add_edge("entregar", END)

Es el plan-and-execute en su forma mínima: planificar, ejecutar en abanico, consolidar, y volver a ejecutar solo lo que falta, con un contador. El modelo no decide si se repite; lo decide decidir leyendo sin_analizar y pasada. Tres pasadas como máximo. Lo que quede sin analizar después de tres va en la propuesta marcado como tal, y compras lo mira a mano.

Una segunda pasada no vuelve a llamar al planificador. El plan de la primera sigue en el estado y repartir lo lee. Volver a planificar tendría sentido si el conjunto de candidatas cambiara, y en una pasada no cambia.

La caché por nodo

cache_policy=CachePolicy(ttl=12 * 3600) en analizar_lote hace que el grafo, antes de ejecutar el nodo, calcule una clave a partir de la entrada del nodo y busque en la caché. Con la clave por defecto, la entrada del lote entera es la clave: fecha, proveedor, enfoque y las 50 referencias con sus cifras.

Verificado: una pasada sobre 200 referencias hace 200 llamadas; una segunda pasada sobre las mismas 200, en otro hilo, hace 0 y termina en dos centésimas de segundo. En las actualizaciones del flujo, cada lote cacheado llega con __metadata__ y cached: True.

Para que la caché sirva en una tienda hay que decidir la clave. Con la clave por defecto, cualquier cambio en las unidades de una referencia invalida el lote entero, que es lo correcto si el stock cambió, y demasiado si cambió una unidad. La versión de producción usa una key_func propia que redondea la cobertura a días enteros y quita del lote los campos que no afectan al análisis:

def clave_lote(lote: dict) -> str:
 base = [
 (r["sku"], r["proveedor_id"], round(r["dias_cobertura"] or 0),
 (r["incidencia"] or {}).get("id"))
 for r in lote["referencias"]
 ]
 return hashlib.sha256(json.dumps([lote["fecha"], lote["enfoque"], base]).encode()).hexdigest()

cache_policy=CachePolicy(key_func=clave_lote, ttl=12 * 3600)

La caché no es el checkpointer. Es un BaseCache que se pasa en compile(cache=...), y en un cluster con varias réplicas del agente tiene que ser compartida. El paquete trae InMemoryCache y RedisCache (langgraph.cache.redis, construido sobre un cliente de redis); la interfaz son seis métodos (get, set, clear y sus versiones asíncronas) si se quiere una sobre una tabla de Postgres. Con InMemoryCache, cada pod tiene la suya y la segunda pasada solo ahorra si cae en el mismo pod.

Lo que se mide

Métrica	Dónde	Qué dice
Candidatas por pasada frente a catálogo	`SELECT` del filtro	Cuánto trabajo ve el modelo. Si sube del 10 por ciento, el multiplicador del filtro es alto o hay un problema de stock real
Tokens por referencia analizada	Langfuse, generaciones bajo `caso=compras` divididas por candidatas	Unos 700 con el prompt actual. Si sube, el historial se ha alargado o el motivo se ha desbordado
Aciertos de caché de prefijo durante la pasada	`vllm:prefix_cache_hits` / `vllm:prefix_cache_queries`	Por encima del 70 por ciento con el prompt del sistema compartido y afinidad en el gateway. Por debajo, las peticiones se reparten entre réplicas
Aciertos de caché de nodo	`__metadata__.cached` en el flujo, contados	Solo cuentan en pasadas repetidas. Cero en la primera del día es lo normal
Duración del abanico frente a candidatas	Traza del hilo, span de `analizar_lote`	Lineal con candidatas y `max_concurrency`. Si no es lineal, el gateway está encolando
Filas en `checkpoint_writes` por pasada	Postgres	Candidatas dividido por lote, por tres. Si crece más, el lote se ha reducido o hay reintentos
`sin_analizar` tras la tercera pasada	`propuesta`	Debe ser cero casi siempre. Cada referencia ahí es una llamada al modelo que no terminó
Líneas de pedido aceptadas por compras frente a propuestas	Tabla de pedidos de compra	La métrica de negocio. Un 70 por ciento de aceptación sin edición es una propuesta útil; un 30, un agente que hay que afinar

La propuesta consolidada no se convierte en pedido sola. entregar la escribe en propuestas_reposicion y abre la aprobación de compras con el mismo patrón del caso 2: un hilo por propuesta, una interrupción con las líneas por proveedor, y un comprador que aprueba, edita cantidades o rechaza. Lo que cambia respecto al caso 2 es el tamaño del vale: son cientos de líneas, y la interfaz de aprobación es una tabla editable, no un botón.

Checklist

El filtro de candidatas es SQL y su multiplicador vive en configuración.
Analisis acota motivo a una frase y a 200 caracteres.
El planificador ve un resumen por proveedor, no las referencias, y usa with_structured_output(..., method="json_schema").
repartir agrupa por proveedor y envía lotes de 50.
analizar_lote tiene cache_policy con key_func propia y retry_policy.
consolidar lleva defer=True.
max_concurrency está en la configuración y coincide con max_parallel_requests de la clave del gateway.
La caché se pasa en compile(cache=...) y es compartida entre réplicas (RedisCache o propia).
Hay un contador de pasadas y un tope de tres.
La propuesta pasa por aprobación de compras antes de ser pedido.
Se ha medido vllm:prefix_cache_hits durante una pasada completa.

Trampas y cosas que no son lo que parecen

El abanico asíncrono no tiene límite. 2.000 en vuelo, medido. Sin max_concurrency el primer efecto es una ráfaga de 429 del gateway y el segundo, los reintentos multiplicando la ráfaga.

El abanico síncrono tiene un límite que no es el suyo. Cinco en un pod de una CPU, por el pool de hilos de Python. Un agente que parece lento en producción y rápido en el portátil de ocho núcleos está pagando esta diferencia.

Los lotes reducen filas, no bytes de checkpoint. El checkpoint lleva la lista consolidada, y esa lista es la misma se envíe como se envíe. Lo que la reduce es acotar lo que cada análisis devuelve.

defer=True no es opcional. Sin él, la consolidación corre con el primer lote que termina. El grafo no avisa; la propuesta sale con una fracción de las referencias.

La caché por defecto es por entrada exacta. Una unidad de stock de diferencia invalida el lote. key_func propia, o la caché no acierta nunca fuera de las pruebas.

InMemoryCache es por pod. Con tres réplicas, dos tercios de las repeticiones no aciertan. RedisCache viene en el paquete; una sobre Postgres son seis métodos.

La re-ejecución tras un fallo es por tarea, no por superstep. Los que terminaron no se repiten. Pero el lote en vuelo cuando muere el pod sí, entero, y sus referencias ya analizadas dentro del lote también. Lotes pequeños.

El planificador no puede añadir referencias. Si el filtro no las sacó, el modelo no las ve. Un jefe de compras que eche en falta una referencia en la propuesta tiene que mirar el filtro, no el prompt.

Cierre

El agente de compras es determinista en todo menos en dos sitios: el plan por proveedor y el análisis por referencia. Todo lo demás, el filtro, el reparto, la consolidación, la decisión de repetir y el tope, es código que no llama al modelo. Es la proporción que hace que treinta mil referencias sean dos mil llamadas y no treinta mil, que una caída a media pasada cueste un lote y no la mañana, y que la segunda pasada del día cueste cero.

Las primitivas que lo permiten son cuatro y son de StateGraph: Send desde una arista condicional, un reductor en el estado, defer=True en la consolidación, y cache_policy con clave propia. Y un parámetro de configuración, max_concurrency, que no está en el grafo y sin el cual el grafo tumba el gateway.

El siguiente caso vuelve a una escala pequeña, una ficha de producto cada vez, y cambia el problema: no es cuántas veces se llama al modelo, es cuántas veces se le deja corregirse antes de decir que no.

Ver también

Fuentes

API de grafos de LangGraph (Send, reductores, defer, cache_policy, retry_policy): https://docs.langchain.com/oss/python/langgraph/graph-api
Persistencia y durabilidad en LangGraph: https://docs.langchain.com/oss/python/langgraph/persistence
Salida estructurada en LangChain 1.x: https://docs.langchain.com/oss/python/langchain/structured-output
Código de langgraph.types (langgraph 1.2.11): Send, CachePolicy, RetryPolicy
Código de langgraph.checkpoint.serde.jsonplus (langgraph-checkpoint 4.2.0), usado para medir los tamaños
Métricas de vLLM 0.29 (vllm:prefix_cache_queries, vllm:prefix_cache_hits): https://docs.vllm.ai/en/latest/usage/metrics.html

Agente de atención al cliente con LangGraph: pedidos, devoluciones y sustituciones con el límite de aprobación humana en el código

Thu, 17 Sep 2026 02:00:00 +0200

TL;DR

El límite de la aprobación humana no está en el prompt ni en la interfaz. Está en un middleware que intercepta la llamada a la herramienta con efecto, evalúa una condición sobre los argumentos, el estado y el contexto, y si se cumple para el grafo antes de que la herramienta corra. Verificado: la interrupción salta en un nodo posterior al modelo y anterior a tools, y la herramienta no se ejecuta hasta que un humano decide.

El humano puede aprobar, editar los argumentos, rechazar con motivo o responder en lugar de la herramienta. Son las cuatro decisiones que admite HumanInTheLoopMiddleware en langchain 1.4.1, y las cuatro tienen un contrato de datos fijo que la aplicación de aprobaciones tiene que hablar. Editar el importe de un reembolso de 120 a 90 hace que la herramienta corra con 90; se ha comprobado con la herramienta instrumentada.

interrupt() sin checkpointer no falla al interrumpir. Devuelve el valor en __interrupt__ como si todo fuera bien, y falla al reanudar con Cannot use Command(resume=...) without checkpointer. Un despliegue sin persistencia parece funcionar hasta que el primer encargado pulsa aprobar.

Al reanudar, el nodo que interrumpió se ejecuta entero otra vez. Con un nodo propio, lo que haya antes de la interrupción corre dos veces. Con el middleware, la interrupción vive en su propio nodo y la herramienta corre después, una vez. Lo que sigue pudiendo correr dos veces es la herramienta cuando el pod muere con ella en vuelo, y por eso el reembolso lleva el identificador de la llamada como clave de idempotencia.

El checkpointer no sabe listar hilos interrumpidos. La cola de aprobaciones es una tabla propia que la aplicación escribe cuando invoke devuelve __interrupt__ y borra cuando se reanuda. Sin esa tabla, la única forma de saber qué está esperando es recordar los identificadores de hilo.

El rechazo llega al modelo como un mensaje en inglés que empieza por User rejected the tool call. El prompt le dice al modelo qué hacer con él. Sin esa línea, el modelo puede disculparse en inglés con un cliente de Talavera.

Estás aquí: el segundo caso, donde el ciclo se rompe

Este es el caso 2 de la serie de agentes con LangGraph para retail. El caso 1 construyó un asistente de sala que cabe en un ciclo modelo-herramientas. Este caso usa el mismo create_agent, el mismo contexto y el mismo checkpointer, y añade lo que el ciclo no tiene: parar, esperar a una persona que puede tardar un día, y seguir desde el mismo sitio.

El agente atiende a un cliente por el canal web sobre un pedido concreto. Puede informar del estado, iniciar una devolución con reembolso, o proponer una sustitución por otra referencia con stock. Las dos últimas tienen efecto en el dinero o en el inventario. La política de la tienda dice cuáles se hacen solas y cuáles firma un encargado.

La analogía: el vale de devolución con casilla de firma

En caja, una devolución de 20 euros con ticket la hace el dependiente. Una de 200, o sin ticket, o de un cliente que ya devolvió tres cosas este mes, lleva un vale con una casilla que firma el encargado. El dependiente rellena el vale entero, lo deja en la bandeja y atiende al siguiente. El encargado pasa cuando puede, lee el vale, y firma, tacha el importe y firma otro, o lo devuelve con una nota.

El agente es el dependiente que rellena el vale. El middleware es la casilla de firma. El checkpointer es la bandeja donde el vale espera. Y el contrato de la interrupción es el formato del vale: si el encargado no entiende lo que hay escrito, no firma.

La política, en una función

La política de aprobación es lo primero que se escribe, y se escribe como una función que devuelve verdadero cuando hace falta un humano. Recibe la llamada a herramienta que el modelo ha propuesto, el estado del hilo y el contexto de ejecución.

from langchain.agents.middleware import ToolCallRequest

def necesita_encargado(req: ToolCallRequest) -> bool:
 args = req.tool_call["args"]
 cliente = req.runtime.context.cliente_id
 if req.tool_call["name"] == "reembolsar":
 if args["importe"] > 60:
 return True
 if devoluciones_ultimos_30_dias(cliente) >= 2:
 return True
 return not pedido_entregado_hace_menos_de(args["pedido"], dias=30)
 if req.tool_call["name"] == "sustituir":
 return diferencia_pvp(args["sku_original"], args["sku_nuevo"]) > 0
 return False

Tres cosas de esta función. La primera: consulta la base de negocio, no el estado del agente. El historial de devoluciones del cliente está en devoluciones, y es la fuente que un encargado aceptaría. La segunda: recibe req.state y req.runtime; verificado que state es el estado completo del agente, con messages, y que runtime.context es el objeto de contexto que se pasó en invoke. La tercera: se ejecuta después de que el modelo haya decidido llamar a la herramienta y antes de que la herramienta corra. Si devuelve falso, la herramienta corre sin parar. Si devuelve verdadero, el grafo para.

El middleware y el contrato de la interrupción

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware

aprobacion = HumanInTheLoopMiddleware(
 interrupt_on={
 "reembolsar": {
 "allowed_decisions": ["approve", "edit", "reject"],
 "when": necesita_encargado,
 },
 "sustituir": {
 "allowed_decisions": ["approve", "reject"],
 "when": necesita_encargado,
 },
 "consultar_pedido": False,
 "stock_alternativas": False,
 },
 description_prefix="Operación fuera de política. Requiere aprobación de un encargado.",
)

agente = create_agent(
 modelo,
 tools=[consultar_pedido, stock_alternativas, reembolsar, sustituir],
 middleware=[prompt_cliente, errores, limites, aprobacion],
 context_schema=ContextoCliente,
 checkpointer=checkpointer,
)

Compilado, el grafo tiene un nodo más que el del caso 1: HumanInTheLoopMiddleware.after_model. Ahí es donde se evalúa when y se llama a interrupt. Es un nodo posterior al modelo y anterior a tools; verificado con una herramienta instrumentada que la herramienta no corre antes de la decisión.

Cuando la política dice que sí, invoke devuelve el estado con una clave __interrupt__. Es una lista de objetos Interrupt con value e id. El value tiene este formato exacto, obtenido de una ejecución con un reembolso de 120 euros:

{
 "action_requests": [
 {
 "name": "reembolsar",
 "args": {"pedido": "P-20260917-0041", "importe": 120.0},
 "description": "Operación fuera de política. Requiere aprobación de un encargado.\n\nTool: reembolsar\nArgs: {'pedido': 'P-20260917-0041', 'importe': 120.0}"
 }
 ],
 "review_configs": [
 {"action_name": "reembolsar", "allowed_decisions": ["approve", "edit", "reject"]}
 ]
}

action_requests lleva una entrada por herramienta interceptada en la misma vuelta del modelo; si el modelo pide un reembolso y una sustitución a la vez y las dos pasan la política, hay dos entradas y una sola interrupción. review_configs le dice a la interfaz qué botones pintar. El campo description es el prefijo más un volcado de la herramienta y los argumentos; para el encargado es mejor construir la descripción con una función, que InterruptOnConfig admite en description, y darle el nombre del cliente, la fecha del pedido y el motivo que el cliente dio.

Con interrupt_on={"reembolsar": True}, sin diccionario, se permiten las cuatro decisiones y no hay condición: todo reembolso para. Es el valor para empezar y para las pruebas, no para la tienda.

Las cuatro decisiones

La reanudación entra con Command(resume=...) y un diccionario con una lista decisions, en el mismo orden que action_requests.

from langgraph.types import Command

agente.invoke(
 Command(resume={"decisions": [{"type": "approve"}]}),
 config={"configurable": {"thread_id": hilo}},
)

Las cuatro, verificadas con la herramienta instrumentada:

Decisión	Formato	Qué pasa
`approve`	`{"type": "approve"}`	La herramienta corre con los argumentos que propuso el modelo
`edit`	`{"type": "edit", "edited_action": {"name": "reembolsar", "args": {...}}}`	La herramienta corre con los argumentos editados. Con el importe cambiado de 120 a 90, la herramienta recibió 90
`reject`	`{"type": "reject", "message": "Fuera de plazo, el pedido tiene 45 días."}`	La herramienta no corre. El modelo recibe un `ToolMessage` con `status="error"` y el texto `User rejected the tool call for reembolsar with reason: Fuera de plazo, el pedido tiene 45 días.`
`respond`	`{"type": "respond", "message": "Ofrece un vale en vez de reembolso."}`	La herramienta no corre. El modelo recibe un `ToolMessage` con `status="success"` y ese texto como si fuera el resultado

Dos consecuencias para el diseño.

El rechazo llega al modelo en inglés. El marco User rejected the tool call ... with reason: lo pone el middleware y no se configura. El motivo del encargado va en castellano detrás. El prompt del agente lleva esta línea: “Si una operación es rechazada por un encargado, comunica al cliente el motivo tal cual, en castellano, y no propongas repetirla”. Sin ella, se han visto respuestas que mezclan idiomas o que reintentan el reembolso con otro importe.

respond es la puerta para la resolución manual. El encargado no aprueba ni rechaza; le dice al agente qué hacer. Como la herramienta no corre, el vale o el reembolso parcial que el encargado proponga lo tiene que emitir el propio encargado en el TPV. Para este agente se deja fuera de allowed_decisions en las dos herramientas: el encargado edita o rechaza, y lo que quiera hacer distinto lo hace fuera. Es una decisión de tienda, no de código, y el sitio donde se toma es esa lista.

Lo que se persiste y lo que se repite

Una interrupción es un checkpoint más. Con el middleware de aprobación y sin los límites del caso 1, la ejecución que para en un reembolso deja 6 checkpoints; la reanudación con edit añade 4 y acaba en 10. El estado del hilo entre los dos invoke está entero en Postgres: mensajes, la llamada propuesta, y la interrupción pendiente. agente.get_state(config) lo devuelve con next=('tools',) y una tarea con la interrupción en tasks[0].interrupts.

Sobre qué se repite hay dos casos distintos que no hay que mezclar.

La re-ejecución del nodo al reanudar. Es diseño de LangGraph: el nodo que llamó a interrupt se ejecuta desde el principio cuando llega Command(resume=...), y la llamada a interrupt devuelve entonces el valor reanudado. Verificado con un nodo propio que registra efectos antes y después de la interrupción: la secuencia es antes, antes, después. Con el middleware esto no afecta a la herramienta, porque la interrupción vive en after_model y la herramienta corre en tools, un nodo después. Afecta a cualquier nodo propio que se escriba con interrupt dentro, y la regla es que la interrupción sea lo primero del nodo.

La re-ejecución de una herramienta en vuelo. Si el pod muere con reembolsar a medias, al reanudar el hilo la tarea del nodo tools se ejecuta otra vez. Las tareas que terminaron antes del fallo no: sus escrituras quedan guardadas como pendientes y se reaplican. Verificado con un abanico de 20 tareas en el que una falla: el estado tras el fallo tiene 19 resultados, y la reanudación con invoke(None, config) ejecuta solo la que faltaba. Pero la que estaba en vuelo cuando murió el proceso no deja escritura, y corre de nuevo.

Por eso reembolsar es idempotente por identificador de llamada:

from langchain.tools import tool, ToolRuntime

@tool
def reembolsar(pedido: str, importe: float, runtime: ToolRuntime[ContextoCliente]) -> dict:
 """Emite un reembolso al medio de pago original del pedido."""
 with pool.connection() as conn, conn.transaction():
 previo = conn.execute(
 "SELECT id, estado FROM reembolsos WHERE clave_idempotencia = %s",
 (runtime.tool_call_id,),
 ).fetchone()
 if previo:
 return {"ok": True, "reembolso": previo[0], "repetido": True}
 rid = conn.execute(
 "INSERT INTO reembolsos (pedido_id, importe, clave_idempotencia, aprobado_por, trace_id) "
 "VALUES (%s, %s, %s, %s, %s) RETURNING id",
 (pedido, importe, runtime.tool_call_id,
 runtime.config["metadata"].get("aprobado_por"),
 runtime.config["metadata"].get("langfuse_trace_id")),
 ).fetchone()[0]
 pasarela.reembolsar(pedido, importe, referencia=rid)
 return {"ok": True, "reembolso": rid}

runtime.tool_call_id es el identificador que el modelo puso en la llamada, y se conserva en el checkpoint. Una re-ejecución trae el mismo identificador, y la columna clave_idempotencia con restricción única lo para. La llamada a la pasarela va fuera de la transacción y con la referencia del reembolso, para que la pasarela deduplique por su lado si el proceso muere entre el INSERT y la llamada.

La durabilidad se fija en invoke. Con durability="sync", cada checkpoint se escribe antes de seguir al siguiente superstep. Es el valor para los hilos con dinero. "async" escribe en paralelo con la ejecución y puede perder el último paso si el pod muere. "exit" escribe al terminar y no vale para nada que pueda interrumpirse.

agente.invoke(
 Command(resume={"decisions": decisiones}),
 config=config,
 durability="sync",
)

La cola de aprobaciones

El checkpointer guarda cada hilo, pero no tiene ninguna consulta que devuelva los hilos que están esperando a un humano. PostgresSaver.list lista checkpoints de un hilo dado; no lista hilos. Y no hay columna de estado en checkpoints que diga “interrumpido”.

La cola es una tabla propia:

CREATE TABLE aprobaciones_pendientes (
 thread_id text PRIMARY KEY,
 tienda text NOT NULL,
 cliente_id text NOT NULL,
 interrupt_id text NOT NULL,
 peticion jsonb NOT NULL, -- el value de la interrupción
 creada timestamptz NOT NULL DEFAULT now(),
 asignada_a text,
 trace_id text
);

La aplicación la escribe cuando invoke devuelve __interrupt__ y la borra en la reanudación, en la misma transacción en la que registra quién decidió qué. Es también la tabla desde la que se mide el tiempo entre interrupción y decisión.

resultado = agente.invoke(entrada, context=ctx, config=config, durability="sync")
if interrupciones := resultado.get("__interrupt__"):
 intr = interrupciones[0]
 with pool.connection() as conn:
 conn.execute(
 "INSERT INTO aprobaciones_pendientes (thread_id, tienda, cliente_id, interrupt_id, peticion, trace_id) "
 "VALUES (%s, %s, %s, %s, %s, %s) ON CONFLICT (thread_id) DO UPDATE SET peticion = EXCLUDED.peticion",
 (config["configurable"]["thread_id"], ctx.tienda, ctx.cliente_id, intr.id,
 Json(intr.value), config["metadata"]["langfuse_trace_id"]),
 )
 return {"estado": "esperando_aprobacion", "mensaje_cliente": mensaje_espera(intr.value)}

Y del lado del encargado, la reanudación con el registro de quién decidió:

def decidir(thread_id: str, encargado: str, decisiones: list[dict]):
 config = {
 "configurable": {"thread_id": thread_id},
 "metadata": {"aprobado_por": encargado},
 "callbacks": [langfuse_handler],
 }
 resultado = agente.invoke(Command(resume={"decisions": decisiones}), config=config, durability="sync")
 with pool.connection() as conn, conn.transaction():
 conn.execute("DELETE FROM aprobaciones_pendientes WHERE thread_id = %s", (thread_id,))
 conn.execute(
 "INSERT INTO decisiones_encargado (thread_id, encargado, decisiones) VALUES (%s, %s, %s)",
 (thread_id, encargado, Json(decisiones)),
 )
 return resultado["messages"][-1].content

El contexto del cliente no viaja en esta llamada. Command(resume=...) se invoca sin context, y el prompt dinámico y las herramientas lo leen del runtime: en la reanudación, runtime.context es None si no se pasa. Verificado con un prompt dinámico que registra el contexto en cada llamada al modelo: C1 en la primera, None tras Command(resume=...) sin context. Hay dos opciones: guardar el contexto del cliente en el estado del agente con un state_schema propio, o pasarlo otra vez en la reanudación leyéndolo de la cola. Aquí se hace lo segundo, porque el contexto tiene el identificador del cliente y no se quiere en el checkpoint más de lo necesario. La función real de decidir carga ContextoCliente de aprobaciones_pendientes y lo pasa en context=.

Quién puede reanudar es autorización de la capa HTTP: decidir solo se llama desde un endpoint que exige rol de encargado y comprueba que la tienda del encargado es la de la fila. El checkpointer acepta cualquier Command(resume=...) para cualquier thread_id, y eso se documenta en el marco de la serie.

El prompt

@dynamic_prompt
def prompt_cliente(request: ModelRequest) -> str:
 ctx = request.runtime.context
 return (
 f"Atiendes al cliente {ctx.cliente_id} de la tienda {ctx.tienda} sobre su pedido. "
 "Consulta el pedido antes de proponer nada. "
 "Para devolver, usa reembolsar con el importe de las líneas devueltas; para cambiar por otra referencia, "
 "comprueba stock_alternativas y usa sustituir. "
 "Algunas operaciones esperan la aprobación de un encargado; si es así, dile al cliente que la operación "
 "queda pendiente y que recibirá confirmación, sin prometer un plazo. "
 "Si un encargado rechaza una operación, comunica el motivo tal cual, en castellano, y no la repitas "
 "con otros valores. Nunca inventes un número de reembolso: solo el que devuelva la herramienta."
 )

La frase sobre la aprobación pendiente importa porque el modelo no ve la interrupción. Desde su punto de vista, pidió una herramienta y la conversación se detuvo. Cuando el hilo se reanuda con approve, lo siguiente que ve es el resultado de la herramienta, como si no hubiera pasado tiempo. Es la aplicación la que le dice al cliente que espere, con mensaje_espera, no el modelo. Y en la reanudación, el mensaje que el modelo genera tras el resultado es el que se le envía al cliente por el canal que corresponda, con el retraso que haya habido.

Una devolución fuera de política, de principio a fin

Con las herramientas reales sobre el catálogo de prueba y las respuestas del modelo guionizadas, como en el caso 1:

Cliente: Quiero devolver el pedido P-20260917-0041, la cafetera llegó con la jarra rota.
[tools] consultar_pedido(pedido="P-20260917-0041") -> {"pedido": "...", "importe": 120.0, "entregado": true, "dias_desde_entrega": 4, "lineas": [...]}
[after_model] reembolsar(pedido="P-20260917-0041", importe=120.0) -> when=True (importe > 60)
[__interrupt__] {"action_requests": [{"name": "reembolsar", "args": {"pedido": "P-20260917-0041", "importe": 120.0}, ...}], ...}
Aplicación -> Cliente: Tu solicitud de devolución está registrada y pendiente de revisión. Te confirmaremos por este canal.
[encargado, 3 horas después] edit: importe 90.0
[tools] reembolsar(pedido="P-20260917-0041", importe=90.0) -> {"ok": true, "reembolso": 7712}
Agente -> Cliente: Hemos aprobado un reembolso de 90 euros por la cafetera, con referencia 7712. El importe llegará a tu medio de pago en 3 a 5 días.

El modelo no sabe por qué el importe es 90 y no 120: la edición cambia los argumentos de la llamada, no le explica nada. Si la tienda quiere que el cliente reciba una explicación (jarra de repuesto sin coste, reembolso del resto), el encargado la escribe en la aplicación y la aplicación la añade al mensaje final. Meter esa explicación en el modelo exigiría una herramienta de notas con respond, y en este agente respond está fuera de allowed_decisions.

Lo que se mide

Métrica	Dónde	Qué dice
Interrupciones por cada cien conversaciones	`aprobaciones_pendientes` (histórico)	Si la política para demasiado o demasiado poco. Entre 10 y 25 es la zona de trabajo; por encima, el umbral de importe es bajo
Tiempo entre interrupción y decisión, p50 y p95	`creada` frente a la fila de `decisiones_encargado`	Lo que el cliente espera. El p95 dice si hay un turno sin encargado
Decisiones por tipo	`decisiones_encargado`	Muchos `edit` con el mismo patrón son una regla que falta en la política; muchos `reject` con el mismo motivo, una condición que falta en `when`
Reembolsos con `repetido = true`	`reembolsos`	Re-ejecuciones reales. Debe ser cercano a cero y distinto de cero alguna vez; si nunca pasa, la clave de idempotencia no se está probando
Operaciones con efecto sin fila en `decisiones_encargado` y con `when` verdadero	Cruce de `reembolsos` con `decisiones_encargado`	Debe ser cero. Es la auditoría de que el límite funciona
Tokens y coste por conversación, con y sin interrupción	Langfuse, metadato `caso=cliente`	Una conversación interrumpida tiene dos trazas o una con hueco, según se configure el callback; las dos formas valen si se agrupan por `thread_id`

La última fila de la tabla es la que se enseña al responsable. No dice cuánto ahorra el agente; dice que ningún euro ha salido sin la firma que la política exige. Es la condición para que el resto de métricas importen.

Checklist

La política es una función when que consulta la base de negocio, no el prompt.
allowed_decisions está decidido por herramienta y respond está fuera salvo en herramientas de notas.
description es una función que da al encargado el contexto que necesita, no el volcado por defecto.
La aplicación escribe aprobaciones_pendientes al recibir __interrupt__ y la borra al reanudar, en transacción con decisiones_encargado.
Las herramientas con efecto usan runtime.tool_call_id como clave de idempotencia con restricción única.
invoke lleva durability="sync" en los hilos con dinero.
La reanudación pasa context= cargado de la cola; no se confía en que el runtime lo recuerde.
El endpoint de reanudación exige rol de encargado y comprueba la tienda.
El prompt dice qué hacer con un rechazo y no promete plazos.
Hay una consulta de auditoría que cruza efectos con decisiones y da cero.

Trampas y cosas que no son lo que parecen

interrupt sin checkpointer no falla al interrumpir. Devuelve __interrupt__ con normalidad y el estado se pierde. El error, Cannot use Command(resume=...) without checkpointer, sale en la reanudación. Un entorno de pruebas sin persistencia da falsos positivos hasta que alguien intenta aprobar.

La herramienta no corre antes de la decisión, pero el modelo ya la ha pedido. Lo que se aprueba es una llamada con argumentos concretos. Si el encargado tarda un día y el stock ha cambiado, sustituir puede fallar al ejecutarse con los argumentos aprobados. La herramienta tiene que volver a comprobar, y el mensaje de error tiene que decir que la aprobación caducó.

El nodo que interrumpe se ejecuta dos veces. Con el middleware no importa; con un nodo propio, todo lo anterior a interrupt se repite. La interrupción va primero.

La herramienta en vuelo se repite si muere el pod. Las que terminaron no. La clave de idempotencia es el identificador de la llamada, y hay que probar la re-ejecución a propósito, matando el pod con una herramienta lenta, para ver la fila con repetido = true.

El rechazo llega en inglés. User rejected the tool call for ... with reason: es texto fijo del middleware. Sin instrucción en el prompt, el modelo puede contestar en inglés o reintentar.

No hay lista de hilos interrumpidos. Ni en el checkpointer ni en el estado. La cola es una tabla propia, y si la aplicación se cae entre el invoke y el INSERT, hay un hilo esperando que nadie ve. La escritura de la cola va lo más cerca posible del invoke, y una tarea periódica cruza aprobaciones_pendientes con los hilos que tienen next=('tools',) y una interrupción en get_state, recorriendo los hilos del día desde consultas_asistente.

El contexto no se recuerda en la reanudación. runtime.context es lo que se pase en esa llamada. Sin context=, el prompt dinámico ve None y falla al formatear.

Cierre

El límite de aprobación humana es una función, un middleware y una tabla. La función decide cuándo se pregunta; el middleware para el grafo antes de la herramienta y fija el contrato de la pregunta y de la respuesta; la tabla es la cola que el checkpointer no tiene. Alrededor, tres decisiones que no son de LangGraph pero que el código obliga a tomar: qué decisiones se permiten por herramienta, cómo se hace idempotente lo que tiene efecto, y quién puede reanudar.

El siguiente caso deja al cliente y mira al almacén. Un agente de compras tiene que revisar miles de referencias contra las incidencias de sus proveedores y proponer una reposición. Ahí el problema no es parar, es abrir en abanico sin tirar el servidor de inferencia, agregar sin condiciones de carrera y no pagar dos veces por la misma referencia.

Ver también

Fuentes

Human-in-the-loop en LangChain 1.x: https://docs.langchain.com/oss/python/langchain/human-in-the-loop
Interrupciones en LangGraph: https://docs.langchain.com/oss/python/langgraph/interrupts
Persistencia y durabilidad en LangGraph: https://docs.langchain.com/oss/python/langgraph/persistence
Código de langchain.agents.middleware.human_in_the_loop (langchain 1.4.1): InterruptOnConfig, HITLRequest, HITLResponse, ApproveDecision, EditDecision, RejectDecision, RespondDecision
Código de langgraph.types (langgraph 1.2.11): interrupt, Command, Interrupt
Código de langgraph.pregel.main (langgraph 1.2.11): firma de invoke, parámetro durability

Agente de empleado de tienda con LangGraph: procedimientos, stock y roturas con RAG, herramientas y middleware

Thu, 17 Sep 2026 01:30:00 +0200

TL;DR

El asistente de sala es un create_agent con tres herramientas, un prompt dinámico y cuatro middlewares. No hay grafo escrito a mano. Es el caso en el que el ciclo modelo-herramientas basta, y por eso es el primero de la serie.

Las herramientas devuelven datos, no prosa, y comprueban el rol dentro. Un dependiente que pide registrar una rotura recibe un error estructurado de la herramienta, no una negativa del modelo. El prompt le dice al modelo que no insista. El modelo no autoriza nada.

El RAG de procedimientos es una tabla en Postgres con pgvector, troceada por sección del manual, con una columna rol_minimo que entra en el WHERE de la consulta vectorial. El dependiente no recupera las secciones del encargado ni por casualidad. La herramienta devuelve el identificador de sección y el prompt obliga a citarlo.

Por defecto, una excepción en una herramienta mata la ejecución entera. Verificado en langchain 1.4.1: el manejador por defecto solo convierte en mensaje los errores de validación de argumentos; cualquier otra excepción se propaga y el turno acaba con traza de error. Hace falta ToolErrorMiddleware con un manejador propio o ToolRetryMiddleware. Y el mensaje que deja ToolRetryMiddleware al agotar reintentos termina en “Please try again”, lo que invita al modelo a volver a llamar a la herramienta rota.

Con el middleware completo, un turno con una llamada a herramienta deja 13 checkpoints en Postgres. Solo con los dos límites, 11. Sin middleware, 5. Los límites hacen falta; el coste en filas hay que contarlo.

Lo que se mide en la primera semana sale de Langfuse y de una tabla de movimientos: consultas por dependiente, latencia, tokens, llamadas a herramienta por turno, y consultas que acaban en el encargado. Con eso, el retorno se explica en minutos de encargado.

Estás aquí: el primer agente sobre el marco de la serie

Este es el caso 1 de la serie de agentes con LangGraph para retail. El marco fija el dominio, las tablas, el contexto de ejecución y el stack: vLLM detrás de LiteLLM, Postgres con pgvector, Langfuse. Aquí no se repite nada de eso; se construye el agente.

Lo que se resuelve es lo que un dependiente pregunta en sala con el cliente delante: si queda una referencia, dónde la hay, qué dice el manual sobre una devolución sin ticket, y cómo se registra un producto que se ha roto en el pasillo. Hoy esas preguntas van al encargado, que las contesta desde la trastienda entre otras cinco cosas. El retorno del agente está en ese tiempo.

La analogía: la carpeta de procedimientos y el teléfono del encargado

Toda tienda tiene una carpeta de procedimientos que nadie abre y un encargado al que todos llaman. La carpeta está bien escrita y desactualizada en tres secciones. El encargado está actualizado y no está.

El agente es la carpeta con el teléfono del encargado dentro. Responde con la carpeta cuando la pregunta está en la carpeta, mira el stock cuando la pregunta es de stock, y devuelve al dependiente al encargado cuando la respuesta exige una decisión que la carpeta reserva al encargado. Lo que no hace es tomar esa decisión, y eso se garantiza en el código, no en el prompt.

El problema de negocio en tres preguntas

Antes de escribir herramientas se listan las preguntas reales. Tres cubren la mayoría:

Stock. “¿Queda el SKU-0912?” y su continuación, “¿en qué tienda cercana lo hay?”. La respuesta es una consulta a la tabla stock filtrada por la tienda del empleado y una segunda por las demás tiendas.
Procedimiento. “¿Qué hago con una devolución sin ticket?”. La respuesta está en el manual, en una sección concreta, con condiciones. El dependiente quiere la sección y la condición, no una paráfrasis.
Rotura. “Se ha caído un lote de vasos, ¿cómo lo registro?”. La respuesta tiene dos partes: qué dice el procedimiento y, si el rol lo permite, el registro en el TPV.

La tercera es la que fija el límite del agente. Un dependiente puede preguntar cómo se registra. Solo un encargado puede registrar. El agente hace las dos cosas, pero la segunda comprueba quién pregunta.

Las herramientas

Tres principios que se mantienen en toda la serie, y que aquí aparecen por primera vez.

Devuelven datos estructurados. Un diccionario que LangChain serializa a JSON en el ToolMessage. Nunca prosa. El modelo redacta; la herramienta informa. Esto hace que el resultado sea comparable en las trazas y que el mismo dato valga para el caso 3, que no tiene modelo en medio para la mayoría de las referencias.

Leen el contexto de ejecución, no argumentos del modelo. La tienda y el rol viajan en runtime.context, un objeto tipado que se pasa en cada invoke. La herramienta lo recibe en un parámetro runtime: ToolRuntime[Contexto] que el modelo no ve en el esquema y no puede rellenar.

Comprueban el rol dentro. La herramienta con efecto devuelve un error estructurado si el rol no es el suyo. Es una línea y es la única barrera que cuenta.

from dataclasses import dataclass
from langchain.tools import tool, ToolRuntime

@dataclass
class Contexto:
 tienda: str
 empleado: str
 rol: str # "dependiente" | "encargado"

@tool
def stock_sku(sku: str, runtime: ToolRuntime[Contexto]) -> dict:
 """Unidades disponibles de un SKU en la tienda del empleado y en las tiendas cercanas."""
 propia = runtime.context.tienda
 with pool.connection() as conn:
 fila = conn.execute(
 "SELECT unidades - reservadas FROM stock WHERE tienda = %s AND sku = %s",
 (propia, sku),
 ).fetchone()
 cercanas = conn.execute(
 "SELECT tienda, unidades - reservadas FROM stock "
 "WHERE sku = %s AND tienda <> %s AND unidades - reservadas > 0 ORDER BY tienda",
 (sku, propia),
 ).fetchall()
 return {
 "sku": sku,
 "tienda": propia,
 "unidades": fila[0] if fila else 0,
 "cercanas": {t: u for t, u in cercanas},
 }

@tool
def registrar_rotura(sku: str, unidades: int, motivo: str, runtime: ToolRuntime[Contexto]) -> dict:
 """Registra una rotura en el TPV y descuenta stock. Solo encargados."""
 if runtime.context.rol != "encargado":
 return {"error": "permiso_denegado", "detalle": "Solo un encargado puede registrar roturas."}
 with pool.connection() as conn, conn.transaction():
 asiento = conn.execute(
 "INSERT INTO movimientos (tienda, sku, tipo, unidades, empleado, motivo, trace_id) "
 "VALUES (%s, %s, 'rotura', %s, %s, %s, %s) RETURNING id",
 (runtime.context.tienda, sku, -unidades, runtime.context.empleado, motivo,
 runtime.config["metadata"].get("langfuse_trace_id")),
 ).fetchone()[0]
 conn.execute(
 "UPDATE stock SET unidades = unidades - %s, actualizado = now() "
 "WHERE tienda = %s AND sku = %s",
 (unidades, runtime.context.tienda, sku),
 )
 return {"ok": True, "asiento": asiento}

Dos detalles del código. pool es un psycopg_pool.ConnectionPool de proceso, creado al arrancar, contra la base retail. Y registrar_rotura escribe el trace_id en la fila: es lo que después permite unir la traza de Langfuse con el movimiento de negocio. En este caso el identificador entra por metadata en la configuración de la llamada; en el artículo 5 lo pone la capa HTTP.

Un dependiente que le pide al agente registrar la rotura obtiene esto en el ToolMessage: {"error": "permiso_denegado", "detalle": "Solo un encargado puede registrar roturas."}. El modelo lo lee y responde que tiene que avisar al encargado. Si el modelo intentara otra cosa, la herramienta devolvería lo mismo. Si un dependiente escribiera en el prompt que es encargado, el contexto seguiría diciendo que no, porque el contexto lo pone la aplicación a partir de la sesión, no el usuario.

El RAG de procedimientos

La carpeta de procedimientos es la tercera herramienta, y es la única con embeddings.

La tabla

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE procedimientos (
 id text PRIMARY KEY, -- "PROC-7.2"
 seccion text NOT NULL, -- "Roturas en sala"
 texto text NOT NULL,
 rol_minimo smallint NOT NULL DEFAULT 0, -- 0 dependiente, 1 encargado
 vigente boolean NOT NULL DEFAULT true,
 embedding vector(1024) NOT NULL
);

CREATE INDEX ON procedimientos USING hnsw (embedding vector_cosine_ops);

Cada fila es una sección del manual, no un trozo de tamaño fijo. Los manuales de tienda ya vienen numerados por sección, y la sección es la unidad que el dependiente reconoce y que el encargado corrige. Un trozo de 500 tokens que empieza a media frase no tiene identificador y no se puede citar. Las secciones largas se parten por subsección, con el identificador del padre como prefijo.

rol_minimo es la columna que hace que el filtro sea de la base de datos y no del prompt. vigente permite retirar una sección sin borrarla, para que las trazas antiguas sigan resolviendo el identificador.

Los embeddings

Se calculan con un modelo de embeddings servido en el mismo vLLM, con --task embed, y expuesto en LiteLLM como cualquier otro modelo. Desde LangChain:

from langchain_openai import OpenAIEmbeddings

emb = OpenAIEmbeddings(
 model="bge-m3",
 base_url="http://litellm.agentes.svc:4000/v1",
 api_key=os.environ["LITELLM_KEY_TIENDA"],
 check_embedding_ctx_length=False,
)

check_embedding_ctx_length=False importa. Con el valor por defecto, OpenAIEmbeddings tokeniza el texto con tiktoken para partirlo según el límite de los modelos de OpenAI, y el resultado se envía como lista de identificadores de token que vLLM no entiende. Con False, envía el texto tal cual.

La consulta

@tool
def procedimiento(consulta: str, runtime: ToolRuntime[Contexto]) -> list[dict]:
 """Secciones del manual de procedimientos relevantes para la consulta (tres como máximo)."""
 rol = 1 if runtime.context.rol == "encargado" else 0
 vector = emb.embed_query(consulta)
 with pool.connection() as conn:
 filas = conn.execute(
 "SELECT id, seccion, texto, 1 - (embedding <=> %s::vector) AS similitud "
 "FROM procedimientos "
 "WHERE vigente AND rol_minimo <= %s "
 "ORDER BY embedding <=> %s::vector LIMIT 3",
 (vector, rol, vector),
 ).fetchall()
 return [
 {"id": i, "seccion": s, "texto": t, "similitud": round(sim, 3)}
 for i, s, t, sim in filas
 if sim >= 0.45
 ]

El filtro por rol va en el WHERE, antes del ORDER BY. Con pgvector 0.8 y un índice HNSW, un filtro restrictivo puede dejar menos de tres resultados tras el recorrido del índice; los recorridos iterativos de esa versión lo corrigen, y en una tabla de unos cientos de secciones el índice ni siquiera es necesario. El umbral de similitud se fija mirando las trazas de la primera semana; 0,45 es un punto de partida para un modelo multilingüe, no una cifra medida.

Tres secciones como máximo. El prompt del agente pide respuestas de tres frases y una cita; con más contexto el modelo tiende a resumir varias secciones en una respuesta que no cita ninguna. Si la pregunta abarca dos procedimientos, el modelo llama a la herramienta dos veces con dos consultas, y eso se ve en la traza.

El prompt dinámico

El sistema se construye en cada llamada al modelo a partir del contexto. No hay un prompt fijo con huecos rellenados a mano en invoke.

from langchain.agents.middleware import dynamic_prompt, ModelRequest

@dynamic_prompt
def prompt_tienda(request: ModelRequest) -> str:
 ctx = request.runtime.context
 return (
 f"Eres el asistente de sala de la tienda {ctx.tienda}. "
 f"Hablas con el empleado {ctx.empleado}, con rol {ctx.rol}. "
 "Responde solo con datos devueltos por las herramientas. "
 "Si una herramienta devuelve un error, explícalo con sus palabras y no lo intentes de otra forma. "
 "Cuando uses el manual, cita el identificador de sección entre paréntesis. "
 "Si no hay sección relevante, dilo y remite al encargado. "
 "Tres frases como máximo."
 )

Lo que el prompt no hace: no lista permisos, no dice qué puede hacer cada rol, no describe las herramientas. Los permisos están en las herramientas. Las descripciones de las herramientas están en sus docstrings, y son lo que el modelo ve en el esquema. Un prompt que repite lo que las herramientas ya dicen es contexto gastado en cada llamada y una segunda fuente de verdad que se desactualiza.

El agente y su middleware

from langchain.agents import create_agent
from langchain.agents.middleware import (
 ToolCallLimitMiddleware, ModelCallLimitMiddleware,
 ToolErrorMiddleware, SummarizationMiddleware,
)

def error_herramienta(exc: Exception, request) -> str:
 return json.dumps({
 "error": type(exc).__name__,
 "detalle": str(exc)[:200],
 "herramienta": request.tool_call["name"],
 })

def construir(modelo, checkpointer):
 return create_agent(
 modelo,
 tools=[stock_sku, procedimiento, registrar_rotura],
 middleware=[
 prompt_tienda,
 ToolErrorMiddleware(on_error=error_herramienta),
 ToolCallLimitMiddleware(run_limit=6, exit_behavior="end"),
 ModelCallLimitMiddleware(run_limit=8, exit_behavior="end"),
 SummarizationMiddleware(modelo, trigger=("fraction", 0.75), keep=("fraction", 0.25)),
 ],
 context_schema=Contexto,
 checkpointer=checkpointer,
 )

Cada middleware está por una razón que se ha visto en el código, no por costumbre.

ToolErrorMiddleware. Sin él, una excepción en stock_sku porque la base de datos no responde no llega al modelo. Se propaga por el nodo tools, sale de invoke y el turno acaba con una traza de error y sin respuesta. Verificado con una herramienta que lanza RuntimeError: el manejador por defecto del nodo de herramientas de LangGraph 1.2.11 devuelve mensaje solo para ToolInvocationError, que es el error de validación de argumentos, y re-lanza el resto. Con el manejador de arriba, el modelo recibe {"error": "RuntimeError", "detalle": "...", "herramienta": "stock_sku"} en un ToolMessage con status="error" y responde que no puede consultar el stock ahora. El manejador recibe la excepción y la petición, en ese orden; un manejador de un solo argumento falla con TypeError en la primera excepción real.

ToolCallLimitMiddleware(run_limit=6). Seis llamadas a herramienta por ejecución. Una consulta de sala normal usa una o dos. Seis es el techo que separa un modelo que está afinando la consulta de uno que está dando vueltas. exit_behavior="end" termina la ejecución sin excepción, con la última respuesta del modelo. El límite por hilo, thread_limit, se deja sin fijar porque el hilo de un dependiente dura un turno de trabajo entero.

ModelCallLimitMiddleware(run_limit=8). Ocho llamadas al modelo por ejecución. Con seis herramientas como máximo, el modelo se llama siete veces en el peor caso; la octava es margen. Este límite es el que cuenta para el coste: cada llamada al modelo lleva el historial entero.

SummarizationMiddleware. Con disparador explícito por fracción y perfil en el modelo; el marco de la serie documenta que sin disparador el middleware no resume nunca. Un turno de trabajo de ocho horas con cuarenta consultas cabe en 32.768 tokens sin resumir, así que en la práctica no salta. Está para el día en que un dependiente hace ciento veinte.

ToolRetryMiddleware no está. Se probó y se quitó. Con el valor por defecto de dos reintentos y on_failure="continue", el mensaje que deja al agotar los reintentos es Tool 'stock_sku' failed after 3 attempts with RuntimeError: ... Please try again. Ese “Please try again” lo lee el modelo, y con una base de datos caída el modelo vuelve a llamar a la herramienta, que vuelve a fallar tres veces, hasta que ToolCallLimitMiddleware corta. Los reintentos contra Postgres se hacen en el pool de conexiones, con tiempo de espera corto, y el agente recibe un error una sola vez.

El grafo que sale

Compilado con esos middlewares, agente.get_graph().nodes devuelve ocho nodos: __start__, model, tools, ToolCallLimitMiddleware.after_model, ModelCallLimitMiddleware.before_model, ModelCallLimitMiddleware.after_model, SummarizationMiddleware.before_model y __end__. prompt_tienda y ToolErrorMiddleware no añaden nodos: envuelven la llamada al modelo y a la herramienta. Los dos límites y el resumen sí son nodos, porque se ejecutan como paso propio antes o después del modelo, y los límites además tienen que poder desviar el flujo a __end__.

Un turno con una llamada a herramienta recorre __start__, los dos before_model, model, los dos after_model, tools, y otra vez los dos before_model, model y los dos after_model. Trece supersteps, trece checkpoints. Solo con los dos límites, once. Sin middleware, cinco. Medido con un modelo falso que devuelve una llamada a stock_sku y después una respuesta, sobre InMemorySaver, contando con checkpointer.list(config). Un turno en el que el modelo pide dos herramientas a la vez deja las mismas trece filas: las dos corren en el mismo superstep del nodo tools.

Persistencia

El checkpointer es PostgresSaver sobre la base agentes, distinta de retail. Las tablas de checkpoint crecen por superstep y se borran por hilo; las de negocio crecen por movimiento y no se borran. No se mezclan.

from psycopg_pool import ConnectionPool
from langgraph.checkpoint.postgres import PostgresSaver

pool_agentes = ConnectionPool(os.environ["PG_AGENTES"], min_size=2, max_size=10,
 kwargs={"autocommit": True, "prepare_threshold": 0})
checkpointer = PostgresSaver(pool_agentes)
agente = construir(modelo, checkpointer)

setup() no se llama aquí. Crea cuatro tablas y tres índices, y los índices van con CREATE INDEX CONCURRENTLY, que no puede ejecutarse dentro de una transacción ni a través de un pooler en modo transacción. Se llama una vez, desde un Job de Kubernetes con un rol que tenga permiso de DDL, antes del primer despliegue. Los pods del agente conectan con un rol sin DDL. Si se olvida, la primera invocación falla con una excepción de tabla inexistente, que es el fallo bueno: ruidoso y en el arranque.

El thread_id lo construye la aplicación: f"tienda:{ctx.tienda}:{ctx.empleado}:{turno}", con turno la fecha y el turno de trabajo. Un hilo por dependiente y turno. El dependiente no elige el identificador ni lo ve. Al cerrar el turno, un proceso aparte llama a checkpointer.delete_thread(thread_id) para los hilos de más de siete días. Es la única operación de borrado que existe en el checkpointer de Postgres 3.1.2, y se documenta en el marco de la serie por qué no hay otra.

Una consulta desde la aplicación:

config = {
 "configurable": {"thread_id": thread_id},
 "metadata": {"caso": "tienda", "tienda": ctx.tienda, "rol": ctx.rol},
 "callbacks": [langfuse_handler],
}
resultado = agente.invoke(
 {"messages": [{"role": "user", "content": pregunta}]},
 context=ctx,
 config=config,
)
respuesta = resultado["messages"][-1].content

Y la misma en streaming, que es lo que la aplicación de sala usa para pintar la respuesta según llega:

for chunk, meta in agente.stream(
 {"messages": [{"role": "user", "content": pregunta}]},
 context=ctx, config=config, stream_mode="messages",
):
 if meta["langgraph_node"] == "model" and chunk.content:
 emitir(chunk.content)

stream_mode="messages" entrega los trozos de cada mensaje con metadatos del nodo que los produce. Filtrar por langgraph_node == "model" deja fuera los ToolMessage, que no se muestran al dependiente.

Una conversación completa

Una conversación de sala de tres turnos, en el mismo hilo, reproducida con las herramientas reales sobre el catálogo de prueba. Las llamadas, los argumentos y los resultados entre corchetes son los que devuelve el código. Las frases del agente están guionizadas con el modelo falso de la serie para fijar el comportamiento esperado; la redacción exacta la pone el modelo que se sirva.

Dependiente: ¿Queda el SKU-0912?
[tools] stock_sku(sku="SKU-0912") -> {"sku": "SKU-0912", "tienda": "T001", "unidades": 0, "cercanas": {"T002": 14}}
Agente: En T001 no queda. T002 tiene 14 unidades disponibles.
Dependiente: Un cliente quiere devolver uno sin ticket, ¿qué hago?
[tools] procedimiento(consulta="devolución sin ticket") -> [{"id": "PROC-4.3", "seccion": "Devoluciones sin justificante", ...}]
Agente: Se admite solo como vale, con DNI y en los 30 días desde la fecha de compra que figure en la etiqueta (PROC-4.3). Si no hay etiqueta, se remite al encargado.
Dependiente: Se me ha caído una caja de seis del SKU-4471, regístralo como rotura.
[tools] procedimiento(consulta="rotura en sala") -> [{"id": "PROC-7.2", ...}]
[tools] registrar_rotura(sku="SKU-4471", unidades=6, motivo="caída en sala") -> {"error": "permiso_denegado", "detalle": "Solo un encargado puede registrar roturas."}
Agente: Retira el producto y fotografíalo (PROC-7.2). El registro en el TPV lo tiene que hacer un encargado; avísale con la foto.

En el tercer turno el modelo pidió dos herramientas en la misma vuelta y la segunda devolvió el error de permiso. La respuesta lo integra sin inventar una alternativa. El mismo tercer turno con rol="encargado" en el contexto devuelve {"ok": true, "asiento": ...} con el identificador del movimiento, y la respuesta lo cita.

Las llamadas, los argumentos y los resultados de arriba son los que aparecen en la traza de Langfuse. La aplicación no los muestra; el encargado que revisa la traza al final de la semana sí los ve.

Lo que se mide en la primera semana

Dos fuentes. Langfuse dice qué hizo el agente; la tabla movimientos y un registro de consultas dicen qué pasó en la tienda.

Langfuse, agrupando por los metadatos caso, tienda y rol:

Métrica	Dónde	Qué dice
Consultas por dependiente y día	Trazas por `thread_id`	Si lo usan. Por debajo de cinco al día, no lo usan
Latencia p50 y p95 por consulta	Duración de la traza	Con vLLM saturado, el p95 se dispara antes que el p50
Tokens de entrada y salida, coste	Generaciones de la traza	La entrada crece con el hilo; el resumen la acota
Llamadas a herramienta por turno	Spans de `tools`	Mediana 1, p95 2. Más, el prompt o las docstrings están mal
Cortes por límite	Trazas que acaban en `after_model` de un límite	Debe ser cero. Cada corte es una conversación fallida
Errores de herramienta	`ToolMessage` con `status="error"`	Separar `permiso_denegado` del resto: el primero es correcto, el resto es infra

Postgres, con dos consultas:

-- Consultas que acabaron en el encargado
SELECT tienda, count(*) FILTER (WHERE escalada) AS al_encargado, count(*) AS total
FROM consultas_asistente WHERE ts >= now() - interval '7 days'
GROUP BY tienda;

-- Roturas registradas a través del agente y tiempo desde la consulta
SELECT m.tienda, count(*) AS roturas,
 percentile_cont(0.5) WITHIN GROUP (ORDER BY m.ts - c.ts) AS mediana_hasta_registro
FROM movimientos m JOIN consultas_asistente c ON c.trace_id = m.trace_id
WHERE m.tipo = 'rotura' AND m.ts >= now() - interval '7 days'
GROUP BY m.tienda;

consultas_asistente la escribe la aplicación en cada turno con el thread_id, el trace_id y un campo escalada que se marca cuando la respuesta remite al encargado. Es la tabla que convierte trazas en minutos.

El retorno se explica así: cada consulta resuelta sin escalar son entre dos y cinco minutos de encargado que no se interrumpen, según la tienda. Con cuarenta consultas al día por tienda y una tasa de escalado del 20 por ciento, son treinta y dos consultas resueltas y entre una y dos horas y media de encargado al día. Las cifras de consultas y de escalado son las que hay que medir; los minutos por consulta los pone cada tienda. Lo que este artículo no da es una cifra de latencia o de coste de su despliegue: dependen del modelo, de la GPU y de la carga, y se miden en el suyo con la tabla de arriba.

Checklist

Las tres herramientas devuelven diccionarios y nunca prosa.
registrar_rotura comprueba el rol dentro y escribe el trace_id en la fila.
La consulta de procedimiento lleva rol_minimo y vigente en el WHERE.
OpenAIEmbeddings va con check_embedding_ctx_length=False.
ToolErrorMiddleware tiene un manejador de dos argumentos que devuelve JSON.
ToolRetryMiddleware no está; los reintentos viven en el pool de Postgres.
Los dos límites llevan exit_behavior="end" y se cuenta cuántas trazas acaban en ellos.
SummarizationMiddleware tiene trigger y el modelo tiene profile.
setup() del checkpointer corre en un Job con DDL, no en los pods.
El thread_id lo construye la aplicación y hay un proceso que borra hilos por antigüedad.
La aplicación escribe consultas_asistente con escalada y trace_id.

Trampas y cosas que no son lo que parecen

Una excepción en una herramienta es una excepción en invoke. No hay manejo por defecto salvo para errores de validación de argumentos. Sin ToolErrorMiddleware, una base de datos caída se ve como un agente caído.

El manejador de ToolErrorMiddleware recibe dos argumentos. Excepción y petición. Con uno, TypeError en la primera excepción real, que es cuando menos se quiere.

ToolRetryMiddleware le pide al modelo que reintente. El mensaje al agotar los intentos termina en “Please try again”. Con una herramienta rota, eso es un bucle hasta el límite de llamadas.

Los límites y el resumen son nodos, y los nodos son checkpoints. Trece filas por turno con una herramienta y el middleware completo, contra cinco sin middleware. El middleware que envuelve (dynamic_prompt, ToolErrorMiddleware) no añade filas; el que se ejecuta como paso propio sí.

OpenAIEmbeddings envía tokens, no texto, por defecto. Con un modelo de embeddings en vLLM eso es un error 400 o, peor, un embedding de un texto que no es el suyo. check_embedding_ctx_length=False.

El filtro por rol en el prompt no es un filtro. Está en la consulta SQL. Si se quita de ahí y se deja en el prompt, un dependiente recupera las secciones del encargado en cuanto la pregunta se parece lo bastante.

setup() desde el pod falla de dos formas. Sin DDL, error de permisos. A través de un pooler en modo transacción, el CREATE INDEX CONCURRENTLY falla. Job aparte.

Cierre

El asistente de sala es el agente más pequeño de la serie y el que más enseña sobre dónde poner cada cosa. Los permisos, en las herramientas. El filtro de documentos, en la consulta. El contexto, fuera del estado. Los errores, convertidos en datos antes de que lleguen al modelo. Y los límites, contados en filas de checkpoint antes de dimensionar la base.

El siguiente caso rompe el ciclo. Un cliente pide una devolución, el agente prepara la resolución y, según el importe y el historial, para y espera a un encargado que puede estar en otra tienda y contestar mañana. Eso es interrupt(), un checkpointer que sobrevive al pod, y un nodo que se ejecuta dos veces sin escribir dos veces.

Ver también

Fuentes

Referencia de create_agent en LangChain 1.x: https://docs.langchain.com/oss/python/langchain/agents
Middleware de LangChain 1.x (ToolErrorMiddleware, ToolRetryMiddleware, límites, resumen): https://docs.langchain.com/oss/python/langchain/middleware
Persistencia y checkpointers en LangGraph: https://docs.langchain.com/oss/python/langgraph/persistence
Código de langgraph.prebuilt.tool_node (langgraph-prebuilt 1.1.0), función _default_handle_tool_errors
Código de langchain.agents.middleware.tool_error y tool_retry (langchain 1.4.1)
Código de langgraph.checkpoint.postgres.base (3.1.2), lista MIGRATIONS
pgvector, indexación HNSW y filtrado: https://github.com/pgvector/pgvector
vLLM, modelos de embeddings (--task embed): https://docs.vllm.ai/en/latest/models/pooling_models.html

Agentes con LangGraph para retail: por qué un grafo, qué primitivas hacen falta y el stack que comparten los cuatro casos

Thu, 17 Sep 2026 01:00:00 +0200

TL;DR

Un agente de LangChain construido con create_agent ya es un grafo de LangGraph. Compilado sin middleware tiene cuatro nodos: entrada, modelo, herramientas y salida. Cada middleware que se añade mete nodos nuevos en ese grafo, y el checkpointer guarda una fila por paso del grafo, no por turno de conversación. Con dos middlewares de límite, un turno con una sola llamada a herramienta pasa de 5 checkpoints a 11. Esto se mide antes de dimensionar la base de datos, no después.

El bucle de herramientas resuelve el primer caso de la serie y se queda corto en los otros tres. No sabe parar a pedir permiso y retomar desde ahí días después, no sabe abrir en abanico miles de elementos y agregar el resultado, y no sabe iterar contra un evaluador con un contador de intentos. Esas tres cosas son primitivas del grafo, no del bucle.

La serie usa un único dominio de retail, con un catálogo ficticio y unas tablas fijas, para que los cuatro agentes compartan datos, contexto de ejecución y métricas. Cada artículo enseña una primitiva sobre ese dominio: el ciclo modelo-herramientas con middleware, la interrupción con reanudación, el map-reduce con Send y reductores, y los subgrafos con bucle acotado.

El stack es el mismo en los cuatro casos y corre en un cluster propio: un modelo abierto servido en vLLM, LiteLLM delante con una clave virtual por agente, Postgres con pgvector para el checkpointer, el almacén y el RAG, y Langfuse para las trazas. Ninguna pieza exige licencia comercial ni conexión con nadie. El servidor HTTP de LangGraph se queda fuera de la serie a propósito.

Hay dos trampas de configuración que aparecen en el minuto uno y que no avisan. Un modelo servido en vLLM con nombre no reconocido por LangChain no tiene perfil, así que la ventana de contexto es desconocida para el agente. Y el middleware de resumen, construido sin disparador, no resume nunca. Ninguna de las dos lanza error.

Casi todo lo que hay publicado sobre agentes con LangGraph sigue usando create_react_agent, que está deprecado desde la 1.0. Esta serie se escribe contra langgraph 1.2.11 y langchain 1.4.1, y cada afirmación sobre el código se ha comprobado en el paquete instalado, no en la documentación.

Estás aquí: después de las licencias y del gateway, el agente

El blog ya ha cubierto lo que hay debajo. La elección del gateway de inferencia, cómo se opera LiteLLM con Langfuse, cómo se dimensiona ese gateway cuando lo que hay detrás son agentes y no personas, y, en el artículo que abre la vertical agéntica, qué es libre y qué no en deepagents y qué hay que construir para servirlo sin depender de nadie. Ese último artículo deja el motor del grafo como pieza MIT que corre en cualquier sitio y el servidor gestionado como pieza con licencia.

Esta serie baja un nivel. Ya no pregunta qué armazón elegir. Pregunta cómo se construye un agente concreto sobre ese motor, con un problema de negocio delante y con números que un responsable de tienda entienda. Son seis artículos:

Este: el marco, las primitivas, el dominio compartido y el stack.
Empleado de tienda: asistente de sala sobre procedimientos, stock y roturas. Ciclo modelo-herramientas, RAG con pgvector, middleware. Es el que se despliega en una semana y el que tiene el retorno más fácil de medir.
Cliente: pedidos, devoluciones y sustituciones. Aquí se pone el límite de la aprobación humana, con interrupt() y reanudación sobre el checkpointer.
Cadena de suministro: análisis de incidencias con proveedores y planificación de reposición. Plan-and-execute con map-reduce sobre miles de referencias.
Datos de producto: enriquecimiento y control de calidad de fichas. Generador y evaluador en un bucle de reflexión acotado.
Cierre operativo: los cuatro agentes servidos en el mismo cluster sin el servidor de LangGraph, con autorización por hilo, retención y sondas.

Los artículos 1 a 4 se leen sueltos. Este marco existe para no repetir en cada uno la parte de dominio, stack y método.

Después de la serie hay una tanda de dos sobre pruebas y evaluación: tests de grafo con un modelo guionizado y evaluación con datasets de Langfuse. Y una tercera sobre memoria y enrutado, que empieza por la memoria entre hilos con PostgresStore.

La analogía: el dependiente con iniciativa y el manual de turno

Un bucle de herramientas es un dependiente con iniciativa y un teléfono. Le llega una pregunta, decide a quién llamar, llama, escucha, vuelve a decidir. Para consultas de sala funciona bien y es lo que se quiere: rapidez y criterio dentro de un margen estrecho.

Un grafo es el manual de turno. Dice en qué orden se hacen las cosas, qué pasos se pueden hacer a la vez, dónde hay que parar a esperar la firma del encargado, y qué se hace si el proveedor no contesta. El dependiente sigue dentro, decidiendo en cada casilla, pero las casillas y las flechas las ha fijado alguien antes y no cambian por mucha iniciativa que tenga.

LangGraph es el manual, y create_agent es un manual de una sola casilla con el dependiente dentro. Los tres casos que vienen después del primero necesitan casillas nuevas.

Por qué un grafo y no un bucle

Antes de decidirlo hay que ver qué es exactamente el bucle en la versión actual. En langchain 1.4.1, create_agent devuelve un CompiledStateGraph de LangGraph. Compilado con un modelo y tres herramientas, sin middleware, tiene esta estructura:

__start__ -> model -> (condicional) -> tools -> model
-> __end__

Cuatro nodos. El estado por defecto es AgentState, con un canal messages que acumula mensajes con el reductor add_messages, un canal privado jump_to para que el middleware desvíe el flujo, y structured_response para la salida tipada. Los middlewares se enganchan como nodos o como envoltorios. ModelCallLimitMiddleware añade un nodo antes del modelo y otro después; ToolCallLimitMiddleware añade uno después. Con esos dos, el grafo pasa a siete nodos, y el mismo turno con una llamada a herramienta deja 11 checkpoints en la base de datos en vez de 5. El checkpointer escribe una fila por superstep, y cada nodo de middleware es un superstep más. Es un coste pequeño por turno y grande por millón de turnos; se vuelve sobre él en el artículo 5.

Lo que el bucle da, y da bien:

Un ciclo modelo-herramientas con parada por defecto. El modelo llama a herramientas hasta que devuelve una respuesta sin llamadas. Con ToolCallLimitMiddleware y ModelCallLimitMiddleware se acota el número de vueltas por ejecución y por hilo, y exit_behavior="end" corta sin lanzar excepción.
Un prompt que depende del contexto de ejecución. Con @dynamic_prompt el sistema se construye en cada llamada al modelo a partir de runtime.context, que es un objeto tipado que se pasa en invoke. Tienda, empleado y rol viajan ahí, no en el prompt ni en el estado.
Herramientas con acceso al contexto. Una herramienta declarada con un parámetro runtime: ToolRuntime[Contexto] recibe el mismo objeto. El modelo no ve ese parámetro y no puede inventárselo. Es la forma de que la consulta de stock sepa en qué tienda está sin que el modelo lo diga.
Persistencia por hilo. Cualquier checkpointer que se le pase guarda el estado completo después de cada superstep, y el hilo se identifica por thread_id en la configuración.

Lo que el bucle no da:

Parar y retomar con intervención humana. Existe interrupt(), y existe HumanInTheLoopMiddleware que la usa por debajo para pedir aprobación antes de una herramienta. Pero el diseño del punto de aprobación, qué se muestra al humano, qué decisiones se le permiten, qué pasa si edita los argumentos y cómo se reanuda con Command(resume=...), es diseño de grafo. En el bucle es una casilla más entre el modelo y la herramienta. Cuando la aprobación depende del importe, del historial del cliente y de si el pedido ya salió del almacén, hace falta un nodo que decida si se pregunta o no, y eso ya no es el bucle.
Abrir en abanico y agregar. Analizar dos mil referencias con un modelo no es dos mil llamadas en secuencia dentro de un bucle. Es un nodo de planificación, un Send por elemento hacia un nodo trabajador, un reductor en el estado que acumule resultados sin pisarse, y un nodo diferido que espere a que todos acaben. add_node(..., defer=True) y cache_policy son parámetros de StateGraph.add_node, no del agente.
Iterar contra un evaluador con contador. Generar una ficha de producto, evaluarla contra unos criterios, corregir, volver a evaluar, y parar a la tercera. Es un ciclo con dos nodos y una arista condicional que lee un contador del estado. En el bucle se puede simular con una herramienta que evalúa, pero el modelo decide cuándo llamarla y cuándo dejar de llamarla, y esa decisión es justo la que no se le quiere dar.

La regla de la serie: se usa create_agent mientras el problema quepa en un ciclo modelo-herramientas con middleware, y se baja a StateGraph cuando hace falta una casilla que el modelo no debe controlar. El primer caso se queda en el agente. Los otros tres bajan al grafo, y en los tres el agente del caso 1 reaparece como subgrafo.

Las cuatro primitivas, una por caso

Cada artículo de la serie enseña una primitiva del grafo sobre un problema de negocio. Aquí va la lista con la forma exacta que tiene en la 1.2.11, para que los artículos posteriores no tengan que presentarla desde cero.

Caso 1: ciclo modelo-herramientas y middleware

from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware, dynamic_prompt, ModelRequest

@dynamic_prompt
def prompt(request: ModelRequest) -> str:
 ctx = request.runtime.context
 return f"Eres el asistente de la tienda {ctx.tienda}. Hablas con {ctx.empleado}."

agente = create_agent(
 modelo,
 tools=[stock_sku, procedimiento],
 middleware=[prompt, ToolCallLimitMiddleware(run_limit=6, exit_behavior="end")],
 context_schema=Contexto,
 checkpointer=checkpointer,
)

La firma completa de create_agent admite además state_schema, store, response_format, interrupt_before e interrupt_after, cache y transformers. Los que importan para esta serie son middleware, context_schema, checkpointer y store.

Caso 2: interrupción y reanudación

from langgraph.types import interrupt, Command

def aprobar_devolucion(state):
 decision = interrupt({
 "pedido": state["pedido_id"],
 "importe": state["importe"],
 "motivo": state["motivo"],
 })
 if decision["aprobada"]:
 return {"estado": "aprobada"}
 return {"estado": "rechazada", "comentario": decision.get("comentario")}

# Días después, desde otro proceso:
grafo.invoke(Command(resume={"aprobada": True}), config={"configurable": {"thread_id": hilo}})

interrupt(value) es una función de un solo argumento. Cuando se ejecuta, el grafo guarda el estado en el checkpointer y devuelve el control con el valor en __interrupt__. La reanudación entra con Command(resume=...) y el nodo se ejecuta entero otra vez desde el principio; la llamada a interrupt devuelve entonces el valor reanudado. Dos consecuencias que condicionan el diseño del caso 2: la interrupción va lo antes posible dentro del nodo, y nada con efecto externo se pone antes de ella en ese mismo nodo. Sin checkpointer, interrupt lanza ValueError.

Caso 3: abanico con `Send` y reductores

import operator
from typing import Annotated, TypedDict
from langgraph.types import Send
from langgraph.graph import StateGraph, START, END

class Estado(TypedDict):
 skus: list[str]
 analisis: Annotated[list[dict], operator.add]

def planificar(state):
 return [Send("analizar_sku", {"sku": s}) for s in state["skus"]]

grafo = StateGraph(Estado)
grafo.add_node("cargar", cargar)
grafo.add_node("analizar_sku", analizar_sku)
grafo.add_node("consolidar", consolidar, defer=True)
grafo.add_edge(START, "cargar")
grafo.add_conditional_edges("cargar", planificar, ["analizar_sku"])
grafo.add_edge("analizar_sku", "consolidar")
grafo.add_edge("consolidar", END)

Send(nodo, estado) lanza una instancia del nodo trabajador con un estado propio, y todas las instancias corren en el mismo superstep. El reductor operator.add sobre analisis es lo que permite que dos mil trabajadores escriban en la misma lista sin condiciones de carrera: LangGraph aplica las escrituras al final del superstep, en orden determinista. defer=True en consolidar lo retrasa hasta que no quede ningún camino pendiente hacia él. El caso 3 añade cache_policy por nodo para no reanalizar la misma referencia dos veces en la misma jornada.

Caso 4: subgrafos y bucle acotado

def decidir(state) -> str:
 if state["veredicto"] == "aprobada" or state["intentos"] >= 3:
 return "publicar"
 return "generar"

grafo.add_node("generar", generar)
grafo.add_node("evaluar", evaluar)
grafo.add_node("publicar", publicar)
grafo.add_edge("generar", "evaluar")
grafo.add_conditional_edges("evaluar", decidir, {"generar": "generar", "publicar": "publicar"})

El contador intentos vive en el estado con un reductor que suma, y la arista condicional lo lee. El modelo no ve ese contador ni decide cuándo parar. generar y evaluar pueden ser cada uno un agente de create_agent compilado y añadido como nodo; un grafo compilado es un nodo válido y comparte con el padre las claves de estado que tengan el mismo nombre.

El dominio compartido

Cuatro agentes sobre cuatro catálogos distintos no serían una serie. Se fija uno, ficticio, con el tamaño justo para que el caso 3 escale.

Tres tiendas, T001 a T003, un almacén central A001 y un catálogo generado de 2.000 referencias en el repositorio de ejemplo, con un generador para subir a 30.000 cuando el caso 3 lo necesite. Las tablas, en Postgres:

Tabla	Claves	Quién la usa
`productos`	`sku`, `nombre`, `familia`, `proveedor_id`, `pvp`	Todos
`fichas`	`sku`, `titulo`, `descripcion`, `atributos` (jsonb), `estado`	Caso 4
`stock`	`(tienda, sku)`, `unidades`, `reservadas`, `actualizado`	Casos 1, 2, 3
`movimientos`	`id`, `tienda`, `sku`, `tipo` (venta, rotura, merma, recepción), `unidades`, `empleado`, `ts`	Casos 1, 3
`pedidos` / `lineas_pedido`	`pedido_id`, `cliente_id`, `estado`, `canal`; `sku`, `unidades`, `precio`	Caso 2
`devoluciones`	`id`, `pedido_id`, `motivo`, `importe`, `estado`, `aprobada_por`	Caso 2
`proveedores` / `incidencias`	`proveedor_id`, `plazo_dias`, `sla`; `id`, `proveedor_id`, `sku`, `tipo`, `abierta_ts`, `cerrada_ts`	Caso 3
`procedimientos`	`id`, `seccion`, `texto`, `rol_minimo`, `embedding` (vector)	Caso 1

El contexto de ejecución también es común. Es una dataclass que se pasa en cada invoke y que las herramientas y el prompt leen desde runtime.context:

@dataclass
class Contexto:
 tienda: str # "T001"
 empleado: str # identificador, no nombre
 rol: str # "dependiente" | "encargado" | "compras" | "catalogo"

Tres decisiones sobre este contexto que se mantienen en toda la serie. La primera: el rol se comprueba dentro de la herramienta, no en el prompt. Una herramienta que solo puede usar un encargado devuelve un error estructurado si el rol no es el suyo, y el prompt le dice al modelo que no insista. Un modelo no es una capa de autorización. La segunda: el contexto no se guarda en el estado ni en el checkpoint. Viaja en cada llamada, así que un hilo reanudado por otra persona lleva el contexto de esa persona. La tercera: el thread_id lo construye la aplicación a partir del empleado y de un identificador de sesión, nunca lo elige el cliente. El checkpointer no comprueba propietarios; esa comprobación es de la capa HTTP que se escribe en el artículo 5.

El stack común

Todo corre en un cluster de Kubernetes genérico. No hay ninguna pieza que exija salir a Internet ni clave de licencia.

Pieza	Papel	Nota
vLLM	Sirve el modelo abierto	Un modelo de clase 30B en FP8 con ventana de 32.768 tokens por defecto para los casos 1 y 2; 128K para el 3
LiteLLM	Gateway delante de vLLM	Una clave virtual por agente, con presupuesto y límite de peticiones. Es lo que separa el coste de cada caso
Postgres 16 + pgvector	Checkpointer, almacén y RAG	Bases separadas en el mismo cluster: `agentes` para checkpoints y store, `retail` para las tablas de negocio y los embeddings
Langfuse	Trazas y coste	Por el callback de LangChain en los casos 1 a 4; el artículo 5 discute la vía OTel
FastAPI	Servir los grafos	Se escribe en el artículo 5; hasta entonces los ejemplos se invocan desde Python

Dos detalles del modelo que hay que fijar antes de escribir una línea del agente.

Pasar la instancia del modelo, no la cadena. create_agent acepta "openai:nombre" como atajo, pero con un modelo servido en vLLM el nombre no está en la tabla de perfiles de LangChain, y la instancia construida a mano es la única forma de controlar base_url, api_key y el perfil:

from langchain_openai import ChatOpenAI

modelo = ChatOpenAI(
 model="qwen3-30b-a3b",
 base_url="http://litellm.agentes.svc:4000/v1",
 api_key=os.environ["LITELLM_KEY_TIENDA"],
 temperature=0,
 profile={"max_input_tokens": 32768},
)

Sin profile, modelo.profile es None para cualquier nombre que no sea un modelo de OpenAI. Verificado con langchain-openai 1.6.2: ChatOpenAI(model="qwen3-30b", base_url=...) devuelve perfil None sin avisar. Con perfil, devuelve el diccionario que se le pasó. El valor tiene que quedar por debajo del --max-model-len de vLLM, porque el agente cuenta los tokens de forma aproximada y el servidor los cuenta con su tokenizador.

El middleware de resumen no resume sin disparador. SummarizationMiddleware(modelo) sin trigger construye una lista de cláusulas vacía y _should_summarize devuelve False siempre. No hay error ni aviso. Con trigger=("fraction", 0.8) sí hay comprobación en el constructor: sin perfil lanza una excepción con el mensaje de que hace falta profile={"max_input_tokens": ...}. Es el único sitio de todo el stack donde la ausencia de perfil se hace notar; en el resto, un modelo sin perfil es un modelo con ventana infinita hasta que vLLM devuelve un error de longitud de contexto.

Con esto, el resumen se configura así en los cuatro casos:

SummarizationMiddleware(
 modelo,
 trigger=("fraction", 0.75),
 keep=("fraction", 0.25),
)

Y el agente no llega nunca al límite del servidor. Con 32.768 de ventana, resume al pasar de 24.576 tokens aproximados y se queda con los últimos 8.192.

Lo que se mide en cada caso

Un responsable de tienda no compra un grafo. Compra minutos de dependiente, devoluciones bien resueltas o fichas publicadas. Cada artículo cierra con una tabla de métricas medidas, y las métricas salen de dos sitios: Langfuse, para lo que el agente hace, y la base de negocio, para lo que pasa después.

Caso	Métrica de agente (Langfuse)	Métrica de negocio (Postgres)
1 Empleado	Latencia p50/p95 por consulta, tokens y coste por consulta, llamadas a herramienta por turno, tasa de cortes por límite	Consultas resueltas sin escalar al encargado, tiempo hasta registro de una rotura
2 Cliente	Interrupciones por cada cien pedidos, tiempo entre interrupción y reanudación, decisiones editadas frente a aprobadas tal cual	Devoluciones aprobadas fuera de política (debe ser cero), importe medio aprobado con y sin humano
3 Suministro	Tokens por referencia analizada, aciertos de caché de nodo, duración del abanico frente al número de referencias	Referencias con rotura evitada, días de cobertura tras la reposición propuesta
4 Fichas	Intentos por ficha hasta veredicto, tasa de aprobación a la primera, segunda y tercera, tokens por ficha publicada	Fichas publicadas por hora, devoluciones por descripción incorrecta

Las métricas de agente se sacan con dos valores en la configuración: metadata={"caso": "tienda", "tienda": ctx.tienda} y el thread_id. Langfuse agrupa por ellos. Las métricas de negocio se sacan con SQL sobre las tablas del dominio, con el empleado y el asiento que las herramientas escriben en movimientos y devoluciones. Correlar las dos es cuestión de escribir el trace_id de Langfuse en la fila de negocio; las herramientas de escritura de la serie lo hacen.

Lo que la serie no cubre

El servidor HTTP de LangGraph (langgraph-api), su cola de ejecuciones, el cron, Studio y la API de asistentes, hilos y ejecuciones. Todo eso tiene licencia Elastic 2.0, pide clave de licencia comercial para producción y llama a casa; el artículo de deepagents lo documenta con fichero y línea. La serie sirve los grafos con FastAPI en el artículo 5 y asume que se pierde esa API. langgraph dev aparece en los ejemplos como lo que es, un servidor en memoria para desarrollo.

Tampoco cubre entrenamiento ni ajuste fino del modelo. Los cuatro casos son de inferencia sobre un modelo abierto tal cual sale del repositorio, y las decisiones de dimensionado son de inferencia: ventana, batching en vLLM, aciertos de caché de prefijo.

Y no cubre la parte de interfaz. Cómo se muestra una interrupción a un encargado en una tablet es un problema de aplicación; el caso 2 entrega el contrato de datos de la interrupción y de la reanudación, no la pantalla.

Método

Cada afirmación sobre el comportamiento del código se ha verificado ejecutando el paquete instalado, con estas versiones:

Paquete	Versión
langgraph	1.2.11
langgraph-checkpoint	4.2.0
langgraph-checkpoint-postgres	3.1.2
langgraph-prebuilt	1.1.0
langchain	1.4.1
langchain-core	1.6.3
langchain-openai	1.6.2

Cuando un artículo dice “hace X”, se ha ejecutado X. Cuando dice “el código sugiere X”, no se ha ejecutado y va marcado así. Los ejemplos de código de la serie se ejecutan contra un modelo falso de LangChain que devuelve mensajes con llamadas a herramientas fijas, para verificar la estructura del grafo, el orden de los nodos y el número de checkpoints; y contra vLLM para las cifras de latencia y tokens. Las dos cosas se distinguen en el texto.

Un aviso de fechas. La 1.0 de LangGraph y de LangChain salió en octubre de 2025 y deprecó create_react_agent a favor de create_agent. La mayoría de guías, cursos y respuestas en foros siguen mostrando el prebuilt antiguo, con langgraph.prebuilt.create_react_agent y un state_modifier en vez de middleware. Funcionan todavía, con aviso de deprecación, y no tienen el sistema de middleware. Nada de esta serie se apoya en ellos.

Checklist

Antes de escribir el primer agente sobre este stack:

El modelo se pasa como instancia de ChatOpenAI con base_url al gateway y profile={"max_input_tokens": N}, con N por debajo del --max-model-len de vLLM.
SummarizationMiddleware lleva trigger explícito; sin él no resume.
El contexto de ejecución es una dataclass que se pasa en cada invoke y no se guarda en el estado.
El rol se comprueba dentro de las herramientas con efecto, no en el prompt.
El thread_id lo construye la aplicación; el cliente no lo elige.
El checkpointer de Postgres se inicializa con setup() una vez, desde un proceso con permiso de DDL, no desde los pods del agente.
Cada agente tiene su clave virtual en LiteLLM con presupuesto, para que el coste salga separado por caso.
Se ha contado cuántos checkpoints deja un turno típico con el middleware elegido, y se ha multiplicado por los turnos por día antes de dimensionar la base de datos.

Trampas y cosas que no son lo que parecen

El middleware no es gratis en la base de datos. Cada nodo de middleware es un superstep y cada superstep es una fila de checkpoint. Con los dos límites del caso 1, 11 filas por turno con una herramienta, contra 5 sin ellos. Con SummarizationMiddleware, que también es un nodo, trece. El coste de cómputo es despreciable; el de almacenamiento y el de la limpieza que no existe, no.

ChatOpenAI sin perfil no avisa. El agente asume ventana desconocida, SummarizationMiddleware con disparador por fracción se niega a construirse, y con disparador por tokens funciona a ciegas respecto al servidor. La única defensa es el profile explícito y una aserción al arrancar.

SummarizationMiddleware(modelo) es un middleware que no hace nada. Sin trigger, la lista de cláusulas está vacía y no resume nunca. Se ve el nodo en el grafo y en las trazas, y eso da una falsa sensación de que el contexto está controlado.

interrupt() re-ejecuta el nodo entero. Lo que haya antes de la interrupción en ese nodo se ejecuta dos veces: al interrumpir y al reanudar. Si es una escritura en el TPV, se escribe dos veces. Esto condiciona todo el caso 2.

El checkpointer de Postgres solo sabe borrar hilos enteros. En langgraph-checkpoint-postgres 3.1.2, delete_thread está implementado; prune, copy_thread y delete_for_runs heredan de la clase base y lanzan NotImplementedError. Y la propia clase base avisa de que una poda parcial hecha a mano puede dejar los canales delta reconstruyéndose vacíos sin error. La retención es un trabajo de borrado por hilo que se escribe en el artículo 5.

langgraph dev no es un servidor. Es hot reload y estado en memoria. En el artículo 5 los grafos se sirven con FastAPI y un checkpointer de Postgres, y esa es la única configuración que la serie llama producción.

Cierre

Lo que se lleva de este marco es una regla y un stack. La regla: create_agent mientras el problema quepa en un ciclo modelo-herramientas con middleware, y StateGraph cuando haga falta una casilla que el modelo no debe controlar, sea una firma, un abanico o un contador. El stack: vLLM, LiteLLM, Postgres con pgvector y Langfuse en un cluster propio, con el modelo pasado como instancia y con perfil, y con el contexto de ejecución fuera del estado.

El siguiente artículo construye el primer agente sobre eso. Es el más sencillo de los cuatro y el que más se parece a lo que la mayoría de equipos ya tiene a medias: un asistente que responde a un dependiente sobre stock y procedimientos, con las herramientas comprobando el rol y con la tabla de métricas que un responsable de tienda puede leer al final de la primera semana.

Ver también

Fuentes

Releases de LangGraph, 1.2.11: https://github.com/langchain-ai/langgraph/releases
Guía de migración a LangGraph v1 (deprecación de create_react_agent): https://docs.langchain.com/oss/python/migrate/langgraph-v1
Referencia de create_agent y middleware en LangChain 1.x: https://docs.langchain.com/oss/python/langchain/agents
Documentación de interrupt y human-in-the-loop en LangGraph: https://docs.langchain.com/oss/python/langgraph/interrupts
Documentación de Send y map-reduce en LangGraph: https://docs.langchain.com/oss/python/langgraph/graph-api
Código de langchain.agents.middleware.summarization (langchain 1.4.1), _normalize_trigger y _should_summarize
Código de langgraph.checkpoint.postgres (3.1.2) y langgraph.checkpoint.base (4.2.0), métodos delete_thread, prune, copy_thread, delete_for_runs
Código de langchain_openai.chat_models.base (1.6.2), resolución del perfil de modelo