deepagents SDK 0.7 系列演进全解析：从破坏性变更到子代理编排强化

deepagents SDK 0.7 系列演进全解析：从破坏性变更到子代理编排强化

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

本指南以 libs/deepagents/CHANGELOG.md 为骨架，系统梳理 deepagents SDK（batteries-included agent harness）从 0.5.x 到 0.7.13 的版本演进脉络，重点解读 0.7.0 引入的破坏性变更、0.7.x 的修复与新增能力，并结合仓库源码（graph.py、middleware/、profiles/、backends/）给出实现层面的佐证。读者阅读后将掌握：当前版本（0.7.13）的关键 API 形态、升级 0.7.x 时需要处理的迁移点、以及 filesystem 权限、harness profiles、RubricMiddleware 等核心机制的底层设计。

一、版本演进总览

deepagents SDK 位于 libs/deepagents，当前最新版本为0.7.13（见 _version.py 与 pyproject.toml），支持 Python 3.11–3.14，依赖langchain>=1.4.0,<2.0.0、langchain-core>=1.6.2、langchain-anthropic、langchain-google-genai、langsmith等。从 Changelog 可以看到 SDK 的演进分三个阶段：

其中 0.7.0 是整个 SDK 发展史上的关键转折点——它同时清理了默认工具集、精简了默认提示词、强化了文件系统安全边界，并移除了大量废弃 API。理解 0.7.0 的变更，就等于理解了 0.7.x 后续所有修复（0.7.1–0.7.13）的上下文。

二、0.7.0：一次系统性"瘦身 + 加固"的破坏性发布

2.1 TodoListMiddleware 退出默认堆栈

0.7.0 最直接的行为变化：create_deep_agent不再默认包含TodoListMiddleware，随之消失的还有write_todos工具、todos状态通道以及 todo 规划提示词。如需恢复，需显式传入middleware=[TodoListMiddleware()]到主 agent；若子 agent 也需要，则要分别加到每个SubAgent的 middleware 上。

这与 graph.py 中描述 middleware 堆栈的源码相印证——默认基础堆栈（Base stack）只包含SkillsMiddleware、FilesystemMiddleware、SubAgentMiddleware、SummarizationMiddleware、PatchToolCallsMiddleware、AsyncSubAgentMiddleware，用户自定义 middleware 插入在基础堆栈与尾堆栈（tail stack）之间。从源码结构看，TodoListMiddleware正是被从这套默认装配中移出，改为按需显式注入。

2.2 默认提示词精简：BASE_AGENT_PROMPT 进入弃用通道

0.7.0 将默认 agent 提示词改为"精简模式"：内置 base prompt 置空，并删减了与工具 schema 重复的工具使用说明。BASE_AGENT_PROMPT被标记为弃用（计划在deepagents==0.9.0移除），但在 0.9.0 之前仍可导入并返回旧的完整提示词；要恢复旧行为，可显式传入create_deep_agent(system_prompt=BASE_AGENT_PROMPT)。

同时，一批内置工具提示词常量被整体删除：TASK_SYSTEM_PROMPT、ASYNC_TASK_SYSTEM_PROMPT、SUMMARIZATION_SYSTEM_PROMPT、FILESYSTEM_SYSTEM_PROMPT、EXECUTION_SYSTEM_PROMPT。对应的SubAgentMiddleware、AsyncSubAgentMiddleware、SummarizationToolMiddleware及create_summarization_tool_middleware的system_prompt默认值改为None（即不再注入任何提示词文本），需要提示词时由调用方自行传入字符串。

在 graph.py 中可以看到新提示词装配规则：最终提示词按USER（调用方 system_prompt）→BASE（profile 的base_system_prompt，默认空）→SUFFIX（profile 的system_prompt_suffix）顺序拼接。若三者均为空，模型收到的 authored 提示词即为空——这正是"精简"语义的落地。

2.3 文件系统安全加固：virtual_mode 默认开启

0.7.0 起，FilesystemBackend与LocalShellBackend默认virtual_mode=True：

• 文件路径锚定在root_dir之下；
• 拒绝..路径穿越；
• 解析到root_dir之外的路径直接抛出ValueError。

此前未指定virtual_mode时会发出弃用警告并回退到False——此时使用宿主机的绝对路径原样访问，且..可以逃逸root_dir。要恢复旧的宽松行为，需显式传virtual_mode=False。实现可参考 backends/filesystem.py 与 backends/local_shell.py 中的路径校验逻辑（validate_path等辅助函数定义于 backends/utils.py）。

2.4 递归 delete 工具与权限语义变更

