跳轉到主要內容
待辦事項追蹤提供了一種結構化的方式來管理任務並向用戶顯示進度。Claude Agent SDK 包含內置的待辦事項功能,可幫助組織複雜的工作流程並讓用戶了解任務進度。
自 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起,會話使用結構化的 Task 工具 TaskCreateTaskUpdateTaskGetTaskList,而不是 TodoWrite。Python SDK 從它啟動的 Claude Code CLI 獲得此變更,而不是從 Python 套件版本:一旦該 CLI(pip 套件內捆綁的副本,或您使用 cli_path 指向的副本)為 v2.1.142 或更新版本,此切換就會適用。請參閱遷移到 Task 工具以了解監控代碼如何變更。此頁面上的範例設置 CLAUDE_CODE_ENABLE_TASKS=0 以繼續為尚未遷移的會話顯示 TodoWrite

待辦事項生命週期

待辦事項遵循可預測的生命週期:
  1. 建立pending 當任務被識別時
  2. 啟動in_progress 當工作開始時
  3. 完成當任務成功完成時
  4. 移除當群組中的所有任務都完成時

何時使用待辦事項

SDK 會為大多數多步驟工作建立待辦事項,例如:
  • 複雜的多步驟任務需要 3 個或更多不同的操作
  • 用戶提供的任務清單當提及多個項目時
  • 非平凡的操作受益於進度追蹤
  • 明確的請求當用戶要求待辦事項組織時
它可能會跳過非常短或單步驟請求的待辦事項。

範例

在執行這些範例之前,請按照快速入門安裝 Claude Agent SDK。 每個範例會執行到代理程式完成並產生其最終結果訊息為止。如果工作階段先達到其輪次限制,該結果訊息會有 error_max_turns 子類型。檢查 subtype 以偵測該結束。 這些範例使用單次 query() 呼叫。在產生 error_max_turns 結果後,query() 會拋出包含 Reached maximum number of turns 的錯誤。每個範例都將其迴圈包裝在 try 區塊中,以便在發生這種情況時乾淨地退出。 請參閱處理結果以了解結果子類型。

監控待辦事項變更

實時進度顯示

遷移到 Task 工具

Task 工具將單個 TodoWrite 呼叫分割為每個新項目的 TaskCreate 和每個狀態變更的 TaskUpdate,並提供 TaskListTaskGet 供模型讀回當前清單。您的監控代碼仍然檢查助手流中的 tool_use 區塊,但維護一個由任務 ID 鍵入的映射,而不是在每次呼叫時替換整個清單。Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起的預設值,因此不需要 options.env 變更。 指派的任務 ID 不在 TaskCreate 輸入中。它在匹配的 tool_result 中作為 { task: { id, subject } } 返回,因此從結果區塊捕獲它以鍵入您的映射。以下範例顯示了對監控待辦事項變更迴圈的最小變更。它僅讀取 tool_use 輸入並跳過從 tool_result 區塊捕獲 ID。要呈現完整清單,請在流中監視 TaskList 工具結果或將 TaskCreate 結果和 TaskUpdate 輸入累積到映射中。 串流的 tool_use 輸入是模型發出的原始形狀。Claude Code 在執行前修復一些接近但不正確的鍵名,將 idtask_id 映射到 taskIdactive_form 映射到 activeForm,但該修復不會反映在流中。防禦性地讀取 TaskUpdate 輸入欄位,如下面的範例所示,而不是假設規範名稱始終存在。