Pular para o conteúdo principal
O rastreamento de tarefas fornece uma forma estruturada de gerenciar tarefas e exibir o progresso aos usuários. O Claude Agent SDK inclui funcionalidade integrada de tarefas que ajuda a organizar fluxos de trabalho complexos e manter os usuários informados sobre a progressão das tarefas.
A partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, as sessões usam as ferramentas Task estruturadas TaskCreate, TaskUpdate, TaskGet e TaskList em vez de TodoWrite. Consulte Migrar para ferramentas Task para saber como o código de monitoramento muda. Os exemplos nesta página definem CLAUDE_CODE_ENABLE_TASKS=0 para continuar mostrando TodoWrite para sessões que ainda não foram migradas.

​
Ciclo de Vida das Tarefas

As tarefas seguem um ciclo de vida previsível:
  1. Criadas como pending quando as tarefas são identificadas
  2. Ativadas para in_progress quando o trabalho começa
  3. Concluídas quando a tarefa termina com sucesso
  4. Removidas quando todas as tarefas em um grupo são concluídas

​
Quando as Tarefas São Usadas

O SDK cria automaticamente tarefas para:
  • Tarefas complexas com múltiplas etapas que exigem 3 ou mais ações distintas
  • Listas de tarefas fornecidas pelo usuário quando vários itens são mencionados
  • Operações não triviais que se beneficiam do rastreamento de progresso
  • Solicitações explícitas quando os usuários pedem organização de tarefas

​
Exemplos

​
Monitorando Mudanças de Tarefas

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}`);
        });
      }
    }
  }
}

​
Exibição de Progresso em Tempo 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 para ferramentas Task

As ferramentas Task dividem a única chamada TodoWrite em TaskCreate para cada novo item e TaskUpdate para cada mudança de status, com TaskList e TaskGet disponíveis para o modelo ler de volta a lista atual. Seu código de monitoramento ainda inspeciona blocos tool_use no fluxo do assistente, mas mantém um mapa codificado por ID de tarefa em vez de substituir a lista inteira a cada chamada. As ferramentas Task são o padrão a partir do TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, portanto nenhuma mudança em options.env é necessária.
Com TodoWriteCom ferramentas Task
Uma chamada de ferramenta reescreve o array todos completoTaskCreate adiciona um item, TaskUpdate corrige um item por taskId
Corresponder block.name === "TodoWrite"Corresponder block.name === "TaskCreate" ou "TaskUpdate"
Forma do item: { content, status, activeForm }Entrada de TaskCreate: { subject, description, activeForm?, metadata? }. Entrada de TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status é "pending", "in_progress" ou "completed"; defina status: "deleted" para deletar
Renderizar block.input.todos diretamenteAcumular itens entre chamadas, ou ler um snapshot de um resultado de ferramenta TaskList
O ID de tarefa atribuído não está na entrada de TaskCreate. Ele volta no tool_result correspondente como { task: { id, subject } }, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop Monitorando Mudanças de Tarefas. Para renderizar uma lista completa, observe um resultado de ferramenta TaskList no fluxo ou acumule resultados de TaskCreate e entradas de TaskUpdate em um 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}`);
    }
  }
}

​
Documentação Relacionada