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. 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 automáticamente tareas para:
  • 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

​
Monitoreo de Cambios en Tareas

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance and track progress with todos",
  // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
  // Task tools instead and these tool_use blocks never appear.
  options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
})) {
  // Todo updates are reflected in the message stream
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "tool_use" && block.name === "TodoWrite") {
        const todos = block.input.todos;

        console.log("Todo Status Update:");
        todos.forEach((todo, index) => {
          const status =
            todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
          console.log(`${index + 1}. ${status} ${todo.content}`);
        });
      }
    }
  }
}

​
Visualización de Progreso en Tiempo Real

import { query } from "@anthropic-ai/claude-agent-sdk";

class TodoTracker {
  private todos: any[] = [];

  displayProgress() {
    if (this.todos.length === 0) return;

    const completed = this.todos.filter((t) => t.status === "completed").length;
    const inProgress = this.todos.filter((t) => t.status === "in_progress").length;
    const total = this.todos.length;

    console.log(`\nProgress: ${completed}/${total} completed`);
    console.log(`Currently working on: ${inProgress} task(s)\n`);

    this.todos.forEach((todo, index) => {
      const icon =
        todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
      const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
      console.log(`${index + 1}. ${icon} ${text}`);
    });
  }

  async trackQuery(prompt: string) {
    for await (const message of query({
      prompt,
      // Re-enable TodoWrite, which this tracker watches for.
      options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
    })) {
      if (message.type === "assistant") {
        for (const block of message.message.content) {
          if (block.type === "tool_use" && block.name === "TodoWrite") {
            this.todos = block.input.todos;
            this.displayProgress();
          }
        }
      }
    }
  }
}

// Usage
const tracker = new TodoTracker();
await tracker.trackQuery("Build a complete authentication system with todos");

​
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.
Con TodoWriteCon herramientas Task
Una llamada de herramienta reescribe el array todos completoTaskCreate añade un elemento, TaskUpdate parcha un elemento por taskId
Coincide con block.name === "TodoWrite"Coincide con block.name === "TaskCreate" o "TaskUpdate"
Forma del elemento: { content, status, activeForm }Entrada de TaskCreate: { subject, description, activeForm?, metadata? }. Entrada de TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status es "pending", "in_progress" o "completed"; establezca status: "deleted" para eliminar
Renderice block.input.todos directamenteAcumule elementos entre llamadas, o lea una instantánea de un resultado de herramienta TaskList
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. 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: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance",
})) {
  if (message.type !== "assistant") continue;
  for (const block of message.message.content) {
    if (block.type !== "tool_use") continue;
    if (block.name === "TaskCreate") {
      const input = block.input as { subject: string };
      console.log(`+ ${input.subject}`);
    } else if (block.name === "TaskUpdate") {
      const input = block.input as { taskId: string; status?: string };
      if (input.status) console.log(`  ${input.taskId} -> ${input.status}`);
    }
  }
}

​
Documentación Relacionada