Langgraph 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

deepagents en un cluster propio: el SDK es libre, el servidor no, y lo que hay que construir en medio

Tue, 15 Sep 2026 07:00:00 +0200

Apertura de la vertical de plataforma agéntica. Los artículos anteriores trataron las piezas por separado: el gateway de inferencia, su segunda puerta, qué cuesta una flota de agentes y el aislamiento. Este trata lo que va encima. Verificado contra deepagents 0.7.14 y el repositorio de LangGraph, commits del 14 de septiembre de 2026.

TL;DR

deepagents no es un runtime. Es una factoría que ensambla middleware y delega en la factoría de agentes de LangChain. Devuelve un grafo compilado de LangGraph y nada más. La documentación del propio repositorio lo dice sin adornos: no introduce un runtime nuevo. Eso es una buena noticia para quien despliega, porque corre donde corra Python.

La herramienta de planificación ya no existe. Desapareció en la 0.7.0 como cambio incompatible, junto con el canal de estado que la sostenía. Casi todo lo escrito sobre este armazón sigue describiéndola como una de sus tres patas. Hoy hay que pedirla explícitamente, y hay que pedirla también en cada subagente.

Con la configuración por defecto, los ficheros del agente viven dentro del checkpoint. El backend de estado guarda el contenido completo, los binarios en base64, en el mismo sitio donde se persiste la conversación. Cambiar eso es una línea y es la primera decisión de arquitectura del despliegue.

La base de datos crece por paso del bucle, no por turno. Cuatro tablas, una fila por superstep, una por canal y versión, otra por escritura de tarea. Y de las cuatro operaciones de limpieza que la clase base declara, en la implementación de Postgres solo hay una: borrar un hilo entero. Las otras tres lanzan excepción de no implementado.

Podar a mano puede vaciar el historial en silencio. El propio código avisa de que un borrado parcial rompe la cadena de deltas y deja los canales reconstruyéndose vacíos sin lanzar ningún error. La única poda segura es por hilo completo.

El aislamiento entre inquilinos es el identificador de hilo, y no hay ninguna comprobación de propietario. Quien pueda enviar un identificador de hilo lee ese hilo. El backend de ficheros en disco fija su raíz al construir el agente, así que no separa a nadie. Y el ejemplo de la documentación para calcular el espacio de nombres por usuario no funciona fuera de la plataforma gestionada.

Hay una trampa de configuración que deja un modelo de ventana corta sin compactar. Si el modelo no expone su ventana, el umbral de compactación cae a 170.000 tokens. Servido en un vLLM con ventana de 32.768, el agente revienta por longitud de contexto mucho antes de compactar. El fallo es silencioso y se arregla pasando el perfil a mano.

La observabilidad sin plataforma existe, y pasa por un paquete que no es evidente. El núcleo de LangChain no emite OpenTelemetry: cero referencias. El exportador vive dentro del SDK de LangSmith, y hay un modo que emite solo por OTLP sin hablar con el servicio. Es el camino a un Langfuse propio, y conviene saber por dónde pasa.

Y aquí se acaba lo libre: el servidor. El SDK, el motor del grafo y los checkpointers son MIT. El servidor que los publica por HTTP tiene licencia Elastic 2.0, pide una clave de licencia comercial para producción, añade Redis al stack y reporta metadatos a un endpoint externo salvo acuerdo de aislamiento. La herramienta de desarrollo es explícitamente de desarrollo.

Lo que queda es una lista de cosas que hay que escribir. Autorización por hilo, retención, cola de ejecuciones, cancelación, drenado limpio y migraciones. Ninguna es difícil. Todas son trabajo, y ninguna aparece en el ejemplo de veinte líneas de la portada.

Estás aquí: el armazón llega después del modelo

La secuencia se repite en todos los proyectos. Primero se monta la inferencia, que es lo visible. Luego el gateway, porque hacen falta claves y presupuestos. Luego la observabilidad, porque nadie sabe qué está pasando. Y cuando todo eso funciona, alguien pregunta por qué el asistente no puede hacer tareas de varios pasos, y entra en escena la palabra agente.

En ese punto la tentación es escribir el bucle a mano, y durante dos semanas parece buena idea. El bucle es fácil. Lo que no es fácil es todo lo que se descubre después: qué pasa cuando el contexto se llena, dónde se guardan los ficheros intermedios, cómo se reanuda una tarea que se quedó a medias, cómo se pide confirmación a un humano sin perder el estado.

Un armazón de agentes es exactamente eso: la respuesta empaquetada a esas preguntas. Y elegirlo parece una decisión de librería, del tamaño de elegir un cliente HTTP. No lo es. Decide dónde vive el estado de tus usuarios, qué base de datos crece, qué se puede aislar y qué no, y en el caso que nos ocupa, si hay una licencia comercial esperando al final del camino.

Este artículo mira deepagents con esos ojos. No es una guía de uso, y no evalúo si sus agentes son buenos. Miro qué obliga a construir.

La analogía: el andamio y la grúa

Una obra necesita andamio y necesita grúa, y no son lo mismo aunque las dos sean estructuras metálicas que rodean al edificio.

El andamio lo monta uno con piezas compradas. Se adapta a la fachada, se puede ampliar, y el día que la obra termina se desmonta y se guarda. Nadie cobra por usarlo una vez comprado.

La grúa es otra cosa. Se alquila, viene con operador, tiene número de serie y hay que avisar a alguien cuando se monta. Sin grúa la obra avanza, más despacio y con más gente, pero avanza.

Aquí el andamio es el SDK y el motor del grafo, y es de quien lo compra. La grúa es el servidor que expone el agente por HTTP, y esa viene con contrato. El artículo trata de dónde está exactamente la línea entre las dos, porque en el folleto no se ve, y de cuánta obra se puede hacer sin grúa.

Qué es deepagents de verdad

Lo primero que hay que quitarse de la cabeza es que sea un sistema. Es una función.

La factoría principal ensambla una lista de middleware y llama a la factoría de agentes de LangChain, que es quien construye el grafo. Lo que devuelve es un grafo compilado, con una configuración añadida encima que sube el límite de recursión a un número muy alto y añade una etiqueta de integración en los metadatos. El documento de arquitectura del propio repositorio lo declara: no se introduce un runtime nuevo.

Compilado con las opciones por defecto, el grafo tiene los nodos que cabría esperar de un bucle de razonamiento y acción: inicio, un nodo previo que repara llamadas a herramienta incompletas, el nodo del modelo, el nodo de herramientas y el final. Las aristas condicionales van del modelo a herramientas, al propio modelo o al final. No hay más. Todo lo que parece un sistema es middleware que añade nodos solo cuando declara sus propios enganches.

Las herramientas que aparecen de serie son las de sistema de ficheros, más la de delegación en subagentes: listar, leer, escribir, editar, borrar, buscar por patrón, buscar por contenido, ejecutar, y la de tarea.

La consecuencia buena de esto es la portabilidad. Si algo es un grafo de LangGraph y nada más, corre en un contenedor de Python cualquiera, con el checkpointer que uno elija, contra el modelo que uno elija. No hay servicio escondido detrás.

Lo que ya no está

Merece un apartado porque contradice a casi todo lo publicado. La herramienta de planificación, la que escribía una lista de tareas y la mantenía en un canal del estado, se eliminó en la 0.7.0 como cambio incompatible declarado en el registro de cambios. No está la herramienta, no está el canal, y no está el fragmento de prompt que la acompañaba.

Sobrevive como middleware de LangChain, y hay que pedirla a mano. Con un detalle que muerde: hay que pedirla también en cada subagente, porque cada subagente monta su propia pila. Lo único que queda de la etapa anterior son restos arqueológicos, como la clave de estado que sigue en la lista de claves excluidas al pasar contexto a un subagente.

El plan, hoy, se apoya en ficheros. Que es coherente con el resto del diseño, y es otra razón para mirar con atención dónde viven esos ficheros.

Dónde vive el estado

Esta es la primera decisión de arquitectura y la que más caro sale equivocar.

El estado del agente tiene dos canales grandes. Los mensajes, con un reductor propio que deduplica por identificador y trata los borrados como lápidas. Y los ficheros, con su propio reductor donde un valor nulo significa borrado. Los dos usan un tipo de canal que escribe deltas y guarda una instantánea completa cada cincuenta actualizaciones, y el comentario del código explica el motivo: pasar el crecimiento del checkpoint de cuadrático a lineal respecto al número de mensajes.

Ese tipo de canal está marcado como beta en su propio código, con el aviso de que la representación en disco puede cambiar. Conviene saberlo antes de apoyar una plataforma encima.

Los backends

Hay una interfaz común y varias implementaciones. Las que importan para decidir:

Backend	Dónde viven los ficheros	Persistencia
Estado	Dentro del estado del grafo, o sea del checkpoint	Por hilo, en la base de datos del checkpointer
Disco	En un directorio real anclado a una raíz	Donde monte el volumen
Almacén	En el almacén de LangGraph, con espacio de nombres	Cruza hilos, con tiempo de vida
Compuesto	Enrutado por prefijo de ruta entre los anteriores	Mixta

El backend por defecto es el de estado. Es decir: por defecto, todo lo que el agente escriba acaba dentro del checkpoint, y los binarios van codificados en base64 dentro del mismo JSON. Para una demostración es cómodo, porque no hay que montar nada. Para una plataforma con usuarios reales es una decisión de dimensionado tomada por omisión.

Hay un detalle que redondea el asunto. El middleware de ficheros desaloja automáticamente los resultados de herramienta grandes a un fichero cuando superan un umbral de tokens, para que no ocupen la ventana de contexto. Es un buen mecanismo. Pero con el backend de estado, desalojar a fichero significa mover el contenido de un sitio del checkpoint a otro sitio del mismo checkpoint. Sale de la ventana del modelo y no sale de la base de datos.

Lo que crece en la base de datos

El checkpointer de Postgres crea cuatro tablas: una de migraciones, una de checkpoints, una de blobs por canal y versión, y una de escrituras por tarea. Las claves primarias empiezan todas por el identificador de hilo, y hay un índice por tabla sobre esa columna.

Lo que hay que interiorizar es el ritmo. Se escribe una fila de checkpoint por superstep del motor, no por turno de conversación. Un turno con cuatro llamadas a herramienta son varios supersteps. Nada de eso se recicla solo.

Y aquí llega la parte incómoda. La clase base del checkpointer declara cuatro operaciones de mantenimiento: borrar un hilo, borrar por ejecución, copiar un hilo y podar con estrategia. En la implementación de Postgres solo está implementada la primera. Las otras tres heredan la excepción de no implementado de la clase base. Borrar un hilo son tres sentencias de borrado por identificador, y ya está.