只要后端支持，agent 现在会看到一个破坏性的递归delete文件系统工具，且 filesystem 权限将delete归类为写操作——这意味着：一条允许写入某路径的规则，同时也授权递归删除该子树，除非存在更窄的 deny 或 interrupt 规则覆盖目标路径。由于递归删除影响子孙节点，deny/interrupt 检查改用**批量路径重叠（bulk path overlap）**而非精确路径匹配。

具体行为还包括：缺失路径返回 not-found 错误；CompositeBackend在路由到的子后端不支持删除时报告 unsupported-operation 错误；后端本身未实现删除时，工具对整个模型隐藏。若想保持旧行为，可添加 deny/interrupt 规则，或在FilesystemMiddleware(tools=...)中省略delete。

2.5 write_file 语义：从"报错"到"覆盖"

0.7.0 起，write_file在目标文件缺失时创建它，已存在时整体替换，不再返回 file-exists 错误，工具描述也不再要求先读文件。没有"仅创建（create-only）"兼容模式。此前依赖 file-exists 错误来强制走edit_file或保护既有内容的工作流/提示词/测试/护栏，现在必须：显式省略write_file、增加权限或 interrupt 规则，或在需要保留既有内容时改用edit_file。

2.6 BackendProtocol 与结果类型 API 清理

0.7.0 移除了一批废弃兼容层：

• 工厂形态后端：调用方必须传具体的BackendProtocol实例，不能再传工厂函数；
• StoreBackend必须显式配置namespace；
• ls/glob/grep/ReadResult采用当前形态的 API；
• 移除BackendProtocol的废弃方法ls_info、als_info、glob_info、aglob_info、grep_raw、agrep_raw，统一用ls/glob/grep及 async 对应方法；
• WriteResult/EditResult移除files_update属性与构造参数，状态写入改由StateBackend直接发出；
• SummarizationMiddleware(history_path_prefix=...)移除并直接抛TypeError，改由CompositeBackend(artifacts_root=...)配置。

此外还有两处面向输出解析的破坏性变化：agent 视角的ls/glob空结果从[]改为渲染No files found（后端 API 仍返回结构化的空LsResult/GlobResult）；read_file不再使用cat -n风格的固定宽度行号栏和 Tab 分隔，改为动态对齐、源码内容与行号之间用两个空格分隔，常量LINE_NUMBER_WIDTH从deepagents.backends.utils和deepagents.middleware.filesystem中删除。解析原始工具输出的调用方都需要更新解析器。

2.7 0.7.0 的新增能力

• middleware 同名替换：自定义 middleware 传入create_deep_agent(..., middleware=[...])时，若.name与默认实例匹配，可以替换内置默认实例（例如覆盖SummarizationMiddleware），无需同时排除内置实例；
• FsToolName 白名单：FilesystemMiddleware(tools=[...])接受关键字专用白名单，类型为新增导出的FsToolName字面量（"ls"、"read_file"、"write_file"、"edit_file"、"delete"、"glob"、"grep"、"execute"），传"all"或省略则保留全部；列表必须包含"read_file"，否则构造器抛ValueError；被省略的内置工具不可执行，自定义工具不受影响；
• grep 结果截断：GrepResult/GlobResult新增truncated标志，后端超时时返回有效部分结果而非报错，agent 视角输出会提示模型缩小搜索范围；FilesystemBackend.glob支持花括号展开（如*.{py,md}）；
• 可配置 grep 匹配上限：FilesystemMiddleware(grep_max_count=...)设置默认值（1000，None禁用），模型可在单次调用中用新参数max_count覆盖；本地 ripgrep 输出流式处理并在达到上限时终止；
• read_file 分页信息：内置read_file分页响应报告返回的源行区间与下一个offset，后端知道文件长度时附带总行数与剩余行数；
• 视频帧提取：通过新 extradeepagents[video]启用，read_file将视频采样为 JPEG 帧，offset/limit按秒解释（见 pyproject.toml 中的video = ["av>=18.0.0,<19.0.0", "pillow>=12.3.0,<13.0.0"]）；
• execute 大输出落盘：兼容且主动加入的BaseSandbox实现可在沙箱 artifact 路径内捕获过大的execute工具输出以减少往返，LangSmithSandbox默认加入；
• Fireworks 提示缓存：检测到兼容的langchain-fireworks时自动启用 prompt-cache 会话亲和性；
• NVIDIA 支持：内置 NVIDIA Nemotron 3 Ultra harness profile 及 NIM app-origin 归属；
• RubricMiddleware 迭代上限放开：接受任意正数max_iterations上限，不再强制硬顶。

三、0.7.x 的持续修复与功能增强

