SpyBara
Go Premium

agent-sdk/todo-tracking.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 247 additions and 195 deletions.

2026
Thu 10 23:00 Sat 12 03:02

追蹤待辦事項

在 Agent SDK 工作階段中追蹤待辦事項，並從結構化工具呼叫在應用程式中呈現 Claude 的進度

在模型可用性下列出的模型上，Claude 無需書面待辦事項清單即可追蹤多步驟工作，而 Claude Code 預設會將任務追蹤工具排除在工作階段之外。您不需要本頁面上的任何內容，Claude 就能在這些模型上完成多步驟任務。

在具有任務追蹤工具的工作階段中，Claude 保持書面待辦事項清單，在工作時更新每個項目的狀態。您在訊息流中看到每個變更都是結構化工具呼叫。僅當您的應用程式讀取這些工具呼叫時才選擇加入工作階段，無論是記錄任務活動還是呈現自己的進度顯示。

模型可用性

在列出的模型上，除非您選擇加入工作階段，否則您在訊息流中看不到這些工具的 tool_use 區塊。Agent SDK 通過它捆綁的 Claude Code 二進位檔案應用這些預設值。如果您將 pathToClaudeCodeExecutable（TypeScript）或 cli_path（Python）指向您自己的 Claude Code 安裝，您將獲得該安裝提供的任何工具，在其自己的預設值下。要查看執行中工作階段中的確切集合，請檢查哪些工具可用。要選擇加入工作階段，請執行以下操作之一：

  • 在 allowedTools（TypeScript）或 allowed_tools（Python）選項中命名其中一個工具
  • 在 tools 選項中列出工具，這會將工作階段的內置工具限制為它命名的工具。將您想要的工具與您使用的其他內置工具一起包含
  • 在 env 選項中設定 CLAUDE_CODE_ENABLE_TODO_TOOLS=1，如本頁面上的範例所做的那樣。在 TypeScript 中，env 替換子程序環境，因此展開 ...process.env 以保留繼承的變數。在 Python 中，env 合併在繼承的環境之上

待辦事項生命週期

Claude 將每個待辦事項移動通過可預測的生命週期：

  1. 建立：Claude 在識別任務時將待辦事項新增為 pending
  2. 啟動：Claude 在開始工作時將待辦事項設定為 in_progress
  3. 完成：Claude 在任務成功完成時將其標記為已完成
  4. 移除：Claude 通過在 TaskUpdate 呼叫中設定 status: "deleted" 來刪除不再需要的待辦事項

Claude 何時建立待辦事項

在具有任務追蹤工具的工作階段中，Claude 為大多數多步驟工作建立待辦事項，例如：

  • 複雜的多步驟任務需要三個或更多不同的操作
  • 使用者提供的任務清單當提及多個項目時
  • 較長的操作受益於進度追蹤
  • 明確的請求當使用者要求待辦事項組織時

Claude 可能會跳過非常短或單步驟請求的待辦事項。

範例

在執行這些範例之前，請按照快速入門安裝 Claude Agent SDK。本頁面上的每個範例都共享相同的權限設定和退出行為：

  • 權限模式：範例提示要求 Claude 在專案上執行實際工作，因此每個範例都設定 permissionMode: "acceptEdits"（TypeScript）或 permission_mode="acceptEdits"（Python）以自動批准工作產生的檔案編輯。請參閱權限模式以了解替代方案。
  • 輪次限制：每個範例執行到代理程式完成並產生其最終結果訊息為止。如果工作階段先達到其輪次限制，該結果訊息會有 error_max_turns 子類型。檢查 subtype 以偵測該結束。
  • 錯誤處理：這些範例使用單次 query() 呼叫。在產生 error_max_turns 結果後，query() 會拋出包含 Reached maximum number of turns 的錯誤。每個範例都將其迴圈包裝在 try 區塊中，以便在發生這種情況時乾淨地退出。請參閱處理結果以了解結果子類型。

監控待辦事項變更

以下範例監視助手流中的 TaskCreate 和 TaskUpdate tool_use 區塊，並列印一個 + 行，其中包含每個新任務的主題，以及一個更新行，其中包含每個狀態變更的任務 ID 和新狀態。當您想要任務活動的日誌而不是呈現的顯示時，請使用此形狀。+ 行不包含指派的 ID，因此此日誌無法將更新與其建立相匹配。要保持該相關性，請如即時顯示進度所做的那樣捕獲 ID。

