Skip to main content
Claude Code proporciona las herramientas de seguimiento de tareas de forma predeterminada solo en los modelos enumerados en Disponibilidad de modelos. Los modelos más nuevos rastrean trabajo de múltiples pasos sin una lista de tareas escrita, por lo que en esos no necesita nada en esta página para que Claude trabaje en tareas de múltiples pasos. En una sesión que tiene las herramientas de seguimiento de tareas, Claude mantiene una lista de tareas escrita, actualizando el estado de cada elemento mientras trabaja. Verá cada cambio en la secuencia de mensajes como una llamada de herramienta estructurada. Opte por una sesión solo cuando su aplicación lea esas llamadas de herramientas, ya sea para registrar la actividad de tareas o para renderizar su propia pantalla de progreso.

Disponibilidad de modelos

The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn’t recognize, they aren’t available unless you opt in:
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
Wherever the tools are available, Claude Code provides the four Task tools, or TodoWrite instead when you set CLAUDE_CODE_ENABLE_TASKS=0.This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
En un modelo que no tiene las herramientas de forma predeterminada, a menos que opte por una sesión, no verá bloques tool_use para ellas en la secuencia de mensajes. El SDK del Agente aplica estos valores predeterminados a través del binario de Claude Code que incluye. Si apunta pathToClaudeCodeExecutable (TypeScript) o cli_path (Python) a su propia instalación de Claude Code, obtiene las herramientas que esa instalación proporciona, bajo sus propios valores predeterminados. Para ver el conjunto exacto en una sesión en ejecución, verifique qué herramientas están disponibles. Para optar por una sesión, haga uno de lo siguiente:
  • Nombre una de las herramientas en la opción allowedTools (TypeScript) o allowed_tools (Python)
  • Liste las herramientas en la opción tools, que restringe las herramientas integradas de la sesión a las que nombra. Incluya las herramientas que desea junto con las otras herramientas integradas que utiliza
  • Establezca CLAUDE_CODE_ENABLE_TODO_TOOLS=1 en la opción env, como lo hacen los ejemplos en esta página. En TypeScript, env reemplaza el entorno del subproceso, así que extienda ...process.env para mantener las variables heredadas. En Python, env se fusiona en la parte superior del entorno heredado

Ciclo de vida de tareas

Claude mueve cada tarea a través de un ciclo de vida predecible:
  1. Creada: Claude añade la tarea como pending cuando identifica una tarea
  2. Activada: Claude establece la tarea en in_progress cuando comienza el trabajo
  3. Completada: Claude la marca como completada cuando la tarea finaliza exitosamente
  4. Eliminada: Claude elimina una tarea que ya no necesita estableciendo status: "deleted" en una llamada TaskUpdate

Cuándo Claude crea tareas

En una sesión que tiene las herramientas de seguimiento de tareas, Claude crea tareas para la mayoría del trabajo de múltiples pasos, como:
  • Tareas complejas de múltiples pasos que requieren tres o más acciones distintas
  • Listas de tareas proporcionadas por el usuario cuando se mencionan múltiples elementos
  • Operaciones más largas que se benefician del seguimiento del progreso
  • Solicitudes explícitas cuando los usuarios piden organización de tareas
Claude 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 en esta página comparte la misma configuración de permisos y comportamiento de salida:
  • Modo de permiso: los ejemplos de solicitud piden a Claude que haga trabajo real en un proyecto, así que cada ejemplo establece permissionMode: "acceptEdits" (TypeScript) o permission_mode="acceptEdits" (Python) para aprobar automáticamente las ediciones de archivo que produce el trabajo. Vea Modos de permiso para las alternativas.
  • Límite de turnos: 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.
  • Manejo de errores: 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. Vea Manejar el resultado para los subtipos de resultado.
Los mensajes del sistema de tareas, SDKTaskNotificationMessage (TypeScript) o TaskNotificationMessage (Python) entre ellos, reportan tareas de fondo como comandos en segundo plano y subagentes. En la secuencia de mensajes, verá la actividad de tareas como bloques tool_use en los mensajes del asistente.

Monitorear cambios de tareas

El siguiente ejemplo observa la secuencia del asistente para bloques tool_use de TaskCreate y TaskUpdate e imprime una línea + con el asunto de cada nueva tarea y una línea de actualización con el ID de tarea y el nuevo estado de cada cambio de estado. Use esta forma cuando desee un registro de actividad de tareas en lugar de una pantalla renderizada. Las líneas + no incluyen los IDs asignados, así que este registro no puede hacer coincidir las actualizaciones con sus creaciones. Para mantener esa correlación, capture los IDs como lo hace Mostrar progreso en tiempo real. 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 ambos ejemplos en esta página, en lugar de asumir que el nombre canónico siempre está presente.

Mostrar progreso en tiempo real

El siguiente ejemplo observa la secuencia del asistente para bloques tool_use de TaskCreate y TaskUpdate y mantiene un mapa de tareas codificado por ID de tarea en una clase TaskTracker, rerenderizando un resumen de progreso en cada cambio. El resumen cuenta tareas completadas y en progreso y muestra la etiqueta activeForm de cada elemento activo en lugar de su subject. Use esta forma cuando su aplicación mantenga una pantalla de progreso en lugar de registrar cada evento. El ID de tarea asignado no está en la entrada de TaskCreate. Claude Code entrega la salida estructurada de cada herramienta en el mensaje del usuario que lleva su bloque tool_result, en el campo tool_use_result. Para TaskCreate, ese objeto se documenta para TypeScript como TaskCreateOutput en Tipos de Salida de Herramientas, y en Python el campo es un dict simple de la misma forma. El rastreador empareja cada bloque tool_result con su llamada tool_use por tool_use_id y lee task.id del tool_use_result del mensaje emparejado. Claude puede leer la lista de vuelta con TaskList y los detalles completos de una tarea con TaskGet.