0.7.0 之后，0.7.1–0.7.13 以小步快跑的方式修复回归并补充能力：

• 0.7.1：可编辑安装（editable installs）在lc_versions.deepagents中标记为+editable（见 _version.py 的 PEP 440 local segment 逻辑）；退化的read_file窗口返回空读；未解析的状态 schema 从静默跳过改为警告。
• 0.7.2：清除模型 profile 不支持的多模态内容块。
• 0.7.3：修复精确文件delete目标解析，采用 first-match-wins 行为。
• 0.7.4：在 SDK artifacts 中暴露execute的退出码。
• 0.7.5：识别支持 files 的 SDK provider 类。
• 0.7.6：摘要时将会话历史卸载到独立的 session ID。
• 0.7.7：ContextHubBackend并发变更改为批量执行；BackendProtocol.glob对裸模式改为递归。
• 0.7.8：files状态仅在 state 后端添加。
• 0.7.9：middleware 关闭 tracing 输入；harness profiles 设置excluded_tools时从执行中排除工具；RubricMiddleware强制完整 criterion 覆盖；澄清execute-timeout=0的语义。
• 0.7.10：防止本地 shell 命令抢占 TUI 输入；沙箱 glob 失败时如实上报而不是报告"无匹配"。
• 0.7.11：为 rubric graders 增加 SDK 集成钩子。
• 0.7.12：SDK 支持子代理对话分叉（conversation forking）；修复 glob 排序容忍缺失的modified_at。
• 0.7.13：SDK 子代理模式由handoff更名为isolated。

其中 0.7.12 的子代理分叉与 graph.py 中关于SubAgent的实验性mode="fork"说明相互印证：fork 模式延续父对话并重建系统提示词，子 agent 自己的system_prompt追加到继承的提示词之后，且 fork 模式不能定义skills。

四、回溯 0.5.x – 0.6.x：理解 0.7 的前提

4.1 harness profiles：按模型族定制的声明式覆盖层（0.5.4）

0.5.4 是 0.7.0 之前最重要的功能发布。它引入harness profiles——一套声明式覆盖层，用于描述随模型族变化的 harness 配置（system-prompt 前缀/后缀、工具包含与命名、middleware 选择、子代理配置、skills）：

• ProviderProfile决定resolve_model如何构建客户端；
• HarnessProfile/HarnessProfileConfig决定create_deep_agent如何装配 agent；
• 二者均以 provider（"openai"）或完整provider:model规格（"openai:gpt-5.4"）为键，注册是追加式的——切换模型时调用点无需改动。

仓库内 profiles/harness/harness_profiles.py 中可以看到GeneralPurposeSubagentProfile（控制自动添加的general-purpose子代理，含三态enabled字段）与HarnessProfileConfig（YAML/JSON 可加载的配置子集，运行时调整如extra_middleware需用HarnessProfile）；profiles/ 目录下提供了 OpenAI、Anthropic（Haiku/Sonnet/Opus）、NVIDIA 等内置 profile。按 Changelog 记录，OpenAI 与 Anthropic 的内置 profile 直接取材自各家官方提示指南（Codex 的apply_patch/shell_command约定、Claude 的工具结果反思与主动调查模式），且在一组精选 tau2-bench 子集上相比默认 harness 有 10–20 分的提升（GPT-5.3 Codex：33% → 53%；Claude Opus 4.7：43% → 53%）——该数据是 Changelog 原文档记录的评测结果，具体数值因评测集与模型版本而异。第三方插件可通过deepagents.provider_profiles与deepagents.harness_profilesentry points 注册。

4.2 RubricMiddleware：自评式迭代（0.6.5）

0.6.5 引入RubricMiddleware，让调用方用**评分标准（rubric）**声明"什么算完成"。每次 agent 即将结束（模型返回无进一步工具调用的响应）时，middleware 调用独立的 grader 子 agent 对 transcript 评分；若返回needs_revision，其反馈以HumanMessage注入，agent 循环继续，直到 grader 返回satisfied/failed或达到max_iterations。

从 middleware/rubric.py 可以看到 verdict 类型定义：satisfied（全部 criterion 通过）、needs_revision（至少一项失败，继续循环）、failed（rubric 本身畸形或无法评估）；中间件合成两个 grader 无法自己发出的终态max_iterations_reached（迭代上限触发，agent 保留最后响应终止）与grader_error（grader 抛异常，区别于针对 rubric 的failed）。0.7.0 起其max_iterations放开为任意正数，0.7.9 起强制完整 criterion 覆盖，0.7.9/0.7.11 还改善了 grader 失败诊断（记录配置的模型、结构化输出策略、整数 HTTP 状态）并新增 SDK 集成钩子。0.7.0 中Emit max_iterations_reached as the terminal RubricMiddleware status的修复（见 0.7.0 Bug Fixes 章节）确保了迭代耗尽时以正确终态收尾。

