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:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
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.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) oallowed_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=1en la opciónenv, como lo hacen los ejemplos en esta página. En TypeScript,envreemplaza el entorno del subproceso, así que extienda...process.envpara mantener las variables heredadas. En Python,envse 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:- Creada: Claude añade la tarea como
pendingcuando identifica una tarea - Activada: Claude establece la tarea en
in_progresscuando comienza el trabajo - Completada: Claude la marca como completada cuando la tarea finaliza exitosamente
- Eliminada: Claude elimina una tarea que ya no necesita estableciendo
status: "deleted"en una llamadaTaskUpdate
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
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) opermission_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. Verifiquesubtypepara detectar ese final. - Manejo de errores: estos ejemplos utilizan llamadas
query()de un solo disparo. Después de producir un resultadoerror_max_turns,query()genera un error que incluyeReached 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 bloquestool_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 bloquestool_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.
Documentación relacionada
- Referencia del SDK del Agente - TypeScript: las opciones, tipos y esquemas de herramientas para el SDK de TypeScript, incluidos los tipos de entrada y salida de la herramienta Task
- Referencia del SDK del Agente - Python: las opciones, tipos y documentación de herramientas para el SDK de Python
- Entrada de Streaming: los dos modos de entrada, y cuándo usar entrada de streaming en lugar de las llamadas de un solo disparo que utilizan estos ejemplos
- Dar a Claude herramientas personalizadas: defina sus propias herramientas con el servidor MCP en proceso del SDK