O sea: la retención te la montas tú. Y con un cuidado que el propio código documenta y que conviene citar entero, porque es el tipo de aviso que se lee después del incidente. Una poda ingenua que elimine checkpoints intermedios y sus escrituras puede cortar la cadena de deltas; el checkpoint superviviente rara vez es un punto de instantánea, así que sus canales se reconstruirían vacíos sin que se lance ningún error.

Traducido a operación: el barrido periódico borra hilos enteros y solo hilos enteros. Nunca filas sueltas. Y como la tabla de checkpoints no tiene columna de fecha, para saber qué hilo es viejo hay que llevar la cuenta por fuera o apoyarse en que el identificador de checkpoint es un UUID ordenable por tiempo.

Existe una variante del checkpointer que guarda solo el último estado y no retiene historia, que acota el crecimiento de raíz. Con una reserva importante que hay que verificar antes de usarla: no está claro que sea compatible con los canales de deltas que este armazón usa por defecto en mensajes y ficheros. Combinar las dos cosas sin comprobarlo es pedir un problema silencioso.

El almacén, que sí tiene limpieza

Curiosamente, la pieza hermana está mejor resuelta. El almacén tiene tiempo de vida configurable, con refresco en lectura, omisión de expirados y un intervalo de barrido, y el barrido es un borrado por fecha de expiración.

Dos avisos. El barredor es un hilo dentro del proceso, así que con varias réplicas hay varios barredores compitiendo por el mismo borrado; es idempotente, pero es contención gratuita y se evita apagándolo y poniendo el borrado en una tarea programada del cluster. Y la búsqueda semántica del almacén exige la extensión de vectores en la base de datos, lo que condiciona la imagen del Postgres gestionado, que normalmente no la trae.

El aislamiento que no existe

Si la plataforma va a tener más de un inquilino, este es el apartado que decide la topología del despliegue.

Lo único que separa un hilo de otro es el identificador de hilo. Es la primera columna de la clave primaria en las tres tablas. No hay ninguna comprobación de propietario en ninguna parte del checkpointer. Quien consiga enviar un identificador de hilo en la configuración de la llamada, lee ese hilo. La autorización es responsabilidad de la capa que uno escriba por encima, y como esa capa también hay que escribirla, conviene anotarlo ya.

Por backend, la situación es distinta:

El de estado hereda el aislamiento del hilo, que es suficiente si la capa HTTP valida que el usuario es dueño del hilo.
El de almacén calcula el espacio de nombres por llamada, mediante una función que recibe el contexto de ejecución. Es la opción correcta para multiinquilino.
El de disco fija su raíz en el constructor, cuando se construye el agente. No hay ningún camino en el código que la recalcule por petición, por hilo o por inquilino. Compartir un despliegue entre inquilinos con este backend significa que todos ven el mismo directorio.

Sobre ese último punto conviene no confundirse con la protección que sí existe. El modo virtual, que ahora viene activado por defecto, bloquea las rutas que se salen de la raíz. Eso protege del recorrido de directorios. No protege del vecino. El propio documento de amenazas del proyecto lo admite: ese modo existe para dar soporte al enrutado por prefijo del backend compuesto, no como frontera de seguridad.

Hay además una trampa documental que vale la pena señalar porque cuesta una tarde. El ejemplo que la documentación propone para calcular el espacio de nombres por usuario lee la identidad de un campo de información de servidor del contexto de ejecución. Ese campo está anotado en el código de LangGraph como metadatos inyectados por el servidor gestionado, y nulo cuando se ejecuta LangGraph de código abierto sin despliegues gestionados. En un cluster propio con una capa HTTP propia, ese ejemplo falla. Lo que hay que usar es el contexto que uno mismo rellena, con el identificador que venga validado del proveedor de identidad.

Y una frontera más que cruza sin avisar: los middleware de memoria y de habilidades interpolan el contenido de ficheros en el prompt de sistema tal cual, sin sanear. Si dos inquilinos comparten un directorio que sirve de origen para eso, el primero escribe instrucciones que ejecuta el agente del segundo. Es inyección de prompt por almacenamiento compartido, y se evita con la misma medida que todo lo anterior: no compartir el backend de disco entre inquilinos.

La conclusión de topología es corta. Multiinquilino de verdad con ficheros significa un despliegue por inquilino, con su espacio de nombres, su volumen y su cuota, o bien el backend de almacén con espacio de nombres calculado por petición. No hay una tercera vía.

El modelo, y la trampa que hay que conocer

El modelo por defecto es un proveedor comercial concreto, y está marcado como obsoleto: pasar el modelo vacío avisa y dejará de funcionar. Se puede inyectar cualquier modelo de chat de LangChain, que es lo que hará quien sirva sus propios pesos.

Con dos detalles de integración que no son evidentes.

El primero. Para apuntar a un endpoint compatible con OpenAI, que es como se ve un vLLM detrás de un gateway, hay que pasar la instancia ya construida, no la cadena con prefijo de proveedor. Con la cadena se aplica un perfil de proveedor que fuerza el uso de la API de respuestas, que un vLLM normalmente no implementa. Pasando el objeto construido no se aplica ningún perfil y el agente queda limpio.

El segundo es la trampa, y en mi opinión es el fallo de configuración más probable de todo el despliegue.

El middleware de compactación calcula sus umbrales a partir del perfil del modelo. Si el modelo declara su ventana de entrada, compacta al llegar al 85 % de la ventana y conserva el 10 %. Si no la declara, cae a un valor fijo: 170.000 tokens.

La cadena que lleva a no declararla es la habitual en un despliegue propio. El cliente de OpenAI resuelve el perfil buscando el nombre del modelo en una tabla estática de modelos del proveedor. Un modelo servido como qwen3-30b-a3b no está en esa tabla, así que el perfil queda vacío, y el vacío se convierte en nulo. El método que lo asigna traga cualquier excepción, así que no hay aviso.

Resultado: un vLLM con ventana de 32.768 tokens no compactará hasta los 170.000. El servidor devolverá error de longitud de contexto mucho antes, y lo hará de forma intermitente, solo cuando las conversaciones se alarguen. Hay una red de seguridad que captura el error y recorta, pero eso es recuperación reactiva después de una llamada fallida, no planificación.

El arreglo es una línea, porque el perfil es un campo público y solo se rellena solo cuando está vacío: se pasa al construir el modelo, con un valor por debajo de la ventana real para dejar sitio a la generación. Y merece un assert en el arranque, porque es el tipo de cosa que nadie mira hasta que falla.

Un apunte de dimensionado relacionado. Con los umbrales por defecto y una ventana de 32.768, la compactación dispararía a 27.852 tokens, mientras que el desalojo de resultados de herramienta grandes está fijado en 20.000. Es decir, un solo resultado de herramienta puede ocupar casi todo el presupuesto antes de que nada lo desaloje. Con ventanas de 128.000 los defaults están proporcionados; por debajo de 64.000 hay que bajar esos dos umbrales a mano.

Las herramientas, y el MCP que no está donde parece

Este armazón tiene sus herramientas de sistema de ficheros y su herramienta de delegación, y las demás se pasan como una lista normal de herramientas de LangChain.

El dato que importa a quien tenga un gateway MCP montado: el SDK no integra MCP. No hay ninguna referencia al protocolo en el paquete, ni dependencia de adaptadores. La integración vive en la herramienta de línea de comandos que acompaña al proyecto, que sí depende de los adaptadores de MCP para LangChain, resuelve configuraciones al estilo de los clientes de escritorio, y convierte cada herramienta remota en una herramienta de LangChain que luego pasa por la lista normal.

O sea que el camino existe y está probado, pero hay que recorrerlo uno: cargar las herramientas del gateway con los adaptadores y pasarlas en la lista. Lo cual, dicho sea de paso, encaja bien con lo que ya sabemos del catálogo: el filtrado por credencial que hace el gateway se aplica en el listado, así que cada agente recibe el subconjunto que le toca sin que el armazón tenga que saber nada.

Los subagentes

Se declaran de tres formas y se invocan con una herramienta de tarea que recibe una descripción y un tipo. Lo que hay que saber para diseñar con ellos:

El subagente recibe el estado del padre excepto los mensajes y unas cuantas claves privadas, y arranca con un único mensaje humano que es la descripción de la tarea. Los ficheros sí se heredan, y comparte el mismo objeto de backend, así que padre e hijo trabajan sobre el mismo sistema de ficheros lógico. El resultado vuelve como un mensaje de herramienta con la respuesta estructurada o el último texto del hijo.

La profundidad es efectivamente de un nivel. Verificado compilando el grafo: la pila que se monta para un subagente declarativo no incluye el middleware de subagentes, así que el hijo no tiene la herramienta de tarea y no puede delegar a su vez.

Y no hay límite de concurrencia propio. El paralelismo es el de las llamadas paralelas a herramienta del motor, y el prompt de la herramienta de tarea invita explícitamente a lanzarlas en paralelo. Quien tenga cuota de GPU por inquilino querrá poner el freno en su sitio, porque aquí no está.

La ejecución de código

El protocolo de sandbox está bien definido y las implementaciones empaquetadas son casi todas de servicios de pago: cuatro proveedores comerciales, más un intérprete de JavaScript embebido y un sandbox del propio proveedor de la plataforma.

Queda un backend de shell local que conviene mirar de cerca antes de considerarlo. Ejecuta el comando con la shell del sistema, y su propio docstring enumera lo que no hace: nada de aislamiento, nada de separación de procesos, nada de límites de recursos, y lista los entornos de producción y multiinquilino como casos de uso inapropiados. Tiene además una opción de heredar el entorno del proceso que, activada, entrega al modelo todas las variables, incluidas las credenciales del gateway y la cadena de conexión de la base de datos. Viene desactivada, y es un pie de bala fácil de pegarse.

La salida razonable en un cluster propio es implementar el protocolo uno mismo, y es más pequeño de lo que parece. La clase base de sandbox exige cuatro cosas: un identificador, ejecutar, subir ficheros y bajar ficheros. Todo lo demás, listar, leer, escribir, editar, borrar y buscar, lo construye la clase base encima de ejecutar. Mirando una de las implementaciones comerciales, son del orden de ciento cincuenta líneas.

Un requisito de la imagen que condiciona el Dockerfile y que conviene saber antes: los ayudantes de la clase base inyectan pequeños scripts de Python codificados para resolver búsquedas y comprobaciones, así que la imagen del sandbox necesita Python y una shell POSIX o la mitad de las llamadas fallan.

Sobre cómo implementarlo, la forma que encaja con un Kubernetes propio es un contenedor efímero por sesión con tiempo de vida acotado, límites de recursos, sin token de cuenta de servicio montado y con una política de red que solo permita salir hacia el gateway de inferencia. Ejecutar se resuelve contra la API de ejecución del cluster, y subir y bajar ficheros por el mismo canal. La alternativa con menos código es una clase de runtime aislada para el pod del agente, un pod por inquilino, y el backend de shell dentro; se pierde el multiinquilino en un solo pod y no hay que escribir nada.

La observabilidad, y el paquete por el que pasa

Aquí hay un dato que sorprende y que conviene tener claro antes de diseñar el pipeline de trazas.

El núcleo de LangChain no emite OpenTelemetry. Cero referencias en todo el paquete. Su trazador nativo habla con el servicio de observabilidad del fabricante y punto.

El exportador OTLP existe, pero vive dentro del SDK de ese servicio. Y ahí está la buena noticia: ese SDK tiene un modo de trazado que emite solo por OTLP, sin hablar con el servicio, leyendo el destino y las cabeceras de las variables de entorno estándar de OpenTelemetry. El transporte es HTTP con protobuf, que es justo lo que acepta un Langfuse autoalojado en su ruta de ingesta.

Es decir: para llevar las trazas del agente a la observabilidad propia hay que instalar el paquete del fabricante y pedirle que no hable con el fabricante. Funciona, es soportado y está documentado, pero es una dependencia que hay que declarar en el análisis de la cadena de suministro, no un detalle de configuración. Y si faltan los paquetes de OpenTelemetry, emite un aviso y deja de trazar en silencio, así que el arranque debería comprobarlo.

Existe la alternativa del manejador de retrollamadas que publica el propio Langfuse, con menos piezas. La diferencia práctica es la correlación: por la vía OTLP los spans del agente comparten identificador de traza con los del gateway y los del motor de inferencia, y se ve una petición entera de punta a punta. Por la vía de retrollamadas, no. Para quien ya tenga un colector desplegado, la vía OTLP es la que paga.

El servidor: aquí se acaba lo libre

Todo lo anterior son decisiones de arquitectura. Esto es una decisión de licencia, y es la que da título al artículo.

El SDK del armazón es MIT. El motor del grafo es MIT. Los checkpointers de memoria, SQLite y Postgres son MIT. Todo eso corre en cualquier sitio, sin clave, sin registro y sin llamar a nadie.

El servidor que expone un grafo por HTTP es otra cosa. El paquete que lo implementa tiene licencia Elastic 2.0, cuyas cláusulas relevantes prohíben ofrecer el software a terceros como servicio gestionado y prohíben modificar o eludir la funcionalidad de clave de licencia. El propio comando de la herramienta de línea imprime las condiciones: para desarrollo local pide una clave de API del servicio, y para uso en producción pide una clave de licencia en una variable de entorno.

Hay además reporte de uso. El código del servidor contiene un endpoint de baliza al que envía metadatos, con una cabecera que lleva la clave de licencia. La documentación de autoalojamiento lo confirma desde el otro lado, al listar entre los requisitos la salida de red hacia ese dominio para verificación de licencia y reporte de uso si no se ejecuta en modo aislado. El modo aislado es una variante contractual, no una casilla que uno marca.

Y arrastra infraestructura: además de Postgres, pide Redis.

La herramienta de desarrollo, que es la que sale en todos los tutoriales, se describe a sí misma como modo de desarrollo con recarga en caliente y servidor en memoria. No es un servidor de producción y no pretende serlo.

Nada de esto es un reproche. Es un modelo de negocio legítimo y bastante habitual: el núcleo permisivo y el plano de control comercial. Lo que no es legítimo es enterarse tarde. Quien esté montando una plataforma con requisito de soberanía, sin dependencias de servicios externos y con el argumento de que todo el stack es abierto, tiene que saber que la pieza que convierte el grafo en un servicio no cumple ese requisito.

Lo que hay que construir

La salida es escribir la capa HTTP uno mismo, y la buena noticia es que es aburrida. Un servicio que compile el grafo una vez con el checkpointer apuntando a la base de datos, y exponga un endpoint que valide el testigo del proveedor de identidad, derive el identificador de hilo y el contexto de inquilino, e invoque el grafo. Streaming por eventos si hace falta.

Lo que hay que escribir además, y que el servidor comercial daba hecho:

Autorización por hilo. El motor no la tiene. Es la más importante y la más fácil de olvidar porque nada falla si no está.
Retención y borrado. Tarea programada que borre hilos enteros, nunca filas sueltas, por las razones del apartado del estado.
Migraciones. La preparación del esquema hay que llamarla explícitamente y necesita permisos de definición de datos, así que va en un trabajo aparte con un rol distinto del de ejecución. Y como crea índices de forma concurrente, no puede pasar por un agrupador de conexiones en modo transacción; conviene apuntar contra el servicio de escritura directo.
Sondas de salud y drenado. El motor tiene un mecanismo de drenado cooperativo, pero conectarlo a la señal de terminación del contenedor es trabajo propio.
Cola de ejecuciones y cancelación, si hacen falta ejecuciones largas en segundo plano. Aquí es donde más se nota la ausencia, y la respuesta razonable es una cola sobre la misma base de datos antes que otro sistema.
Durabilidad decidida a conciencia. Hay tres modos: persistir antes del paso siguiente, persistir en paralelo, o persistir solo al salir. El último no vale en Kubernetes: si el pod muere, se pierde el turno entero.

Sobre este último punto conviene ser explícito, porque afecta al diseño de las herramientas. El motor guarda las escrituras de cada tarea en cuanto termina, y al reanudar reaplica las que ya estaban y no las repite. Una herramienta que terminó no se vuelve a ejecutar. Una herramienta que estaba en vuelo cuando el pod murió sí, porque su escritura nunca llegó. La semántica es de al menos una vez, así que toda herramienta con efecto externo tiene que ser idempotente o llevar clave de idempotencia. No hay exactamente una vez.

Y lo mismo aplica a las interrupciones para confirmación humana: al reanudar, el nodo se re-ejecuta entero, así que cualquier efecto lateral que estuviera antes de la interrupción dentro del mismo nodo se repite. La regla es que la interrupción vaya primero.

El encaje con el registro de actividad

Dos cosas de este montaje tocan el cumplimiento de lleno, y las dos salen de apartados anteriores.

La primera es que el checkpoint es, de facto, un repositorio de datos personales. Contiene la conversación entera y, con el backend por defecto, los ficheros que el agente haya escrito. Si la plataforma atiende a personas identificables, esa base de datos necesita cifrado, retención propia y control de acceso separado, exactamente igual que la tabla de gasto del gateway. La diferencia es que aquí no hay ningún interruptor de redacción que valga: el estado es el estado.

La segunda es la trazabilidad. Un agente que delega en subagentes y ejecuta herramientas produce una cadena de acciones que hay que poder reconstruir, y el único sitio donde esa cadena queda completa es la traza. Que la traza salga por OTLP hacia la observabilidad propia deja de ser una preferencia técnica y pasa a ser el mecanismo de registro. Conviene diseñarlo así desde el principio, y no añadirlo después.

Como siempre en esta serie, los códigos concretos del anexo hay que contrastarlos contra el texto vigente antes de llevarlos a un documento de cumplimiento; el planteamiento está desarrollado en el artículo de controles técnicos.

Checklist

Decidir el backend de ficheros antes de la primera demostración, porque el de por defecto mete el contenido en la base de datos.
Pasar el perfil del modelo a mano con la ventana real, y comprobarlo en el arranque.
Bajar los umbrales de desalojo si la ventana del modelo está por debajo de 64.000 tokens.
Construir el modelo como instancia, nunca como cadena con prefijo de proveedor, si detrás hay un endpoint compatible con OpenAI.
Escribir la autorización por hilo antes de abrir el servicio a más de un usuario.
Un despliegue por inquilino si se usa el backend de disco; espacio de nombres calculado por petición si se usa el de almacén.
Calcular ese espacio de nombres desde el contexto propio, no desde el campo de información de servidor, que es nulo fuera de la plataforma gestionada.
Tarea programada de retención que borre hilos enteros y solo hilos enteros.
Migraciones del esquema en un trabajo aparte, con rol propio y contra el servicio de escritura directo.
Durabilidad síncrona, y herramientas con efectos externos idempotentes.
Trazas por OTLP con el modo que no habla con el servicio del fabricante, y comprobación en el arranque de que los paquetes están.
Poner límite de concurrencia a los subagentes si hay cuota de GPU de por medio.
Si hace falta ejecución de código, implementar el protocolo de sandbox contra un contenedor efímero; el backend de shell local está desaconsejado por su propia documentación.
Anotar en el análisis de la cadena de suministro las dependencias duras de proveedores comerciales que el paquete arrastra aunque no se usen.

Trampas y cosas que no son lo que parecen

La herramienta de planificación se eliminó en la 0.7.0. Hay que añadirla a mano, y también en cada subagente.
El backend por defecto guarda los ficheros dentro del checkpoint, binarios incluidos en base64.
Desalojar un resultado grande a fichero no lo saca de la base de datos con ese backend, solo de la ventana de contexto.
Se escribe un checkpoint por superstep, no por turno.
De las cuatro operaciones de limpieza declaradas, en Postgres solo existe borrar un hilo.
Una poda parcial puede vaciar el historial sin lanzar ningún error.
El canal de deltas está en beta y su representación en disco puede cambiar.
No hay comprobación de propietario en el checkpointer. El identificador de hilo no es una credencial.
La raíz del backend de disco se fija al construir el agente y no separa inquilinos.
El ejemplo de la documentación para el espacio de nombres por usuario no funciona fuera de la plataforma gestionada.
El middleware de ficheros y el de subagentes no se pueden quitar.
Si el modelo no declara su ventana, la compactación no dispara hasta los 170.000 tokens, en silencio.
Pasar el modelo como cadena con prefijo de proveedor fuerza una API que un vLLM no implementa.
El SDK no integra MCP; la integración vive en la herramienta de línea de comandos.
Los subagentes no delegan: la profundidad es de un nivel.
El núcleo de LangChain no emite OpenTelemetry; el exportador vive en el SDK del servicio del fabricante.
El servidor HTTP tiene licencia Elastic 2.0, pide clave de licencia para producción y reporta uso salvo acuerdo de aislamiento.
La herramienta de desarrollo es de desarrollo, con servidor en memoria.
La reanudación es de al menos una vez para herramientas en vuelo.

Cierre

La pregunta con la que empezó este artículo era si deepagents encaja en una plataforma propia. La respuesta es que sí, y que encaja mejor de lo que esperaba, precisamente porque es menos de lo que aparenta. Una pila de middleware sobre un grafo es fácil de alojar, fácil de entender y fácil de sustituir. Lo que no encaja es la pieza de al lado.

Esa asimetría es el patrón que llevo viendo todo el año en el ecosistema, y merece nombrarlo. El núcleo se publica con licencia permisiva porque el núcleo es donde se compite por adopción. El plano de control se publica con licencia restrictiva porque el plano de control es donde se cobra. Pasó con los gateways, pasa con la observabilidad, y pasa aquí. Quien monte plataforma soberana no puede evaluar un proyecto entero por la licencia de su repositorio principal: hay que mirar paquete a paquete, y mirar cuál de ellos es el que uno va a necesitar el día que aquello tenga usuarios.