4.3 文件系统权限系统（0.5.2）

0.5.2 引入 filesystem 访问控制的权限系统：规则按声明顺序评估、首个匹配生效、无匹配则放行；每条规则mode可为allow（默认）/deny/interrupt（暂停等待人工审批，自动安装HumanInTheLoopMiddleware）。0.6.8 为权限新增 interrupt 模式（源码中有专门的 _fs_interrupt.py）。0.7.0 在此基础上把delete归类为写操作（见上文 2.4），0.5.2 还要求权限路径必须以/开头、禁止路径穿越（否则抛ValueError）。对应配置类型FilesystemPermission与FsToolName均从init.py 顶层导出。

4.4 QuickJS 代码解释器与流式事件（0.6.0）

0.6.0 新增实验性CodeInterpreterMiddleware：通过作用域隔离的 QuickJS 运行时支持代码执行与程序化工具调用，安装方式为可选依赖deepagents[quickjs]（对应 pyproject.toml 中的quickjs = ["langchain-quickjs>=0.3.7"]）。同版本支持stream_events/astream_events的version="v3"事件流。0.6.12 又新增deepagents[aws]extra（安装langchain-aws），为 Bedrock 用户提供自动提示缓存集成（pyproject.toml）。

五、升级 0.7.x 的迁移清单

综合以上分析，从 0.6.x 及更早版本升级到 0.7.x 时，应按以下清单逐项核对：

1. middleware 依赖：确认没有依赖默认的TodoListMiddleware/write_todos；需要时显式传入TodoListMiddleware()。
2. 提示词：依赖旧默认提示词的 agent 需显式传system_prompt=BASE_AGENT_PROMPT；引用了TASK_SYSTEM_PROMPT等五个常量需改为自备字符串；注意 0.9.0 将移除BASE_AGENT_PROMPT。
3. 文件系统边界：确认代码不依赖virtual_mode=False的宽松路径行为（绝对路径直通、..逃逸）；需要旧行为显式传virtual_mode=False。
4. 写语义：write_file现在会覆盖已存在文件——审计所有依赖 file-exists 错误的逻辑，改用edit_file或权限/中断规则保护。
5. delete 权限：为新增的递归delete工具配置 deny/interrupt 规则，或从FilesystemMiddleware(tools=...)中省略。
6. 后端 API：移除对ls_info/glob_info/grep_raw等废弃方法及files_update的引用；StoreBackend显式配置namespace；后端传实例而非工厂。
7. 输出解析：解析器适配No files found空结果、动态对齐的read_file行号格式、grep/glob的truncated标志与max_count参数。
8. 子代理命名：涉及子代理模式的代码注意 0.7.13 中handoff→isolated的更名，以及 0.7.12 起可选的 fork 模式（需注意 fork 子代理不能定义skills）。

六、相关源码速查

• graph.py：create_deep_agent完整签名（model/tools/system_prompt/middleware/subagents/skills/memory/permissions/backend/interrupt_on/response_format/state_schema/context_schema等）、middleware 堆栈装配顺序与提示词拼接规则。
• middleware/filesystem.py：FilesystemMiddleware、FilesystemPermission、FsToolName与内置文件系统工具的 allowlist 过滤。
• middleware/rubric.py：grader verdict 类型、transcript 截断策略与迭代状态机。
• middleware/subagents.py 与 middleware/async_subagents.py：同步/异步子代理。
• backends/：FilesystemBackend、LocalShellBackend、CompositeBackend、StateBackend、StoreBackend、ContextHubBackend与BackendProtocol。
• profiles/harness/harness_profiles.py 与 profiles/provider/provider_profiles.py：profile 注册与配置模型。
• pyproject.toml：依赖与aws/quickjs/video可选 extras。
• _version.py：版本管理与可编辑安装的版本标记逻辑。

结语

从 0.5.4 的 profiles 到 0.7.13 的isolated子代理模式，deepagents SDK 在不到一年的演进中完成了从"能力堆叠"到"声明式、可定制、安全加固"的转变。0.7.0 的破坏性变更本质上是一次面向长期健康的架构整理：默认提示词与工具集回归精简、文件系统默认进入沙箱语义、废弃 API 彻底清除。对于使用或计划使用该 SDK 的开发者，建议以 CHANGELOG.md 配合上述源码路径交叉阅读，在升级时严格执行迁移清单，并关注 0.9.0 对BASE_AGENT_PROMPT的移除计划。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents