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:- Creadas como
pendingcuando se identifican las tareas - Activadas a
in_progresscuando comienza el trabajo - Completadas cuando la tarea finaliza exitosamente
- 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
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 subtipoerror_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 llamadaTodoWrite 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.