模型可用性
下列工具預設僅在 Claude Opus 4.7、Claude Sonnet 4.6、Claude Haiku 4.5 及更早的模型上可用。在所有其他模型上(包括 Claude Code 無法識別的模型 ID),除非您選擇加入,否則這些工具無法使用:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
CLAUDE_CODE_ENABLE_TASKS=0 時改為提供 TodoWrite。此預設集合適用於 Claude Code v2.1.268 及更新版本,TypeScript Agent SDK 從 v0.3.268 開始包含此版本。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 將每個待辦事項移動通過可預測的生命週期:- 建立:Claude 在識別任務時將待辦事項新增為
pending - 啟動:Claude 在開始工作時將待辦事項設定為
in_progress - 完成:Claude 在任務成功完成時將其標記為已完成
- 移除:Claude 通過在
TaskUpdate呼叫中設定status: "deleted"來刪除不再需要的待辦事項
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 區塊中,以便在發生這種情況時乾淨地退出。請參閱處理結果以了解結果子類型。
任務系統訊息,
SDKTaskNotificationMessage(TypeScript)或 TaskNotificationMessage(Python)等,報告背景任務,例如背景命令和子代理程式。在訊息流中,您看到待辦事項活動作為助手訊息中的 tool_use 區塊。監控待辦事項變更
以下範例監視助手流中的TaskCreate 和 TaskUpdate tool_use 區塊,並列印一個 + 行,其中包含每個新任務的主題,以及一個更新行,其中包含每個狀態變更的任務 ID 和新狀態。當您想要任務活動的日誌而不是呈現的顯示時,請使用此形狀。+ 行不包含指派的 ID,因此此日誌無法將更新與其建立相匹配。要保持該相關性,請如即時顯示進度所做的那樣捕獲 ID。
串流的 tool_use 輸入是模型發出的原始形狀。Claude Code 在執行前修復一些接近但不正確的鍵名,將 id 或 task_id 對應到 taskId 和 active_form 對應到 activeForm,但該修復不會反映在流中。防禦性地讀取 TaskUpdate 輸入欄位,如本頁面上的兩個範例所做的那樣,而不是假設規範名稱始終存在。
即時顯示進度
以下範例監視助手流中的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 讀回一個任務的完整詳細資訊。
相關文件
- Agent SDK 參考 - TypeScript:TypeScript SDK 的選項、類型和工具架構,包括 Task 工具輸入和輸出類型
- Agent SDK 參考 - Python:Python SDK 的選項、類型和工具文件
- 串流輸入:兩種輸入模式,以及何時使用串流輸入而不是這些範例使用的單次呼叫
- 為 Claude 提供自訂工具:使用 SDK 的進程內 MCP 伺服器定義您自己的工具