La parte buena es que la factura, en este caso, se paga en trabajo y no en dinero. Lo que hay que construir para prescindir del servidor comercial es un servicio HTTP sin misterio, una tarea de retención, un trabajo de migración y una capa de autorización. Nada de eso es investigación. Todo eso es una semana de un ingeniero que sepa lo que hace, y a cambio queda un sistema que se despliega igual en un instituto que en un centro de datos clasificado, sin salida a internet y sin nadie contando ejecuciones al otro lado.

Lo que sí recomiendo es hacer esa lista antes de la primera demostración y no después. Porque el ejemplo de la portada funciona en veinte líneas, y las veinte líneas tienen el backend por defecto, el modelo sin perfil y ninguna autorización.

Ver también

Elegir gateway de inferencia — la pieza de debajo, y el mismo patrón de licencia mirado en otro sitio.
El gateway MCP de LiteLLM — de dónde salen las herramientas que este armazón consume.
Prioridad de herramientas MCP — cómo se decide qué subconjunto del catálogo ve cada agente.
Dimensionar para agentes — la carga real que genera un bucle de herramientas sobre el gateway y el motor.
El contratista con la llave maestra — el aislamiento de red que este artículo da por necesario.
El segundo vector de coste de los agentes — ejecución durable y qué cuesta un bucle que falla a medias.
Controles técnicos para ENS, 42001 y el AI Act — el marco donde encajan el registro y la retención.
LiteLLM y Langfuse: el par operativo — el destino de las trazas OTLP de las que habla el artículo.

Fuentes

langchain-ai/deepagents, código y documento de arquitectura: https://github.com/langchain-ai/deepagents.
langchain-ai/deepagents, registro de cambios de la rama del SDK (eliminación de la herramienta de planificación en la 0.7.0): https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/CHANGELOG.md.
langchain-ai/langgraph, motor, canales y checkpointers: https://github.com/langchain-ai/langgraph.
langgraph-checkpoint-postgres, esquema de tablas y operaciones de mantenimiento: https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres.
langgraph-checkpoint, clase base del checkpointer y aviso sobre poda con canales de deltas: https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint.
LangChain, despliegue de servidor autónomo (requisitos de licencia, Postgres, Redis y salida de red): https://docs.langchain.com/langsmith/deploy-standalone-server.
LangChain, trazado con OpenTelemetry: https://docs.langchain.com/langsmith/trace-with-opentelemetry.
Elastic License 2.0: https://www.elastic.co/licensing/elastic-license.
Langfuse, integración nativa OpenTelemetry (ruta de ingesta y autenticación): https://langfuse.com/integrations/native/opentelemetry.
Langfuse, integración con LangChain por retrollamadas: https://langfuse.com/integrations/frameworks/langchain.
langchain-ai/helm, chart del servidor: https://github.com/langchain-ai/helm.
Boletín Oficial del Estado, Real Decreto 311/2022, Esquema Nacional de Seguridad: https://www.boe.es/buscar/act.php?id=BOE-A-2022-7191.

Langfuse v4, día 2 (3 de 10): dos agentes conocidos instrumentados, Open Deep Research y GPT Researcher

Mon, 14 Sep 2026 07:00:00 +0200

Tercer artículo de una serie de diez sobre operar Langfuse v4 en producción. El primero recorría qué entra en una traza; el segundo medía lo que cuesta un turno de agente sobre un grafo mínimo. Este aplica lo mismo a dos agentes que la gente despliega. Código leído el 14 de septiembre de 2026: Open Deep Research en el commit 1b7d2e8 y GPT Researcher en el 6f99857, con Langfuse 4.15.2 y LangGraph 1.2.11.

TL;DR

Una petición de Open Deep Research con la configuración por defecto son 1.416 observaciones y 8,1 MB. Medido sobre una réplica fiel de su topología con cinco unidades concurrentes, seis iteraciones del supervisor y diez llamadas react por investigador, que son sus valores por defecto. Todo cae en una sola traza. Y es un suelo, porque en el banco los resultados de búsqueda son de trescientos caracteres y los de verdad son mucho mayores.

Ninguna de esas 1.416 es de tipo AGENT. Sus nueve nodos se llaman clarify_with_user, write_research_brief, research_supervisor, final_report_generation, supervisor, supervisor_tools, researcher, researcher_tools y compress_research. Ninguno contiene la cadena que busca el handler.

El abanico paralelo no rompe la traza, y el miedo a que la rompa es infundado. Open Deep Research reenvía el config a los subgrafos y GPT Researcher pasa uno nuevo con solo etiquetas. Probé los dos patrones: una traza en ambos casos, porque LangChain recompone el config desde la variable de contexto.

GPT Researcher son dos productos en el mismo repositorio. El modo multiagente es LangGraph y se traza como cualquier grafo. El modo estándar no tiene grafo, y ahí cada llamada al modelo abre su propia traza: ocho llamadas, ocho trazas, medido.

Su nodo humano no usa interrupt(), espera por websocket. La observación del nodo se queda abierta mientras la persona piensa, de modo que su duración mide latencia humana. El percentil 95 de ese grafo no significa nada si no se excluye ese nodo.

Instrumentar los dos no requiere tocar sus repositorios. En Open Deep Research basta importar el grafo compilado y pasar el handler por config. En el modo estándar de GPT Researcher hay que envolver con el SDK, porque no hay sitio donde enganchar callbacks.

Estás aquí: OBSERVE, día 2

El artículo anterior sacó una fórmula sobre un grafo de juguete: 4 + 5n observaciones por turno, con el volumen en bytes creciendo con el cuadrado de los pasos. Una fórmula sobre un juguete sirve para entender el mecanismo y no sirve para dimensionar nada.

Este artículo la aplica a dos agentes reales, elegidos porque son conocidos y porque se rompen de maneras distintas. La serie pasa a diez artículos y el de migración se corre un puesto.

La analogía: dos fábricas, una auditoría

Una auditoría de trazabilidad en una fábrica con todo el proceso en cadenas propias es tediosa pero completa: cada puesto deja parte, y el auditor reconstruye la pieza de principio a fin. El volumen de papel es enorme y ese es el único problema.

La segunda fábrica subcontrata la mitad del proceso. El auditor ve entrar el material en una nave y salir el producto terminado, con horas y cantidades, y de lo que pasa dentro no tiene nada. El papel es poco. El problema tampoco es el papel.

Open Deep Research es la primera fábrica y el problema es de volumen. GPT Researcher, en su modo estándar, es la segunda, y el problema es que la traza no recoge lo que hace falta saber. Las dos se arreglan, pero con herramientas distintas, y confundirlas lleva a comprar disco cuando lo que falta es instrumentación.

Los dos agentes, y por qué estos

Open Deep Research (langchain-ai/open_deep_research, 12,7 k estrellas) es el agente de investigación de referencia de LangChain. Todo su trabajo pasa por LangChain, así que la instrumentación por callbacks lo ve entero.

GPT Researcher (assafelovic/gpt-researcher, 28,4 k estrellas) es el agente de investigación open source más conocido y no es de LangChain. Su modo multiagente usa LangGraph; su modo estándar, que es el que corren la API y la interfaz web, no.

Uno es de la casa y el otro no, que para una comparación es lo que importa.

Open Deep Research: la forma del grafo

Tres grafos, dos de ellos anidados como subgrafos (src/open_deep_research/deep_researcher.py):

El grafo raíz, deep_researcher (línea 701), con cuatro nodos: clarify_with_user, write_research_brief, research_supervisor y final_report_generation.
El subgrafo del supervisor (línea 353), con supervisor y supervisor_tools, que iteran entre sí.
El subgrafo del investigador (línea 589), con researcher, researcher_tools y compress_research, que es un bucle react clásico.

La multiplicación está en supervisor_tools. Cuando el supervisor decide delegar, ese nodo lanza un subgrafo de investigador por cada unidad y los espera juntos (línea 305):

research_tasks = [
 researcher_subgraph.ainvoke({
 "researcher_messages": [HumanMessage(content=tool_call["args"]["research_topic"])],
 "research_topic": tool_call["args"]["research_topic"]
 }, config)
 for tool_call in allowed_conduct_research_calls
]

tool_results = await asyncio.gather(*research_tasks)

El detalle que decide si la traza sale entera es ese config del final: el nodo recibe la configuración de LangGraph y la reenvía a los subgrafos, así que los callbacks viajan y cada investigador cuelga del sitio correcto.

Los tres topes de la configuración por defecto (src/open_deep_research/configuration.py) son max_concurrent_research_units = 5, max_researcher_iterations = 6 y max_react_tool_calls = 10. Se multiplican entre sí.

Lo que cuesta una petición, medido

Repliqué esa topología con modelos falsos, la misma técnica del artículo anterior: tres grafos, el mismo anidamiento, el mismo abanico con asyncio.gather, resultados de búsqueda de trescientos caracteres y respuestas de modelo de doscientos. Sin red y sin GPU, así que reproduce en cualquier sitio.

Unidades	Iteraciones	Llamadas react	Observaciones	generation	chain	KB de atributos	Mayor observación
1	1	1	26	8	18	56,8 KB	3,7 KB
2	2	3	92	26	66	257,3 KB	4,6 KB
5	6	10	1.416	370	1.046	8.108 KB	11,0 KB

La última fila es la configuración por defecto del repositorio. Una petición de investigación, una persona pulsando un botón una vez, deja 1.416 observaciones y ocho megabytes en el backend de observabilidad. En una sola traza, con un solo identificador.

Esos ocho megabytes son un suelo, no un techo. En el banco, cada resultado de búsqueda ocupa trescientos caracteres; un resultado real de Tavily con el contenido de la página ocupa entre diez y cien veces más, y ese texto entra en el historial y se reserializa en cada observación posterior del mismo investigador, que es el crecimiento cuadrático del artículo anterior actuando sobre un texto mucho mayor.

Puesto en cuentas de capacidad: cien peticiones de investigación al día, que para un equipo pequeño no es nada, son 141.600 observaciones y del orden de un gigabyte diario sin comprimir, con búsquedas de juguete. Con búsquedas reales, decenas de gigabytes. Es otro orden de magnitud respecto a un asistente de chat, y es la razón por la que este artículo va antes que el de capacidad.

Cero observaciones de tipo AGENT

En las 1.416 observaciones no hay ni una de tipo AGENT. El artículo anterior explicaba por qué: el handler decide ese tipo buscando la cadena agent en la ruta de la clase o en el nombre del run. Los nueve nodos de Open Deep Research son clarify_with_user, write_research_brief, research_supervisor, final_report_generation, supervisor, supervisor_tools, researcher, researcher_tools y compress_research.

