Agent Mentor Learn
Memoria y estado del agente · Lección 4 de 6

Lección 4: Estado estructurado: cómo un agente recuerda en qué punto está una tarea

Objetivos de aprendizaje:

  • Explicar por qué enterrar el progreso de una tarea en prosa conversacional no es fiable, y por qué tiene que convertirse en estado estructurado
  • Enunciar el ciclo de vida completo que recorre una tarea pendiente, desde su creación hasta su eliminación
  • Distinguir el costo de empezar de cero frente al de retomar desde donde se interrumpió el trabajo
  • Decidir si una pieza del estado de la tarea debería vivir en el historial de la sesión o escribirse en un punto de control separado

Requisitos: terminar la Lección 3 y entender los dos modos de la memoria externa | Anterior: Lección 3 << | Siguiente: Lección 5 >>

Tras reiniciarse el proceso, ¿el agente sigue sabiendo en qué paso estaba?

Un agente va avanzando por una tarea de varios pasos: refactorizar un módulo, que se descompone en cuatro pasos — «actualizar las definiciones de tipos», «actualizar los puntos de llamada», «ejecutar las pruebas», «actualizar la documentación». Acaba de terminar el segundo paso cuando el proceso se interrumpe por un reinicio inesperado. Cuando vuelve a arrancar, se enfrenta a la misma descripción de la tarea. ¿Debería rehacer el paso uno desde cero, o sabe que ya terminó los dos primeros pasos y puede retomar directamente desde el paso tres?

La respuesta se reduce a una sola cosa: si el progreso de la tarea quedó registrado como estado estructurado, en lugar de esparcido por un montón de prosa conversacional. Si «las definiciones de tipos ya están actualizadas» no es más que una línea de lenguaje natural en una de las respuestas anteriores del modelo, sepultada entre decenas de mensajes, el código anfitrión no tiene forma fiable de extraer de ahí el hecho concreto «en qué paso estamos». Pero si ese progreso se expresa como una lista de tareas pendientes con campos fijos — donde cada tarea lleva un marcador de estado explícito —, el código anfitrión puede leerlo directamente: los pasos uno y dos están completos, el paso tres no ha empezado.

Esa es la pregunta central que aborda esta lección. Las Lecciones 1, 2 y 3 trataban todas de cómo gestionar el contenido — el historial de conversación, los archivos de memoria. Esta lección trata de cómo expresar el progreso, para que un agente o su aplicación anfitriona, tras una interrupción, sepa exactamente hasta dónde llegó la tarea.

El ciclo de vida de una tarea pendiente: creada, activada, completada, eliminada

Tomemos como ejemplo la herramienta de seguimiento de tareas de Claude Code. La documentación oficial expone el ciclo de vida completo que recorre una tarea pendiente durante la ejecución — cuatro pasos:1

  1. Creada: Claude añade la tarea pendiente como pending cuando identifica una tarea
  2. Activada: Claude pone la tarea pendiente en in_progress cuando empieza el trabajo
  3. Completada: Claude la marca como completed cuando la tarea termina con éxito
  4. Eliminada: Claude borra una tarea pendiente que ya no necesita fijando status: "deleted" en una llamada TaskUpdate1

Estos cuatro pasos no son el vago «ya está» o «estoy en ello» del lenguaje natural. Son cuatro valores de estado explícitos: pending, in_progress, completed y deleted para la eliminación. Cada cambio de estado sucede a través de una llamada a herramienta explícita, no porque el modelo suelte un comentario en el texto de su respuesta.

La documentación también detalla cómo se manifiesta de verdad este mecanismo en la conversación: "In a session that has the task-tracking tools, Claude keeps a written todo list, updating each item's status as it works. You see each change in the message stream as a structured tool call."1 (En una sesión que dispone de las herramientas de seguimiento de tareas, Claude mantiene por escrito una lista de tareas pendientes y va actualizando el estado de cada elemento a medida que trabaja. Ves cada cambio en el flujo de mensajes como una llamada a herramienta estructurada.) Esa frase fija la distinción clave: el progreso no se «refleja» pasivamente en la conversación, se escribe activamente como una llamada a herramienta que se puede identificar y analizar por sí sola. Esa es la diferencia real entre el estado estructurado y una descripción de progreso esparcida por la prosa.

Puntos de control: convertir la recuperación en algo distinto de empezar de cero

Una vez que tienes una lista de tareas pendientes estructurada, la siguiente pregunta es: ¿dónde vive la lista en sí? Si solo existe en el historial de conversación de esta sesión, en el momento en que la sesión termine de verdad (no una interrupción breve, sino un cierre completo, como la idea de la Lección 3 de que «cuando la sesión termina, todo lo que hay en la ventana desaparece»), el registro de progreso se esfuma con ella. En el fondo, la API no tiene estado: "The Messages API is stateless, which means that you always send the full conversational history to the API."2 (La API de Mensajes no tiene estado, lo que significa que siempre envías el historial completo de la conversación a la API.)

Ese es el problema que resuelven los puntos de control: escribir el estado de una tarea en un momento dado — qué pasos están hechos, cuál es el paso actual, qué pasos quedan — en una pieza de datos, y persistirla en algún sitio fuera del tiempo de vida de la sesión. Los puntos de control usan el mismo mecanismo subyacente que la memoria externa de la Lección 3 (escribir un archivo, leerlo de vuelta más tarde); la diferencia es que un punto de control no guarda «conocimiento que vale la pena recordar», sino «hasta dónde llegó la tarea» — el tipo de estado que puedes usar directamente para reanudar la ejecución.

