模型可用性
The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn’t recognize, they aren’t available unless you opt in:
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
TodoWrite instead when you set CLAUDE_CODE_ENABLE_TASKS=0.This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from 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 服务器定义您自己的工具