Saltar al contenido principal
El seguimiento de tareas proporciona una forma estructurada de gestionar tareas y mostrar el progreso a los usuarios. El SDK del Agente Claude incluye funcionalidad de tareas integrada que ayuda a organizar flujos de trabajo complejos y mantener a los usuarios informados sobre la progresión de las tareas.
A partir del TypeScript Agent SDK 0.3.142 y Claude Code v2.1.142, las sesiones utilizan las herramientas Task estructuradas TaskCreate, TaskUpdate, TaskGet y TaskList en lugar de TodoWrite. El SDK de Python obtiene este cambio de la CLI de Claude Code que lanza, no de la versión del paquete de Python: el cambio se aplica una vez que esa CLI — la copia incluida dentro del paquete pip, o una a la que apunte con cli_path — sea v2.1.142 o posterior. Consulte Migrar a herramientas Task para ver cómo cambia el código de monitoreo. Los ejemplos en esta página establecen CLAUDE_CODE_ENABLE_TASKS=0 para seguir mostrando TodoWrite para sesiones que aún no han migrado.

Ciclo de Vida de las Tareas

Las tareas siguen un ciclo de vida predecible:
  1. Creadas como pending cuando se identifican las tareas
  2. Activadas a in_progress cuando comienza el trabajo
  3. Completadas cuando la tarea finaliza exitosamente
  4. Eliminadas cuando todas las tareas en un grupo se completan

Cuándo se Utilizan las Tareas

El SDK crea tareas para la mayoría del trabajo de múltiples pasos, como:
  • Tareas complejas de múltiples pasos que requieren 3 o más acciones distintas
  • Listas de tareas proporcionadas por el usuario cuando se mencionan múltiples elementos
  • Operaciones no triviales que se benefician del seguimiento del progreso
  • Solicitudes explícitas cuando los usuarios piden organización de tareas
Puede omitir tareas para solicitudes muy cortas o de un solo paso.

Ejemplos

Antes de ejecutar estos ejemplos, instale el Claude Agent SDK siguiendo el inicio rápido. Cada ejemplo se ejecuta hasta que el agente termina y produce su mensaje de resultado final. Si una sesión alcanza primero su límite de turnos, ese mensaje de resultado tiene el subtipo error_max_turns. Verifique subtype para detectar ese final. Estos ejemplos utilizan llamadas query() de un solo disparo. Después de producir un resultado error_max_turns, query() genera un error que incluye Reached maximum number of turns. Cada ejemplo envuelve su bucle en un bloque try para salir limpiamente cuando eso sucede. Consulte Manejar el resultado para los subtipos de resultado.

Monitoreo de Cambios en Tareas

Visualización de Progreso en Tiempo Real

Migrar a herramientas Task

Las herramientas Task dividen la única llamada TodoWrite en TaskCreate para cada elemento nuevo y TaskUpdate para cada cambio de estado, con TaskList y TaskGet disponibles para que el modelo lea la lista actual. Su código de monitoreo aún inspecciona bloques tool_use en la secuencia del asistente, pero mantiene un mapa codificado por ID de tarea en lugar de reemplazar la lista completa en cada llamada. Las herramientas Task son las predeterminadas a partir del TypeScript Agent SDK 0.3.142 y Claude Code v2.1.142, por lo que no se necesita cambio en options.env. El ID de tarea asignado no está en la entrada de TaskCreate. Vuelve en el bloque tool_result coincidente como { task: { id, subject } }, así que capturelo del bloque de resultado para codificar su mapa. El siguiente ejemplo muestra el cambio mínimo al bucle Monitoreo de Cambios en Tareas. Lee solo entradas de tool_use y omite capturar IDs de bloques tool_result. Para renderizar una lista completa, observe un resultado de herramienta TaskList en la secuencia o acumule resultados de TaskCreate e entradas de TaskUpdate en un mapa. La entrada tool_use transmitida es la forma bruta que emitió el modelo. Claude Code repara algunos nombres de clave casi correctos pero incorrectos antes de la ejecución, asignando id o task_id a taskId y active_form a activeForm, pero esa reparación no se refleja en la secuencia. Lea los campos de entrada de TaskUpdate defensivamente, como lo hacen los ejemplos a continuación, en lugar de asumir que el nombre canónico siempre está presente.