Con los puntos de control en su sitio, por fin se sostiene la recuperabilidad: tras un reinicio del proceso, el agente no tiene que adivinar «dónde estaba». Lee el punto de control más reciente, ve «los pasos uno y dos están completed, el paso tres está in_progress», y continúa desde el paso tres en lugar de rehacer los pasos uno y dos.

La comparación de costos aquí es concreta. En la tarea de refactorización, el paso «actualizar las definiciones de tipos», si es idempotente (ejecutarlo de nuevo produce el mismo resultado), solo cuesta tiempo perdido cuando se rehace desde cero. Pero si algún paso es una operación no idempotente como «insertar un registro de migración en la base de datos», empezar de cero podría insertar dos registros duplicados e incluso corromper datos. Lo que un punto de control ahorra no es solo tiempo — es el riesgo de volver a ejecutar por accidente ese tipo de operación no idempotente.

El estado estructurado existe para que la interrupción sea superable

Volviendo al escenario con el que abrió esta lección: tras reiniciarse el proceso, ¿debería el agente empezar de cero o retomar desde donde se interrumpió? Ahora podemos responderlo con claridad — depende de si se hicieron dos cosas. ¿Se expresó el progreso de la tarea como estado estructurado (en lugar de esparcido por la prosa conversacional), y se escribió ese estado en un punto de control (en lugar de vivir solo en el historial de esta única sesión)? Necesitas ambas. Con estado estructurado pero sin punto de control, el estado desaparece igualmente cuando termina la sesión; con un punto de control pero sin estado estructurado, lo que se escribió en el punto de control es a su vez lenguaje natural vago, y leerlo de vuelta sigue sin decirte de forma fiable en qué paso quedó la tarea.

Esta lección trató de cómo expresar y preservar el progreso. La siguiente lección se vuelca en otra pregunta que importa igual de tanto: ¿podría este estado y esta memoria preservados convertirse en un objetivo para atacantes — qué pasa si un atacante puede escribir contenido en un punto de control o en un archivo de memoria?

Resumen

  • El progreso de una tarea solo lo puede leer de forma fiable el código anfitrión una vez que se convierte en estado estructurado; una descripción de progreso esparcida por respuestas en lenguaje natural no se puede analizar de forma estable para saber «en qué paso estamos ahora mismo»
  • El ciclo de vida completo de una tarea pendiente son cuatro pasos — creada (pending), activada (in_progress), completada (completed), eliminada (deleted) — y cada paso sucede a través de una llamada a herramienta estructurada explícita que se puede observar en el flujo de mensajes
  • Estructurado y persistente son dos cosas distintas: estructurado resuelve «puede leerlo un programa», un punto de control resuelve «sigue estando ahí el estado tras un reinicio del proceso o cuando termina la sesión» — necesitas ambas
  • Un punto de control escribe el estado de una tarea en un momento dado en algún sitio fuera del tiempo de vida de la sesión, convirtiendo la recuperación en «continuar desde donde se interrumpió» en lugar de «empezar de cero», y evitando en especial volver a ejecutar por accidente operaciones no idempotentes
  • El estado estructurado, igual que la memoria externa, se convierte en su propio objetivo de ataque una vez persistido — el tema de la siguiente lección; cuanto más preservas, más límites tienes que sostener

>> Lección 5: Los límites y la seguridad de la memoria

Footnotes

  1. Track todos — https://code.claude.com/docs/en/agent-sdk/todo-tracking ↩ ↩2 ↩3

  2. Using the Messages API — https://platform.claude.com/docs/en/build-with-claude/working-with-messages ↩

Ejercicios

01

Un agente recibe la tarea «añadir pruebas unitarias al proyecto» y la descompone en tres tareas pendientes: «escribir los casos de prueba», «ejecutar la batería de pruebas», «corregir los casos que fallan». Siguiendo el orden cronológico de abajo, anota en qué estado del ciclo de vida (pending / in_progress / completed / deleted) debería estar cada tarea pendiente en cada momento.

Nivel 1: Etiquetar el estado del ciclo de vida de una única ejecución de tarea
  1. La tarea acaba de descomponerse; ninguna de las tres ha empezado.
  2. El agente empieza a escribir los casos de prueba.
  3. Los casos de prueba están escritos; el agente empieza a ejecutar la batería de pruebas.
  4. Al ejecutar las pruebas se descubren dos casos que fallan (el caso A y el caso B). El agente refina «corregir los casos que fallan» en dos nuevas tareas pendientes, «corregir el caso A» y «corregir el caso B», y empieza a corregir el caso A.
  5. Mientras corrige el caso A, resulta que el caso B era en realidad la propia prueba mal escrita y no necesita ningún cambio, así que «corregir el caso B» se elimina.
Criterios de finalización · marcado local
02

Un equipo diseñó esta lógica de ejecución: el progreso de la tarea del agente aparece solo en el resumen en lenguaje natural de cada una de sus respuestas, algo como «hasta ahora los dos primeros pasos están hechos, actualmente ocupándome del tercero». Ese resumen existe solo en el historial de mensajes de la sesión actual; el equipo no escribe ningún archivo de punto de control. El sistema reinicia el proceso de vez en cuando por límites de recursos, y tras un reinicio se retoma la misma tarea.

Nivel 2: Diagnosticar un diseño de tarea no recuperable

Señala los dos problemas de este diseño (uno sobre «si el estado está estructurado», otro sobre «si el estado está persistido»), y da la dirección de corrección correspondiente para cada uno.

Criterios de finalización · marcado local