Objetivos de aprendizaje:
- Nombrar los seis campos que corresponden a checkpoint.json y, para cada uno, decir con qué se topa la reanudación cuando falta
- Distinguir los dos puntos de guardado dentro de un mismo turno del bucle (después de que el modelo nombra una herramienta, después de que el resultado de la herramienta queda registrado) y explicar a qué te expone escribir solo uno de ellos
- Escribir un
saveCheckpointque no pueda corromper el propio archivo de punto de control: escribir un archivo temporal y después renombrar de forma atómica, en vez de sobrescribir en el lugarRequisitos: Leíste la Lección 1 y sabes distinguir memoria de estado de ejecución; te manejas con el arreglo
messagesy el esqueleto de bucle guiado porstop_reasonde «Fundamentos del arnés de agente: bucles y control» | Anterior: Lección 1 << | Siguiente: Lección 3 >>
La Lección 1 separó memoria y estado de ejecución: la memoria es lo que le das al modelo, el estado de ejecución es la escena en curso que sostiene el propio arnés, el arreglo messages, el contador de turnos, la llamada a herramienta cuyo resultado todavía no quedó registrado. Por omisión esa escena existe solo en la memoria del proceso. Cuando el proceso muere se va con él, y aun con todos los demás archivos intactos en disco, la tarea solo puede arrancar de nuevo desde cero.
Escribir esa escena en disco, convertirla en algo que un proceso reiniciado pueda leer de vuelta, es lo que es un punto de control. Lo que sostiene de verdad la confiabilidad de las tareas largas en la práctica no suele ser pedirle al modelo que absorba cada falla por su cuenta; es combinar "the adaptability of AI agents built on Claude with deterministic safeguards like retry logic and regular checkpoints"1 (la adaptabilidad de los agentes de IA construidos sobre Claude con salvaguardas deterministas como lógica de reintento y puntos de control regulares). Esta lección cubre la mitad del punto de control: qué corresponde poner en uno, en qué lugar del bucle escribirlo y cómo realizar la escritura misma, porque un punto de control mal escrito puede dejarte peor que no tener ninguno.
Un punto de control no es «volcar a un archivo todo lo que hay en memoria». Es «registrar lo que necesita la reanudación del bucle, ni más ni menos». Todas las lecciones posteriores de este curso funcionan con el mismo protocolo:
messages, una forma nueva para pendingToolUse), y version le permite a la ruta de reanudación preguntar «¿reconozco este punto de control?» antes que nada; ante una versión que no conoce, habría que negarse a cargar y fallar ruidosamente en vez de apretar los dientes y seguir parseando.task, el arnés no puede ni decir a qué tarea pertenece el punto de control, mucho menos reportarle al usuario el progreso de la reanudación.messages, y en la mayoría de las configuraciones las cifras históricas de consumo sencillamente ya no están disponibles.null, o bien un registro con forma { id, name, input }, una herramienta que el modelo nombró y cuyo resultado todavía no está registrado. Qué hacer con este campo es asunto de la Lección 3, donde la reanudación concilia contra él; aquí solo necesitas saber que es la ranura designada del punto de control para marcar un estado a medio terminar. Para mantener su forma simple, todos los ejemplos de esta lección suponen un bloque tool_use por turno; cuando un turno emite varias llamadas concurrentes a herramientas, conviértelo en un arreglo, que el razonamiento es el mismo.Mete esos campos en el bucle y resulta que el momento no es tan simple como «escribir una vez al final de cada turno». Hay dos puntos de guardado:
El punto A va después de que llega la respuesta del modelo y antes de que la herramienta se ejecute: registra el bloque tool_use de la respuesta en pendingToolUse y después escribe. El punto B va después de que el resultado de la herramienta se agregó a messages: devuelve pendingToolUse a null y escribe de nuevo.
¿Alcanza con B solo? La exposición es la ventana entre A y B: el modelo nombró una herramienta y la herramienta se está ejecutando, o terminó pero su resultado no llegó a messages ni se escribió en disco. Si el proceso muere en esa ventana, el último punto de control en disco sigue siendo el que escribió B en el turno anterior, y no sabe nada de la llamada de este turno: no es que se haya perdido algún detalle, es que esta llamada a herramienta no dejó rastro alguno en disco. La Lección 3 concilia al reanudar —si esa herramienta terminó de verdad, si hace falta volver a ejecutarla— y contra lo que concilia es precisamente el pendingToolUse que escribió A. Esta lección solo cava el pozo; los ejercicios de la lección 6 te ponen delante un punto de control de solo B y te hacen diagnosticar qué sale mal al reanudar.
El enfoque obvio es hacer JSON.stringify del objeto state y fs.writeFileSync directo encima del viejo checkpoint.json. Eso está bien cuando el proceso termina normalmente, pero «termina normalmente» es exactamente el caso para el que los puntos de control no son. Los puntos de control existen para que maten el proceso en cualquier momento, para el corte de corriente, para que el contenedor sea desalojado. Escribir un archivo no es una operación atómica. Si el proceso se interrumpe a mitad de la escritura, el checkpoint.json que queda en disco puede estar a medio escribir: ni la versión vieja, ni la nueva, solo JSON truncado. La reanudación siguiente lanza una excepción en JSON.parse, y ese archivo era la única copia de la escena de la tarea: no hay ninguna versión más vieja a la que recurrir.
La jugada es «escribir un archivo temporal y después renombrar de forma atómica». Escribe el contenido completo en checkpoint.json.tmp; si te caes a mitad de ese paso, la única baja es el archivo temporal, y el checkpoint.json de verdad sigue siendo la versión más vieja e intacta de antes de la caída, que la reanudación lee sin problema. Una vez que el archivo .tmp está completo, hazle fs.renameSync sobre el nombre real. En el mismo sistema de archivos, rename es un reemplazo atómico de un solo paso: el sistema operativo o bien apunta la entrada de directorio al archivo nuevo por completo, o bien la deja apuntando al viejo. No hay ningún estado intermedio a medio renombrar.
El protocolo que enseña esta lección es para tareas largas desatendidas, con una granularidad de dos puntos de guardado por turno del bucle. Para contrastar, mira dónde pone la palabra «checkpoint» un producto real, Claude Code: "checkpointing automatically captures the state of your code before each user prompt."2 (los puntos de control capturan automáticamente el estado de tu código antes de cada prompt del usuario). "Every user prompt creates a new checkpoint"2 (cada prompt del usuario crea un punto de control nuevo), y "Claude Code saves checkpoints with the conversation, so you can still run /rewind after you resume a session"2 (Claude Code guarda los puntos de control junto con la conversación, así que puedes ejecutar /rewind incluso después de reanudar una sesión).
El escenario al que sirve no es este. Los puntos de control de Claude Code están hechos para una sesión con una persona en el circuito: el usuario puede frenar todo en cualquier momento, probar un enfoque, decidir volver a antes de cierto mensaje y darle otra pasada, así que la unidad natural es «el usuario dijo algo». Lo que estás construyendo aquí es para tareas largas desatendidas: nadie está de guardia para dar el alto, la unidad es «el bucle dio una vuelta», y dentro de un mismo turno se parte otra vez en los puntos de guardado A y B, porque una caída puede producirse entre «el modelo nombró una herramienta» y «el resultado quedó registrado». Los dos no resuelven el mismo problema. Ponerlos uno al lado del otro sirve sobre todo para dejar una cosa clara: cuán fino cortar un punto de control, y cada cuánto escribir uno, depende de a qué sirve el punto de control. No hay una sola respuesta.
Los puntos de control cuestan algo. Bajo el protocolo de esta lección, un turno del bucle escribe en disco dos veces. Para una tarea corta que termina en tres o cinco turnos, eso es puro sobrecosto: el proceso se ejecuta hasta el final y esos archivos de punto de control nunca se leen. Si conviene meter esta maquinaria en tu propio arnés es algo que vale la pena medir contra la regla de que "you should consider adding complexity only when it demonstrably improves outcomes."3 (habría que considerar agregar complejidad solo cuando mejora los resultados de forma demostrable). Cuanto más larga la tarea y más alto el costo de una caída, mejor se pone ese canje; para algo que termina en unos segundos, probablemente no lo necesites.
version, task, turns, tokensUsed, messages, pendingToolUse. messages es la pieza más grande, y sin él el modelo no tiene nada sobre lo que pasó antes; pendingToolUse es la marca de llamada colgante contra la que concilia la Lección 3messages. Guardar solo en B deja un punto ciego en toda la ventana en la que el modelo nombró una herramienta que no terminó.tmp y ponlo en su lugar con fs.renameSync: eso es lo que garantiza que lo que hay en disco en cualquier instante sea una versión completa>> Lección 3: Reanudar desde un punto de control: reiniciar el bucle
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩2
Checkpointing — Claude Code Docs — https://code.claude.com/docs/en/checkpointing ↩ ↩2 ↩3 ↩4
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩2
Frente al protocolo que planteó esta lección, ¿qué campos le faltan todavía a este punto de control? Para cada campo faltante, di específicamente: si intentaras reanudar desde este punto de control incompleto, ¿dónde exactamente se caería?
const checkpoint = {
version: 1,
task: "Clasificar los tickets de soporte del último trimestre por tipo de problema y consolidarlos en una sola tabla",
turns: 3,
tokensUsed: 14208,
messages: [/* el historial completo de la conversación */],
pendingToolUse: null, // o { id, name, input }
};
while (response.stop_reason === "tool_use") {
state.messages.push({ role: "assistant", content: response.content });
const block = response.content.find((b) => b.type === "tool_use");
// Punto de guardado A: el modelo nombró una herramienta, todavía no se ejecutó
state.pendingToolUse = { id: block.id, name: block.name, input: block.input };
saveCheckpoint(state);
const result = await executeTool(block.name, block.input);
state.messages.push({
role: "user",
content: [{ type: "tool_result", tool_use_id: block.id, content: result }],
});
state.turns += 1;
state.pendingToolUse = null;
// Punto de guardado B: el resultado de herramienta de este turno quedó totalmente registrado en messages
saveCheckpoint(state);
response = await callModel({ tools, messages: state.messages });
state.tokensUsed += response.usage?.output_tokens ?? 0;
}
import fs from "node:fs";
import path from "node:path";
function saveCheckpoint(state, dir = "./checkpoints") {
fs.mkdirSync(dir, { recursive: true });
const finalPath = path.join(dir, "checkpoint.json");
const tmpPath = `${finalPath}.tmp`;
fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
fs.renameSync(tmpPath, finalPath); // en un mismo sistema de archivos, rename es un reemplazo atómico
}
function saveCheckpoint(state) {
fs.writeFileSync("checkpoint.json", JSON.stringify({ messages: state.messages }));
}
import fs from "node:fs";
function saveCheckpoint(state) {
fs.writeFileSync("checkpoint.json", JSON.stringify(state, null, 2));
}
async function runAgent(task, tools, callModel, executeTool) {
const state = {
version: 1,
task,
turns: 0,
tokensUsed: 0,
messages: [{ role: "user", content: task }],
pendingToolUse: null,
};
let response = await callModel({ tools, messages: state.messages });
while (response.stop_reason === "tool_use") {
state.messages.push({ role: "assistant", content: response.content });
const block = response.content.find((b) => b.type === "tool_use");
const result = await executeTool(block.name, block.input);
state.messages.push({
role: "user",
content: [{ type: "tool_result", tool_use_id: block.id, content: result }],
});
state.turns += 1;
saveCheckpoint(state);
response = await callModel({ tools, messages: state.messages });
}
return state;
}