Son nombres buenos. Describen lo que hace cada nodo y no incluyen una palabra que no aporta nada al que lee el código. El resultado es que el agente de investigación de referencia de LangChain, visto desde Langfuse, es un árbol de cadenas.

Se arregla desde fuera, sin tocar el repositorio, poniendo nombre a la invocación del subgrafo o renombrando los dos nodos que representan una decisión del modelo, que son supervisor y researcher. Sin eso, cualquier panel que agrupe por tipo de observación no va a distinguir el trabajo de decisión del trabajo de fontanería.

Instrumentarlo sin tocar el repositorio

Open Deep Research se publica como grafo de LangGraph Server, con su langgraph.json apuntando a deep_researcher. Hay dos formas de meterle el handler según cómo lo ejecutes.

Si lo invocas desde tu propio código, el grafo compilado es importable y basta el config:

from langfuse import Langfuse, propagate_attributes
from langfuse.langchain import CallbackHandler
from open_deep_research.deep_researcher import deep_researcher

trace_id = Langfuse.create_trace_id(seed=f"{peticion_id}")
handler = CallbackHandler(trace_context={"trace_id": trace_id})

with propagate_attributes(
 trace_name="deep-research",
 user_id=usuario,
 session_id=peticion_id,
 tags=["odr", "investigacion"],
):
 resultado = await deep_researcher.ainvoke(
 {"messages": [HumanMessage(pregunta)]},
 config={
 "callbacks": [handler],
 "configurable": {
 "thread_id": peticion_id,
 "max_concurrent_research_units": 3,
 "max_researcher_iterations": 4,
 },
 },
 )

Bajar esos dos topes de 5 y 6 a 3 y 4 no es una recomendación de observabilidad, es una decisión de producto que además divide el volumen de trazas por tres. Mejor tomarla a la vez.

Si lo despliegas en LangGraph Server, no hay invocación tuya donde meter el config, así que el handler se ata al compilar. El patrón es envolver el grafo exportado:

# grafo_instrumentado.py, y en langgraph.json apuntar aqui
from langfuse.langchain import CallbackHandler
from open_deep_research.deep_researcher import deep_researcher

graph = deep_researcher.with_config({"callbacks": [CallbackHandler()]})

Con esa vía se pierde el identificador de traza sembrado por petición, porque el handler se crea una vez. Si el agente usa interrupciones, esa pérdida importa, por lo que vimos en el artículo anterior.

GPT Researcher: dos productos en el mismo repositorio

Aquí está lo interesante, y es una trampa en la que se cae con cualquier agente que haya crecido por capas.

El repositorio tiene el paquete gpt_researcher, que es el motor, y el paquete multi_agents, que es una orquestación encima. Solo el segundo usa LangGraph.

El orquestador (multi_agents/agents/orchestrator.py:66) tiene ocho nodos: browser, planner, human, researcher, writer, fact_checker, visualizer y publisher, con dos bucles condicionales, uno de revisión humana del plan y otro de verificación de hechos. El nodo researcher lanza en paralelo un subgrafo de editor por sección (multi_agents/agents/editor.py:134), y ese subgrafo tiene su propio bucle de revisión entre reviewer y reviser.

Todo eso se traza como cualquier grafo. Y los modelos se llaman con self.llm.ainvoke(messages, **kwargs) desde el proveedor genérico (gpt_researcher/llm_provider/generic/base.py:365), que es un modelo de chat de LangChain sin config explícito, de modo que recoge la configuración ambiente mientras se ejecuta dentro de un nodo. Las generaciones aparecen.

El modo estándar es otra cosa. La clase GPTResearcher no tiene grafo, no tiene nodos y no pasa por LangGraph en ningún punto. Es el modo que usan la API y la interfaz web, o sea el que la mayoría ejecuta.

El mito del config nuevo

Antes de seguir hay que desmontar algo que parece un fallo y no lo es, porque se repite en muchos agentes.

Cuando el nodo researcher lanza los subgrafos de sección, lo hace así (multi_agents/agents/editor.py:74):

final_drafts = [
 chain.ainvoke(self._create_task_input(research_state, query, title),
 config={"tags": ["gpt-researcher"]})
 for query in queries
]
research_results = [result["draft"] for result in await asyncio.gather(*final_drafts)]

Ese config es nuevo y solo lleva etiquetas. El método ni siquiera recibe la configuración del nodo, así que no podría reenviarla. La conclusión intuitiva es que los subgrafos pierden los callbacks y cada sección acaba en su propia traza.

No pasa. Monté los dos patrones lado a lado, el de Open Deep Research que reenvía el config y el de GPT Researcher que pasa uno nuevo, y los dos dan una sola traza con un solo span raíz. El motivo es que LangChain no toma el config que le pasas tal cual: parte de la configuración ambiente guardada en una variable de contexto y le superpone las claves que traes. Los callbacks siguen ahí, y las variables de contexto se copian a las tareas que crea asyncio.gather.

Lo que sí se pierde son las etiquetas del padre, que quedan sustituidas por la lista nueva. Es una molestia de filtrado, no una traza rota.

El modo estándar: ocho llamadas, ocho trazas

Sin grafo no hay run raíz, y sin run raíz cada llamada al modelo es su propio árbol. Medido con ocho llamadas sueltas a un modelo de chat con el handler pasado a mano en cada una:


Observaciones	8
Trazas distintas	8
Spans raíz	8
Tipos	8 generation

Ocho trazas de una observación cada una, sin relación entre ellas. Ninguna sabe que pertenece a la misma investigación. Y eso en el caso favorable, porque el modo estándar no ofrece ningún sitio público donde poner ese handler: los **kwargs llegan hasta ainvoke desde create_chat_completion (gpt_researcher/utils/llm.py:120), pero el camino atraviesa varias capas internas que no están pensadas como punto de extensión.

La vía que funciona sin parchear el repositorio es envolver por fuera con el SDK y dejar que las llamadas de dentro cuelguen de ahí:

from langfuse import get_client, observe, propagate_attributes
from gpt_researcher import GPTResearcher

@observe(name="gpt-researcher", as_type="agent")
async def investigar(pregunta: str, peticion_id: str, usuario: str) -> str:
 with propagate_attributes(user_id=usuario, session_id=peticion_id, tags=["gptr"]):
 researcher = GPTResearcher(query=pregunta, report_type="research_report")
 await researcher.conduct_research()
 informe = await researcher.write_report()

 cliente = get_client()
 cliente.update_current_span(
 output={"longitud": len(informe), "fuentes": len(researcher.get_source_urls())},
 metadata={"costes_gptr": researcher.get_costs()},
 )
 return informe

Con eso hay una traza por investigación, con una observación de tipo agent en la raíz y las generaciones colgando dentro, en el mismo árbol. No aparecen las búsquedas ni el troceado de documentos, porque eso no pasa por LangChain. Si hacen falta, se añaden con start_as_current_observation(as_type="tool") alrededor de las llamadas propias, que es la primera de las tres salidas del filtro de spans que describía el artículo anterior.

Hay que fijarse en researcher.get_costs(). GPT Researcher lleva su propia contabilidad de coste, y meterla como metadato es lo único que permite cuadrarla después con lo que calcula Langfuse. Cuando las dos cifras no coinciden, casi siempre es el alias del modelo del gateway.

El nodo humano que se queda abierto

El modo multiagente tiene un nodo human que pide opinión sobre el plan antes de investigar. No usa interrupt() de LangGraph. Espera dentro del nodo, leyendo del websocket (multi_agents/agents/human.py).

Las dos formas tienen consecuencias opuestas en la traza. Con interrupt(), el grafo devuelve el control y la traza se parte en dos, que es lo que medía el artículo anterior. Esperando dentro del nodo, la traza es una sola pero la observación de ese nodo queda abierta todo el tiempo que tarde la persona, minutos u horas.

Ninguna de las dos está mal. Lo que está mal es el panel que promedia duraciones sin saber cuál de las dos tiene delante. Con la espera dentro del nodo, el percentil 95 de duración del grafo mide cuánto tarda un humano en contestar un mensaje, no lo que tarda el agente. Si se alerta sobre esa métrica, la alerta salta a la hora de comer.

La regla práctica es excluir por nombre los nodos de espera humana de cualquier métrica de latencia, y medir esa espera aparte, que además suele ser una métrica de producto interesante por sí sola.

Qué mirar en la traza cuando llega

Con los dos agentes instrumentados, y antes de montar ningún panel, hay cuatro comprobaciones que se hacen una vez y ahorran semanas:

Cuenta las observaciones de una petición típica. Si salen más de mil, el problema de esta plataforma va a ser de volumen y toca decidir muestreo antes que nada.
Mira si hay más de un span raíz. Más de uno significa que hay trabajo que se está trazando fuera del árbol, y hay que saber cuál antes de que sean miles.
Comprueba que las generaciones traen coste. Si vienen a cero, es el alias del modelo, y se arregla dando de alta ese nombre con su precio.
Ordena las observaciones por duración y quita las que esperan a una persona. Lo que queda arriba es donde está el tiempo de verdad.

Checklist

El grafo se invoca con un identificador de traza sembrado por petición, no con uno aleatorio.
Los topes de concurrencia e iteraciones del agente están fijados a conciencia, sabiendo que multiplican el volumen de trazas.
Los nodos que representan una decisión del modelo llevan agent en el nombre, o se ha asumido por escrito que no habrá observaciones de ese tipo.
El trabajo que no pasa por LangChain está envuelto con el SDK, o se ha decidido que no hace falta verlo.
Los nodos de espera humana están identificados y excluidos de las métricas de latencia.
La contabilidad de coste propia del agente, si la tiene, entra como metadato para poder cuadrarla.
Hay una cifra medida de observaciones por petición, tomada de la instalación propia y no de este artículo.

Trampas

Los valores por defecto de un agente de investigación son de demostración, no de producción. Cinco unidades por seis iteraciones por diez llamadas react multiplican, y el que los eligió pensaba en la calidad del informe, no en tu ClickHouse.

Un repositorio puede tener dos agentes dentro con dos historias de instrumentación distintas. Instrumentar el modo que documenta el README y no el que ejecuta la API es un error que no da ningún síntoma: las trazas llegan, solo que de otra cosa.

Pasar un config nuevo a un subgrafo no rompe la traza. Rompe las etiquetas. El árbol se mantiene porque los callbacks viajan por variable de contexto.

Un nodo que espera a una persona contamina cualquier estadística de duración. Y no lo hace de forma evidente, porque el nodo termina bien y no marca error.

Buenos nombres de nodo y buena clasificación de observaciones son objetivos en conflicto. Gana el que escribe el código del agente, que normalmente no eres tú.

