Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Rastrear y reanudar ejecuciones largas de agentes
Una ejecución larga (procesar 300 archivos, rastrear un repositorio, completar un plan) puede detenerse a mitad de camino: un fallo, una ventana de contexto llena, un despliegue, una pausa. Un bloque de memoria de trabajo identificado por el run_id de la ejecución guarda su progreso en ClickHouse, de modo que un proceso nuevo lo lee y continúa desde la última unidad de trabajo completada. No se necesita un almacén de checkpoints aparte.
El patrón
- Elige un
run_idestable para la tarea: un id de trabajo, un id de plan. - Después de cada unidad de trabajo, llama a
checkpoint(state, run_id=...).statees lo que un proceso nuevo necesita para continuar: ids de elementos completados, un cursor, una cadena JSON. - Al arrancar, llama a
resume(run_id=...).Nonesignifica una ejecución nueva; en caso contrario, omite lo que el checkpoint indica como hecho.
flowchart LR
A["start: resume(run_id)"] -->|None| B[fresh run]
A -->|state| C[skip completed items]
B --> D[do one unit]
C --> D
D --> E["checkpoint(state, run_id)"]
E -->|more work| D
E -->|finished| F["delete('checkpoint', run_id)"]
Con el SDK de Python
from loom import Agent
RUN = "reindex-catalog"
async def process(agent: Agent, items: list[str]) -> None:
done = set((await agent.working_memory.resume(run_id=RUN) or "").split())
for item in items:
if item in done:
continue
await do_work(item)
done.add(item)
await agent.working_memory.checkpoint(" ".join(sorted(done)), run_id=RUN)
checkpoint y resume son working_memory.set y working_memory.get sobre el bloque checkpoint (cámbialo con block_key=). Cada checkpoint sobrescribe el anterior.
Advertencia: el
char_limitpor defecto es de 4,096 caracteres (DEFAULT_CHAR_LIMITensdk/python/loom/working_memory.py). Mantén el estado pequeño, o guarda un puntero a él: un blob grande pertenece acontext.offload, con sublob_keyen el checkpoint.
Cuando la tarea termina, borra el checkpoint:
await agent.working_memory.delete("checkpoint", run_id=RUN)
Para un registro de progreso en lugar de una sola instantánea, working_memory.append(..., run_id=RUN) añade a un bloque y working_memory.render(run_id=RUN) vuelve a leer los bloques.
Mediante MCP
working_memory.set aparece listado (loom_working_memory_set) en los toolsets coding, atomic y all, y se ejecuta mediante loom_op en todos los demás toolsets excepto readonly y assistant. working_memory.get no aparece listado en ningún toolset, incluido all; llámalo mediante loom_op con {"op": "working_memory.get", "arguments": {...}}. Un agente:
- llama a
working_memory.setconrun_idyblock_key="checkpoint"después de cada paso; - llama a
working_memory.getcon el mismorun_idyblock_keyal arrancar.
Dos ejecuciones con run_id distintos nunca ven los checkpoints de la otra.
Qué plano guarda un checkpoint
| Estado | Plano | Por qué |
|---|---|---|
| Un cursor de reanudación pequeño (ids hechos, un desplazamiento) | Memoria de trabajo | Se lee por clave exacta; se sobrescribe en cada paso; nunca se genera su embedding |
| Un resultado parcial grande o la salida de un paso | Blob de context.offload |
Guarda contenido que supera el límite del bloque, con un summary y ttl_seconds; se lee con context.fetch |
| Una afirmación que la ejecución estableció | memory.set |
Duradera, con embedding y clasificada para recuperarla después |
La guía del agente de investigación asigna cada tipo de estado del agente a su plano.
Rastrear lo que hizo la ejecución
run.begin/run.completeregistran la propia ejecución: su objetivo, su estado, las memorias en las que se apoyó (memories_used) y una reflexión.run.getdevuelve la ejecución con las claves que recuperó, las memorias que escribió, sus turnos y su coste (ejecuciones).- Las memorias que escribió la ejecución llevan su
run_id;memory.search(run_id=...)filtra por ellas. conversation.createyconversation.appendaceptan unrun_id, de modo que la transcripción de la ejecución queda vinculada a ella (conversaciones y sesiones).- Con
LOOM_SEARCH_TRACE_LOG_ENABLED=true(desactivado por defecto),memory.search_trace_log(run_id=...)lista cada búsqueda que hizo la ejecución y lo que devolvió (depuración).
Loom no guarda instantáneas de las variables del proceso. El checkpoint contiene lo que tú pongas en él.
Por qué funciona
loom.working_memory es una ReplacingMergeTree(version) ordenada por (org, namespace, agent, user_id, session_id, run_id, block_key). Cada checkpoint escribe una nueva versión de la fila y las lecturas colapsan a la más reciente. run_id forma parte de la clave de ordenación, así que dos ejecuciones son dos filas.