串流的 tool_use 輸入是模型發出的原始形狀。Claude Code 在執行前修復一些接近但不正確的鍵名，將 id 或 task_id 對應到 taskId 和 active_form 對應到 activeForm，但該修復不會反映在流中。防禦性地讀取 TaskUpdate 輸入欄位，如本頁面上的兩個範例所做的那樣，而不是假設規範名稱始終存在。

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

try {
for await (const message of query({
prompt: "Create a static website with a home page, an about page, and a shared stylesheet, and track progress with todos",
// Keeps the Task tools on models where Claude Code otherwise doesn't provide them.
options: { maxTurns: 15, permissionMode: "acceptEdits", env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } },
})) {
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}`);
}
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result.
console.log(`Session ended with an error: ${error}`);
}

即時顯示進度

以下範例監視助手流中的 TaskCreate 和 TaskUpdate tool_use 區塊，並在 TaskTracker 類別中保持由任務 ID 鍵入的任務映射，在每次變更時重新呈現進度摘要。摘要計算已完成和進行中的任務，並顯示每個活動項目的 activeForm 標籤以代替其 subject。當您的應用程式維護進度顯示而不是記錄每個事件時，請使用此形狀。

指派的任務 ID 不在 TaskCreate 輸入中。Claude Code 在攜帶其 tool_result 區塊的使用者訊息上傳遞每個工具的結構化輸出，在 tool_use_result 欄位中。對於 TaskCreate，該物件在 TypeScript 中記錄為工具輸出類型下的 TaskCreateOutput，在 Python 中該欄位是相同形狀的純字典。追蹤器通過 tool_use_id 將每個 tool_result 區塊與其 tool_use 呼叫配對，並從配對訊息的 tool_use_result 讀取 task.id。Claude 可以使用 TaskList 讀回清單，使用 TaskGet 讀回一個任務的完整詳細資訊。

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

type Task = { subject: string; activeForm?: string; status: string };

class TaskTracker {
private tasks = new Map<string, Task>();
private pendingCreates = new Map<string, { subject: string; activeForm?: string }>();

displayProgress() {
if (this.tasks.size === 0) {
console.log("\nProgress: no open tasks\n");
return;
}

const items = [...this.tasks.values()];
const completed = items.filter((t) => t.status === "completed").length;
const inProgress = items.filter((t) => t.status === "in_progress").length;

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

for (const [id, task] of this.tasks) {
const icon =
task.status === "completed" ? "✅" : task.status === "in_progress" ? "🔧" : "❌";
const text = task.status === "in_progress" && task.activeForm ? task.activeForm : task.subject;
console.log(`${id}. ${icon} ${text}`);
}
}

handleToolUse(block: { id: string; name: string; input: unknown }) {
if (block.name === "TaskCreate") {
const input = block.input as { subject: string; activeForm?: string; active_form?: string };
this.pendingCreates.set(block.id, {
subject: input.subject,
activeForm: input.activeForm ?? input.active_form,
});
} else if (block.name === "TaskUpdate") {
const input = block.input as {
taskId?: string;
id?: string;
task_id?: string;
status?: string;
activeForm?: string;
active_form?: string;
};
const taskId = input.taskId ?? input.id ?? input.task_id;
if (!taskId) return;
if (input.status === "deleted") {
this.tasks.delete(taskId);
this.displayProgress();
return;
}
const task = this.tasks.get(taskId);
if (!task) return;
if (input.status) task.status = input.status;
const active = input.activeForm ?? input.active_form;
if (active) task.activeForm = active;
this.displayProgress();
}
}

handleToolResult(block: { tool_use_id: string; is_error?: boolean }, result: unknown) {
const create = this.pendingCreates.get(block.tool_use_id);
if (!create) return;
this.pendingCreates.delete(block.tool_use_id);
if (block.is_error) return;
// The result's user message carries the tool's structured output as
// tool_use_result; for TaskCreate that's TaskCreateOutput,
// { task: { id, subject } }.
const out = result as { task?: { id: string } };
if (!out?.task?.id) return;
this.tasks.set(out.task.id, { ...create, status: "pending" });
this.displayProgress();
}

async trackQuery(prompt: string) {
try {
for await (const message of query({
prompt,
options: { maxTurns: 20, permissionMode: "acceptEdits", env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } },
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use") this.handleToolUse(block);
}
}
if (message.type === "user" && Array.isArray(message.message.content)) {
for (const block of message.message.content) {
if (block.type === "tool_result") this.handleToolResult(block, message.tool_use_result);
}
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// such as when the maxTurns limit is hit.
console.log(`Session ended with an error: ${error}`);
}
}
}

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