Ocho megabytes por petición con búsquedas de trescientos caracteres. Con resultados reales, el número que salga de tu instalación no se parecerá al de este artículo, y será mayor.

La serie: los diez artículos

Qué entra en una traza: modelo de datos de la versión 4, límites, precedencias, scores, enmascarado e índices.
Poner LangGraph delante: la instrumentación de una plataforma agéntica y el coste medido de un turno.
Dos agentes conocidos instrumentados (este artículo): Open Deep Research y GPT Researcher, con las cifras medidas de una petición real.
Migrar de la versión 3 a la 4 sin ventana: los tres pasos del modo de escritura, las migraciones de fondo reanudables y dónde está el punto de no retorno del retroceso.
Las colas del worker: el mapa de las treinta y nueve, qué pool dedicar a cada grupo, los interruptores por cola, el particionado y la concurrencia.
Capacidad y coste real de ClickHouse: cómo medir los bytes por observación con las tablas del sistema, la diferencia entre la tabla completa y la de listados, y el coste de fusión de los índices de texto completo.
Retención, borrado y protección de datos: por qué un borrado no libera disco, el limpiador de máscaras que viene desactivado, la cola de borrados pendientes y el ciclo de vida de S3 que hay que implementar a mano.
Copias de seguridad y recuperación cruzada: orden de restauración entre Postgres, ClickHouse y el almacenamiento de objetos, qué rompe cada desajuste, y hasta dónde llega la reproducción de eventos.
Runbook de saturación: qué alertar de las métricas de cola, las sondas de atasco, el drenado por el endpoint de preparación y la cola de mensajes fallidos.
Sacar los datos fuera: la integración de almacenamiento de objetos a Parquet, las exportaciones por lotes y la API de métricas, para montar el lago de datos.

Ver también

Poner LangGraph delante: la fórmula y el crecimiento cuadrático que aquí se aplican a dos agentes reales.
Langfuse v4: qué entra de verdad en una traza: el modelo de datos que explica el coste del volumen.
Dimensionar el gateway para una flota de agentes: el mismo problema visto desde el gateway.
FinOps y multi-tenencia de GPU con LiteLLM: por qué el coste sale a cero con un alias del gateway.
Ejecución duradera y coste de los agentes: qué pasa cuando el agente sobrevive al proceso.
Aislar agentes de IA por cliente: el aislamiento de un agente que navega y descarga.

Fuentes

Código de Open Deep Research, commit 1b7d2e8, leído el 14 de septiembre de 2026: src/open_deep_research/deep_researcher.py y configuration.py.
Código de GPT Researcher, commit 6f99857, leído el 14 de septiembre de 2026: multi_agents/agents/orchestrator.py, multi_agents/agents/editor.py, multi_agents/agents/human.py, gpt_researcher/llm_provider/generic/base.py y gpt_researcher/utils/llm.py.
Medición propia del 14 de septiembre de 2026 sobre réplicas de las dos topologías, con LangGraph 1.2.11, langchain-core 1.6.3, SDK de Langfuse 4.15.2, InMemorySpanExporter y modelos falsos, sin red.
Estrellas de GitHub de los dos repositorios, consultadas el 14 de septiembre de 2026.

Langfuse v4, día 2 (2 de 10): poner LangGraph delante, y lo que cuesta un turno de agente en observaciones

Sun, 13 Sep 2026 07:00:00 +0200

Segundo artículo de una serie de diez sobre operar Langfuse v4 en producción. El primero, qué entra de verdad en una traza, recorría el modelo de datos leyendo el código del servidor. Este mide el otro lado. Verificado contra Langfuse 4.15.2 (SDK de Python), LangGraph 1.2.11 y langchain-core 1.6.3, con las cifras tomadas el 13 de septiembre de 2026 en un banco de pruebas sin red.

TL;DR

Un turno de agente son cuatro observaciones más cinco por cada llamada a herramienta. Medido con un exportador en memoria sobre un grafo ReAct mínimo: cero herramientas, 4 observaciones; una, 9; cinco, 29; diez, 54; cuarenta, 204. La fórmula se cumple exactamente en todo el rango.

El volumen en bytes crece de forma cuadrática, no lineal. El mismo turno pasa de 12,2 KB con una llamada a herramienta a 1,87 MB con cuarenta. El 88 % de esos bytes es el campo de entrada, porque cada observación reserializa el historial de mensajes completo tal y como está en ese momento.

Las definiciones de herramientas viajan pegadas a cada llamada al modelo. El handler las añade al campo de entrada como mensajes con rol tool. Medido: 364 bytes por herramienta. Con veinte herramientas son 7,3 KB en cada uno de los pasos del bucle.

El tipo de observación AGENT se asigna por coincidencia de cadena en el nombre. Un nodo llamado planificador sale como CHAIN; el mismo nodo llamado agente_planificador sale como AGENT. La lógica es literalmente buscar agent en la ruta de la clase o en el nombre del nodo (langfuse/langchain/CallbackHandler.py:397).

Una interrupción con reanudación produce dos trazas separadas. Verificado con invoke, con stream y con subgrafos, y también reutilizando el mismo objeto handler. El SDK trae maquinaria para reenganchar la traza, pero solo se dispara si el run raíz termina con una excepción de control de flujo, y en LangGraph 1.2.11 la interrupción vuelve por el valor de retorno.

El arreglo cabe en una línea y está medido. Pasar trace_context={"trace_id": Langfuse.create_trace_id(seed=thread_id)} al construir el handler deja la interrupción y la reanudación en la misma traza, incluso con handlers distintos y, por tanto, con réplicas distintas.

El procesador de spans descarta por defecto lo que no reconoce. Solo exporta spans del propio SDK, spans con algún atributo gen_ai.*, o spans de una lista cerrada de treinta y cinco prefijos de instrumentación (langfuse/_client/span_filter.py:11). Las trazas de tu propio código no llegan salvo que entren por una de esas tres puertas.

Estás aquí: OBSERVE, día 2

La serie se planteó con ocho artículos y ha crecido a diez. El motivo es de orden: los dos siguientes hablan de migrar y de dimensionar ClickHouse, y las dos cosas necesitan una cifra de entrada que nadie publica, que es cuántas observaciones y cuántos bytes produce una unidad de trabajo real. Un chat produce una traza con dos observaciones. Un agente produce doscientas. Dimensionar con la cifra del chat lleva a un cluster que se cae el día que alguien conecta el agente.

Así que antes de migrar, medir. Y para medir hace falta poner delante lo que la gente despliega.

La analogía: el expediente que se fotocopia entero en cada firma

Un expediente de contratación pasa por seis mesas. En cada mesa alguien lee lo que hay, añade una hoja y lo pasa a la siguiente.

Hay dos maneras de dejar rastro de ese recorrido. La primera es anotar en un registro qué mesa lo tocó, cuándo y qué hoja añadió. Seis anotaciones cortas. La segunda es fotocopiar el expediente completo al entrar en cada mesa y al salir, y archivar las doce fotocopias. El registro ocupa una hoja. Las fotocopias ocupan, en la sexta mesa, seis veces lo que ocupaban en la primera, y en total ocupan del orden del cuadrado del número de mesas.

La instrumentación por callbacks de LangChain hace lo segundo. No registra el delta de cada paso, registra el estado completo a la entrada y a la salida de cada paso. Con un chat eso da igual, porque el estado es corto y hay un paso. Con un agente de cuarenta pasos, el archivo pesa casi dos megabytes por expediente tramitado.

Esto no es un defecto que haya que arreglar. Es lo que permite abrir una traza y ver exactamente qué vio el modelo en el paso 17 sin reconstruir nada. Pero condiciona el dimensionado, y el número hay que saberlo antes de firmar el pliego.

Cuál es la plataforma agéntica más usada

La pregunta tiene dos respuestas según la métrica, y las dos son defendibles.

Por descargas de PyPI en los últimos treinta días, consultadas el 13 de septiembre de 2026:

Paquete	Descargas / 30 días
`langgraph`	52,3 M
`strands-agents`	35,2 M
`openai-agents`	22,9 M
`crewai`	19,1 M
`google-adk`	14,5 M
`pydantic-ai`	8,0 M
`llama-index`	5,0 M
`agno`	1,9 M
`autogen-agentchat`	0,6 M

Por estrellas de GitHub el orden se invierte en cabeza: CrewAI va por 58,4 k, LangGraph por 38,1 k y el SDK de agentes de OpenAI por 28,6 k.

Las descargas de PyPI están infladas por integración continua y por imágenes que reinstalan en cada build, así que son un indicador de presencia en pipelines, no de agentes en producción. Las estrellas miden interés, no despliegue. Con las dos cosas a la vez, LangGraph es la que aparece en más pipelines y la que tiene el camino de instrumentación más trabajado en Langfuse, así que es la que se instrumenta aquí. Lo que sigue sobre volumen aplica igual a cualquier plataforma que instrumente por callbacks de LangChain, porque el coste viene del modelo de callbacks, no del grafo.

Cómo entra LangGraph en Langfuse

Conviene aclarar la ruta, porque el artículo anterior dejaba dos vías abiertas y aquí solo se usa una.

langchain-core 1.6.3 no importa OpenTelemetry en ningún sitio. La comprobación es directa sobre el wheel instalado y no devuelve ni un fichero. LangGraph tampoco emite spans OTLP por su cuenta. Lo que hay es el sistema de callbacks de LangChain, y el CallbackHandler de Langfuse se engancha ahí.

Ese handler no habla con la API de ingesta clásica. Crea observaciones con el SDK v4, que por dentro es OpenTelemetry: el LangfuseSpanProcessor monta un OTLPSpanExporter contra {base_url}/api/public/otel/v1/traces (langfuse/_client/span_processor.py:123). O sea que sí es OTLP, pero generado por el SDK, no por una instrumentación automática de terceros.

La diferencia importa por una razón concreta que quedó pendiente en el artículo anterior. Como los datos pasan por las llamadas del SDK, la función de enmascarado clásica sí se aplica: entrada, salida y metadatos pasan por _process_media_and_apply_mask antes de convertirse en atributos (langfuse/_client/span.py:534). Con una instrumentación automática del tipo OpenInference u OpenLLMetry, los mensajes viajan en eventos de span y el enmascarado no los toca. Para un agente que maneja datos de cliente en las herramientas, esa diferencia decide la ruta.

La contrapartida es que un handler de callbacks solo ve lo que pasa por LangChain. Las llamadas HTTP que haga una herramienta por su cuenta, la consulta a la base de datos, el subprocess, nada de eso aparece. Y si instrumentas tu código con OpenTelemetry para que aparezca, te topas con el filtro del que habla el apartado de más abajo.

El tipo de observación se decide por el nombre del nodo

