SpyBara
Go Premium

agent-sdk/todo-tracking.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

18 added, 4 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Listas de Tarefas

Rastreie e exiba tarefas usando o Claude Agent SDK para gerenciamento organizado de tarefas

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.

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. {/* min-version: 2.1.142 */}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 TodoWrite Com ferramentas Task
Uma chamada de ferramenta reescreve o array todos completo TaskCreate 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 diretamente Acumular 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.

O input tool_use transmitido é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando id ou task_id para taskId e active_form para activeForm, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de TaskUpdate defensivamente, como os exemplos abaixo fazem, em vez de assumir que o nome canônico está sempre presente.

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;
id?: string;
task_id?: string;
status?: string;
};
const taskId = input.taskId ?? input.id ?? input.task_id;
if (taskId && input.status) console.log(`  ${taskId} -> ${input.status}`);
}
}
}