Vai al contenuto principale
Il tracciamento dei todo fornisce un modo strutturato per gestire le attività e visualizzare i progressi agli utenti. Claude Agent SDK include funzionalità todo integrate che aiutano a organizzare flussi di lavoro complessi e mantengono gli utenti informati sulla progressione delle attività.
A partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, le sessioni utilizzano i tool Task strutturati TaskCreate, TaskUpdate, TaskGet e TaskList al posto di TodoWrite. Vedere Migrazione ai tool Task per come monitorare i cambiamenti del codice. Gli esempi in questa pagina impostano CLAUDE_CODE_ENABLE_TASKS=0 per continuare a mostrare TodoWrite per le sessioni che non hanno ancora eseguito la migrazione.

​
Ciclo di vita dei Todo

I todo seguono un ciclo di vita prevedibile:
  1. Creati come pending quando le attività vengono identificate
  2. Attivati a in_progress quando il lavoro inizia
  3. Completati quando l’attività termina con successo
  4. Rimossi quando tutte le attività in un gruppo sono completate

​
Quando vengono utilizzati i Todo

L’SDK crea automaticamente todo per:
  • Attività complesse multi-step che richiedono 3 o più azioni distinte
  • Elenchi di attività forniti dall’utente quando vengono menzionati più elementi
  • Operazioni non banali che traggono beneficio dal tracciamento dei progressi
  • Richieste esplicite quando gli utenti chiedono l’organizzazione dei todo

​
Esempi

​
Monitoraggio dei cambiamenti dei Todo

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

​
Visualizzazione dei progressi in tempo reale

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");

​
Migrazione ai tool Task

I tool Task dividono la singola chiamata TodoWrite in TaskCreate per ogni nuovo elemento e TaskUpdate per ogni cambio di stato, con TaskList e TaskGet disponibili affinché il modello possa leggere di nuovo l’elenco corrente. Il codice di monitoraggio continua a ispezionare i blocchi tool_use nel flusso dell’assistente, ma mantiene una mappa con chiave dell’ID attività invece di sostituire l’intero elenco ad ogni chiamata. I tool Task sono l’impostazione predefinita a partire da TypeScript Agent SDK 0.3.142 e Claude Code v2.1.142, quindi non è necessario alcun cambio options.env.
Con TodoWriteCon tool Task
Una chiamata di tool riscrive l’intero array todosTaskCreate aggiunge un elemento, TaskUpdate modifica un elemento per taskId
Corrisponde a block.name === "TodoWrite"Corrisponde a block.name === "TaskCreate" o "TaskUpdate"
Forma dell’elemento: { content, status, activeForm }Input TaskCreate: { subject, description, activeForm?, metadata? }. Input TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status è "pending", "in_progress" o "completed"; impostare status: "deleted" per eliminare
Renderizza block.input.todos direttamenteAccumula elementi tra le chiamate, o leggi uno snapshot da un risultato dello strumento TaskList
L’ID attività assegnato non è nell’input TaskCreate. Ritorna nel tool_result corrispondente come { task: { id, subject } }, quindi acquisiscilo dal blocco del risultato per inserire la chiave nella mappa. L’esempio seguente mostra il cambio minimo al ciclo Monitoraggio dei cambiamenti dei Todo. Per renderizzare un elenco completo, guarda un risultato dello strumento TaskList nel flusso o accumula i risultati TaskCreate e gli input TaskUpdate in una mappa: 
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}`);
    }
  }
}

​
Documentazione correlata