El primer artículo insistía en que v4 tiene diez tipos de observación y en que usar el correcto cambia lo que la interfaz sabe agrupar. El handler de LangChain emite seis de esos diez: tool, retriever, generation, agent, chain y span. Nunca emite event, embedding, evaluator ni guardrail.

La asignación es directa para cuatro de ellos: callback de herramienta, tipo tool; callback de recuperador, tipo retriever; callback de modelo, tipo generation. Para los callbacks de cadena, que es lo que son todos los nodos de un grafo de LangGraph, el criterio es este (langfuse/langchain/CallbackHandler.py:393):

elif callback_type == "chain":
 # Detect if it's an agent by examining class path or name
 if serialized and "id" in serialized:
 class_path = serialized["id"]
 if any("agent" in part.lower() for part in class_path):
 return "agent"

 name = self.get_langchain_run_name(serialized, **kwargs)
 if "agent" in name.lower():
 return "agent"

 return "chain"

Medido sobre el mismo grafo con el nodo renombrado, y con el resto idéntico:

Nombre del nodo	Llamadas a herramienta	Observaciones	Tipos
`planificador`	10	54	11 generation, 33 chain, 10 tool
`agente_planificador`	10	54	11 generation, 22 chain, 11 agent, 10 tool

Once observaciones cambian de tipo por once caracteres en el nombre de una función. Esto tiene dos consecuencias prácticas. La primera es que cualquier cuadro de mando que cuente observaciones de tipo AGENT está contando convenciones de nombres. La segunda es que el grafo de agente de la interfaz se dibuja cuando la traza contiene alguna observación de tipo distinto de span, event o generation, y chain cuenta, así que el dibujo sale igual. Lo que cambia es lo que puedes filtrar y agregar después.

La recomendación operativa es aburrida y funciona: nombrar los nodos que representan una decisión del modelo con un nombre que contenga agent, y dejar el resto como cadenas. Es una convención de nombres elevada a esquema de datos, que no es bonito, pero es lo que hay y es estable.

Lo que cuesta un turno, medido

El montaje es un grafo ReAct mínimo: un nodo que llama al modelo, un ToolNode con una herramienta, una arista condicional con tools_condition y un checkpointer en memoria. El modelo es GenericFakeChatModel de langchain-core, que devuelve una lista fija de mensajes, así que no hace falta ni red ni GPU y el experimento es reproducible en cualquier portátil. El exportador es InMemorySpanExporter de OpenTelemetry, pasado al cliente por el parámetro span_exporter, de modo que las observaciones se cuentan sin servidor Langfuse delante.

Resultado, con el nodo llamado planificador:

Llamadas a herramienta	Observaciones	generation	chain	tool	Bytes de atributos
0	4	1	3	0	4,2 KB
1	9	2	6	1	12,2 KB
5	29	6	18	5	64,1 KB
10	54	11	33	10	173,5 KB
20	104	21	63	20	541,4 KB
30	154	31	93	30	1.108 KB
40	204	41	123	40	1.874 KB

La cuenta de observaciones es exactamente 4 + 5n. Las cinco por vuelta del bucle son: el nodo del modelo, la llamada al modelo, la arista condicional, el nodo de herramientas y la herramienta. Las cuatro fijas son el grafo raíz, la primera vuelta parcial y el cierre.

Los bytes no siguen esa línea. De 10 a 20 pasos el volumen se multiplica por 3,1; de 20 a 40, por 3,5. Es el crecimiento cuadrático que se espera cuando cada uno de los n pasos arrastra un historial de longitud proporcional a n.

El desglose por campo lo confirma. Con cuarenta pasos, de 1.709 KB medidos en esa ejecución, 1.502 KB están en langfuse.observation.input y solo 56 KB en la salida. El 88 % de lo que se ingiere es el mismo historial repetido en distinto grado de avance. La observación individual más grande de ese turno son 22,2 KB, que está lejos del tope de 9,5 MB por span OTLP, así que el problema no es el límite de tamaño: es el agregado.

Y dentro de la entrada hay un segundo multiplicador. El handler añade la definición de cada herramienta al campo de entrada de la generación, como mensajes con rol tool (langfuse/langchain/CallbackHandler.py:1190). Medido con herramientas de tres parámetros y una descripción de una línea:

Herramientas enlazadas	Bytes del campo de entrada de una generación
0	34
1	398
5	1.854
10	3.674
20	7.334

Son 364 bytes por herramienta, en cada generación, siempre. Un agente con veinte herramientas y cuarenta pasos ingiere 7,3 KB × 41 generaciones = 300 KB solo en esquemas de herramientas que no cambian nunca a lo largo del turno.

Qué significa esto para ClickHouse

Aquí toca un descargo honesto. Comprimí el payload completo de esas ejecuciones con ZSTD nivel 3, que es lo que usa events_full, y salieron ratios de entre 29× y 86×, mejorando cuanto más largo el turno. Ese número está inflado por lo sintético del banco: mi herramienta devuelve siempre la misma cadena, así que la redundancia es mayor que en producción.

Lo que sí se sostiene es la forma. La repetición del historial es exactamente el patrón que la compresión columnar absorbe bien, así que el disco de ClickHouse no es donde duele. Donde duele es antes: en el ancho de banda hacia el endpoint OTLP, en la CPU del worker que descomprime y aplana, y en la cola de ingesta, que ven los bytes sin comprimir. El primer artículo dejaba anotado que la cola que satura primero es langfuse.queue.ingestion.depth, y esta es la razón por la que satura.

Cuenta rápida para dimensionar, con las cifras medidas y un turno medio de diez pasos:

1.000 turnos al día son 54.000 observaciones y unos 170 MB sin comprimir al día.
10.000 turnos al día son 540.000 observaciones y 1,7 GB sin comprimir al día.
Si el turno medio sube de diez a veinte pasos, las observaciones se duplican y los bytes se triplican.

La sensibilidad al número de pasos es el parámetro que hay que vigilar, más que el número de usuarios. Un cambio de prompt que haga al agente dar tres vueltas más multiplica la factura de observabilidad sin que nadie haya tocado la infraestructura. El artículo 6 de la serie vuelve sobre esto con las tablas de sistema de ClickHouse para medir los bytes reales por observación en tu propia instalación, que es lo único que sustituye a esta estimación.

Interrupciones: dos trazas donde debería haber una

Un agente en producción con aprobación humana usa interrupt(), devuelve el control, espera a una persona y reanuda con Command(resume=...). La pregunta operativa es si la traza sobrevive a esa pausa.

El SDK trae maquinaria explícita para el caso. Hay un almacén de contextos de traza pendientes indexado por thread_id, con un tope de 1.024 entradas y desalojo del más antiguo (MAX_PENDING_RESUME_TRACE_CONTEXTS), y una función que reconoce un Command con resume y recupera el contexto guardado.

Medido, no funciona en esta combinación de versiones:

Caso	¿Misma traza?
Mismo objeto handler, `invoke`	No
Mismo objeto handler, `stream`	No
Interrupción dentro de un subgrafo	No
Handler nuevo para la reanudación	No

El motivo está en el código y es consistente. El contexto pendiente solo se guarda desde on_chain_error cuando el run que falla es el raíz y el nivel resultante es DEFAULT, que es lo que ocurre con las excepciones de control de flujo de LangGraph (CallbackHandler.py:866). En LangGraph 1.2.11 la interrupción no sale por excepción desde la raíz: el grafo devuelve normalmente, con la interrupción en el valor de retorno. El run raíz termina por on_chain_end y la rama que guarda el contexto nunca se ejecuta. La observación del nodo interrumpido sí queda bien: nivel DEFAULT y el Interrupt en el mensaje de estado, no marcado como error, que es el comportamiento correcto.

El arreglo está verificado y no depende de que el SDK cambie:

from langfuse import Langfuse
from langfuse.langchain import CallbackHandler

trace_id = Langfuse.create_trace_id(seed=thread_id)
handler = CallbackHandler(trace_context={"trace_id": trace_id})

Con eso, la interrupción y la reanudación caen en la misma traza aunque el handler sea otro objeto y aunque la reanudación la atienda otra réplica, porque el identificador se deriva del thread_id y no de un estado en memoria. Es la misma técnica que la documentación recomienda para unir varios agentes en una traza, aplicada a unir un agente consigo mismo.

Con un matiz que hay que decidir a conciencia. Sembrar con el thread_id a secas mete todos los turnos de esa conversación en una sola traza, que crece sin límite mientras la conversación siga viva. Si lo que quieres es una traza por turno con la reanudación pegada al turno correcto, siembra con thread_id más el número de turno, y deja la agrupación de la conversación al identificador de sesión, que para eso está. Como en v4 no hay tabla de trazas, una traza enorme no es una fila enorme: es un filtro que devuelve muchas filas, y lo que sufre es la interfaz al abrirla.

Hilo, sesión, usuario y lo que solo se lee en la raíz

El handler reconoce cinco claves de metadatos: langfuse_session_id, langfuse_user_id, langfuse_trace_name, langfuse_tags y langfuse_prompt. Las cuatro primeras se leen solo cuando parent_run_id es None, es decir, únicamente en el run raíz (CallbackHandler.py:587). Ponerlas en la configuración con la que invocas un subgrafo no hace nada.

La vía recomendada y la que funciona sin sorpresas es el gestor de contexto:

from langfuse import propagate_attributes

with propagate_attributes(
 trace_name="turno-agente",
 user_id=usuario,
 session_id=thread_id,
 tags=["produccion", "soporte-n1"],
):
 grafo.invoke(entrada, config=cfg)

Lo que LangGraph aporta por su cuenta llega igualmente. En la ejecución medida aparecen como metadatos de observación langgraph_node, langgraph_step, langgraph_triggers, langgraph_path, langgraph_checkpoint_ns, checkpoint_ns y thread_id, más ls_provider, ls_model_type y ls_integration. El thread_id sube además a metadato de traza.

Eso está bien, pero recordando lo del primer artículo: en events_core lo que está indexado es metadata_names, o sea los nombres de las claves, no los valores. Filtrar por langgraph_node = "planificador" es escaneo. Si vas a segmentar por nodo de forma habitual, el sitio correcto es el nombre de la observación, que es donde el nodo ya aparece, o una etiqueta, asumiendo que las etiquetas tampoco están indexadas. El campo barato para cortar por nodo en v4 es el propio nombre de la observación.

El identificador de sesión merece una decisión explícita. thread_id de LangGraph y session_id de Langfuse son el mismo concepto y no se conectan solos. Mapearlos uno a uno es lo razonable, y además es lo que hace que la conversación entera sea navegable en la interfaz aunque cada turno sea una traza distinta.

El filtro que tira tus propias trazas

Este es el hallazgo que más sorprende al montarlo. El procesador de spans de Langfuse no exporta todo lo que pasa por el TracerProvider. Exporta lo que cumple una de estas tres condiciones (langfuse/_client/span_filter.py:104):

