跳转到主要内容
待办事项跟踪提供了一种结构化的方式来管理任务并向用户显示进度。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 映射到 taskId,将 active_form 映射到 activeForm,但该修复不会反映在流中。防御性地读取 TaskUpdate 输入字段,如下面的示例所示,而不是假设规范名称始终存在。