自 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起,會話使用結構化的 Task 工具
TaskCreate、TaskUpdate、TaskGet 和 TaskList,而不是 TodoWrite。Python SDK 從它啟動的 Claude Code CLI 獲得此變更,而不是從 Python 套件版本:一旦該 CLI(pip 套件內捆綁的副本,或您使用 cli_path 指向的副本)為 v2.1.142 或更新版本,此切換就會適用。請參閱遷移到 Task 工具以了解監控代碼如何變更。此頁面上的範例設置 CLAUDE_CODE_ENABLE_TASKS=0 以繼續為尚未遷移的會話顯示 TodoWrite。待辦事項生命週期
待辦事項遵循可預測的生命週期:- 建立為
pending當任務被識別時 - 啟動為
in_progress當工作開始時 - 完成當任務成功完成時
- 移除當群組中的所有任務都完成時
何時使用待辦事項
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,並提供 TaskList 和 TaskGet 供模型讀回當前清單。您的監控代碼仍然檢查助手流中的 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 在執行前修復一些接近但不正確的鍵名,將 id 或 task_id 映射到 taskId 和 active_form 映射到 activeForm,但該修復不會反映在流中。防禦性地讀取 TaskUpdate 輸入欄位,如下面的範例所示,而不是假設規範名稱始終存在。