Lo creó el tracer del propio SDK de Langfuse.
Tiene al menos un atributo que empieza por gen_ai.
Su ámbito de instrumentación coincide con uno de los treinta y cinco prefijos de una lista cerrada.

La lista incluye lo esperable y un poco más: openinference, litellm, haystack, langsmith, strands-agents, pydantic-ai, autogen-core, vllm y una veintena de instrumentaciones opentelemetry.instrumentation.*.

La consecuencia para un agente es directa. Si instrumentas tus herramientas con OpenTelemetry a mano para ver la llamada al ERP o la consulta a Postgres dentro de la traza del agente, esos spans se descartan en silencio, sin log y sin error. Hay tres salidas, por orden de limpieza:

Crear esas observaciones con el SDK de Langfuse, con start_as_current_observation(as_type="tool"), que es lo que el resto del artículo asume.
Poner algún atributo gen_ai.* en el span, lo cual es abusar de la convención para colar el span, así que solo si el span describe de hecho una interacción con un modelo.
Mandar esos spans a tu colector de OpenTelemetry normal y no a Langfuse, y correlacionar por identificador de traza. Para una plataforma soberana con un colector propio, esta es la opción sensata: Langfuse guarda la parte de modelo, el colector guarda la parte de sistema, y el identificador de traza las une.

Que el comportamiento sea silencioso es lo que hace que se tarde una tarde en encontrarlo. Merece estar en el runbook.

El modelo y el coste con el gateway en medio

Un detalle que afecta a cualquiera que ponga LiteLLM delante, que es el montaje del que hablan el par operativo y la multi-tenencia de GPU.

El nombre de modelo que el handler pone en la generación sale primero del metadato ls_model_name y, si no está, de la serialización del componente (CallbackHandler.py:1297). Con un ChatOpenAI apuntando al gateway, ese nombre es el alias que hayas definido en LiteLLM, por ejemplo qwen-32b-interno. Langfuse calcula el coste con su propia tabla de modelos, que no conoce ese alias, así que la generación llega con tokens y sin coste.

Se arregla definiendo el modelo en Langfuse con ese mismo nombre y su precio por millón de tokens, que además es la única manera de que el coste refleje lo que cuesta tu GPU y no lo que cuesta la API de otro. Es trabajo de una tarde y evita que el panel de coste de la plataforma agéntica esté a cero para siempre.

Cómo queda esto en código

Lo mínimo que hay que tener puesto para que un agente LangGraph produzca trazas útiles en Langfuse v4:

import os
from typing import Annotated, TypedDict

from langfuse import Langfuse, get_client, propagate_attributes
from langfuse.langchain import CallbackHandler
from langchain_core.messages import HumanMessage
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# 1. Cliente. El enmascarado se aplica porque los datos pasan por el SDK.
def mask(*, data, **kwargs):
 return redactar_pii(data)

Langfuse(
 public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
 secret_key=os.environ["LANGFUSE_SECRET_KEY"],
 host=os.environ["LANGFUSE_HOST"],
 mask=mask,
 environment="pro", # minusculas, guiones, 40 caracteres, no empezar por "langfuse"
 sample_rate=float(os.getenv("LANGFUSE_SAMPLE_RATE", "1.0")),
)

# 2. Grafo. El nodo de decision lleva "agent" en el nombre a proposito.
class Estado(TypedDict):
 messages: Annotated[list, add_messages]

grafo = StateGraph(Estado)
grafo.add_node("agente_planificador", nodo_modelo)
grafo.add_node("tools", ToolNode(HERRAMIENTAS))
grafo.add_edge(START, "agente_planificador")
grafo.add_conditional_edges("agente_planificador", tools_condition)
grafo.add_edge("tools", "agente_planificador")
app = grafo.compile(checkpointer=checkpointer)

# 3. Por turno: traza determinista sembrada con hilo y turno, sesion = hilo.
def ejecutar_turno(thread_id: str, turno: int, texto: str, usuario: str):
 trace_id = Langfuse.create_trace_id(seed=f"{thread_id}:{turno}")
 handler = CallbackHandler(trace_context={"trace_id": trace_id})
 cfg = {
 "callbacks": [handler],
 "configurable": {"thread_id": thread_id},
 }
 with propagate_attributes(
 trace_name="turno-agente",
 user_id=usuario,
 session_id=thread_id,
 tags=["agente", "soporte"],
 ):
 salida = app.invoke({"messages": [HumanMessage(texto)]}, config=cfg)
 return trace_id, salida

# 4. Reanudacion tras aprobacion humana: mismo seed, misma traza.
def reanudar_turno(thread_id: str, turno: int, decision):
 from langgraph.types import Command

 trace_id = Langfuse.create_trace_id(seed=f"{thread_id}:{turno}")
 handler = CallbackHandler(trace_context={"trace_id": trace_id})
 cfg = {"callbacks": [handler], "configurable": {"thread_id": thread_id}}
 return app.invoke(Command(resume=decision), config=cfg)

# 5. Puntuar el turno. Los scores no viajan por OTLP: van por su propia ruta.
get_client().create_score(
 trace_id=trace_id,
 name="resuelto",
 value=1,
 data_type="BOOLEAN",
)

Dos notas sobre lo que no está en el ejemplo. sample_rate es muestreo de cabecera y por traza, así que muestrea turnos completos, que es lo que se quiere: media traza de agente no sirve para nada. Y si el proceso es un servidor web, el cliente se construye una vez al arrancar, no por petición, mientras que el handler puede ser por turno sin problema, porque con el identificador sembrado ya no guarda estado que haga falta conservar.

Checklist de instrumentación de un agente

Los nodos que representan una decisión del modelo llevan agent en el nombre. El resto, no.
Cada turno tiene un identificador de traza determinista sembrado con hilo y número de turno.
El thread_id de LangGraph va como session_id de Langfuse, siempre.
Los atributos de traza se ponen con propagate_attributes, no como metadatos en un subgrafo.
El alias de modelo del gateway está dado de alta en la tabla de modelos de Langfuse, con precio.
Las herramientas que hacen trabajo fuera de LangChain se instrumentan con el SDK de Langfuse, no con OpenTelemetry a pelo.
Hay una alerta sobre la profundidad de la cola de ingesta, y se conoce el número de pasos medio por turno.
Se ha medido, en la propia instalación, cuántas observaciones y cuántos bytes produce un turno real. Las cifras de este artículo son de un banco sintético.
El muestreo está puesto por variable de entorno, para poder bajarlo sin desplegar código.

Trampas

El tipo AGENT no significa que haya un agente. Significa que alguien escribió agent en el nombre. Y al revés: un grafo entero sin esa cadena no produce ni una observación de tipo agente.

Poner langfuse_session_id en los metadatos de un subgrafo no hace nada. Solo se leen en el run raíz.

Una interrupción parte la traza en dos. Salvo que siembres el identificador. Y si trabajas con varias réplicas, el estado en memoria del handler no te va a salvar nunca, porque la reanudación puede caer en otro pod.

Tus spans de OpenTelemetry no llegan. El filtro por defecto los descarta sin avisar si el ámbito no está en la lista y no hay atributos gen_ai.*.

El número que hay que vigilar no es el de usuarios, es el de pasos por turno. El volumen crece con el cuadrado de los pasos, y los pasos los decide el prompt, no la infraestructura.

Guardas megabytes y la interfaz te enseña mil caracteres. El truncado de la vista materializada a doscientos caracteres y el tope de lectura de mil siguen ahí. Pagas la ingesta completa y ves un recorte, salvo que abras la observación concreta.

El coste sale a cero con el gateway delante. Alias de modelo desconocido para la tabla de precios.

flush_at por encima del tamaño de cola revienta al construir el cliente. Con un ValueError de OpenTelemetry que no menciona Langfuse por ningún lado.

La serie: los diez artículos

Qué entra en una traza: modelo de datos de la versión 4, límites, precedencias, scores, enmascarado e índices.
Poner LangGraph delante (este artículo): la instrumentación de una plataforma agéntica y el coste medido de un turno.
Dos agentes conocidos instrumentados: Open Deep Research y GPT Researcher, con las cifras medidas de una petición real.
Migrar de la versión 3 a la 4 sin ventana: los tres pasos del modo de escritura, las migraciones de fondo reanudables y dónde está el punto de no retorno del retroceso.
Las colas del worker: el mapa de las treinta y nueve, qué pool dedicar a cada grupo, los interruptores por cola, el particionado y la concurrencia.
Capacidad y coste real de ClickHouse: cómo medir los bytes por observación con las tablas del sistema, la diferencia entre la tabla completa y la de listados, y el coste de fusión de los índices de texto completo.
Retención, borrado y protección de datos: por qué un borrado no libera disco, el limpiador de máscaras que viene desactivado, la cola de borrados pendientes y el ciclo de vida de S3 que hay que implementar a mano.
Copias de seguridad y recuperación cruzada: orden de restauración entre Postgres, ClickHouse y el almacenamiento de objetos, qué rompe cada desajuste, y hasta dónde llega la reproducción de eventos.
Runbook de saturación: qué alertar de las métricas de cola, las sondas de atasco, el drenado por el endpoint de preparación y la cola de mensajes fallidos.
Sacar los datos fuera: la integración de almacenamiento de objetos a Parquet, las exportaciones por lotes y la API de métricas, para montar el lago de datos.

Ver también

Langfuse v4: qué entra de verdad en una traza: el modelo de datos que explica por qué el volumen importa tanto.
LiteLLM y Langfuse: el par operativo: las cuatro colas donde se pierde la traza entre el gateway y el backend.
El gateway no vive solo: por qué el usuario de la traza no es el de Keycloak.
Dimensionar el gateway para una flota de agentes: el otro lado del mismo problema de volumen.
Ejecución duradera y coste de los agentes: qué pasa cuando el agente sobrevive al proceso que lo lanzó.
Aislar agentes de IA por cliente: el aislamiento que hay debajo de todo esto.
Evals: la capa después del tracing: dónde encajan los scores de un turno de agente.

Fuentes

Medición propia del 13 de septiembre de 2026: LangGraph 1.2.11, langchain-core 1.6.3 y SDK de Python de Langfuse 4.15.2, con InMemorySpanExporter de OpenTelemetry y GenericFakeChatModel, sin red.
Código del SDK de Langfuse 4.15.2: langfuse/langchain/CallbackHandler.py, langfuse/_client/span_filter.py, langfuse/_client/span_processor.py, langfuse/_client/span.py.
Descargas de PyPI de los últimos treinta días vía pypistats, consultadas el 13 de septiembre de 2026.
Estrellas de GitHub de LangGraph, CrewAI y OpenAI Agents SDK, consultadas el 13 de septiembre de 2026.
Integración de Langfuse con LangGraph y grafos de agente, consultados el 13 de septiembre de 2026.