deepagents SDK 0.7 系列演进全解析从破坏性变更到子代理编排强化【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本指南以 libs/deepagents/CHANGELOG.md 为骨架系统梳理 deepagents SDKbatteries-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依赖langchain1.4.0,2.0.0、langchain-core1.6.2、langchain-anthropic、langchain-google-genai、langsmith等。从 Changelog 可以看到 SDK 的演进分三个阶段版本区间里程碑主题关键入口0.5.2 – 0.5.4filesystem 权限系统、harness profiles声明式覆盖层0.5.4 的 Highlights 章节0.6.0 – 0.6.12QuickJS 代码解释器、RubricMiddleware、Bedrock 提示缓存、deepagents[aws]extra0.6.0 / 0.6.5 / 0.6.120.7.0 – 0.7.13大版本破坏性变更middleware、prompt、filesystem 语义、backend API随后多轮修复加固0.7.0 的 BREAKING CHANGES 章节其中 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被标记为弃用计划在deepagents0.9.0移除但在 0.9.0 之前仍可导入并返回旧的完整提示词要恢复旧行为可显式传入create_deep_agent(system_promptBASE_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→BASEprofile 的base_system_prompt默认空→SUFFIXprofile 的system_prompt_suffix顺序拼接。若三者均为空模型收到的 authored 提示词即为空——这正是精简语义的落地。2.3 文件系统安全加固virtual_mode 默认开启0.7.0 起FilesystemBackend与LocalShellBackend默认virtual_modeTrue文件路径锚定在root_dir之下拒绝..路径穿越解析到root_dir之外的路径直接抛出ValueError。此前未指定virtual_mode时会发出弃用警告并回退到False——此时使用宿主机的绝对路径原样访问且..可以逃逸root_dir。要恢复旧的宽松行为需显式传virtual_modeFalse。实现可参考 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必须显式配置namespacels/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/GlobResultread_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...)设置默认值1000None禁用模型可在单次调用中用新参数max_count覆盖本地 ripgrep 输出流式处理并在达到上限时终止read_file 分页信息内置read_file分页响应报告返回的源行区间与下一个offset后端知道文件长度时附带总行数与剩余行数视频帧提取通过新 extradeepagents[video]启用read_file将视频采样为 JPEG 帧offset/limit按秒解释见 pyproject.toml 中的video [av18.0.0,19.0.0, pillow12.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.7ContextHubBackend并发变更改为批量执行BackendProtocol.glob对裸模式改为递归。0.7.8files状态仅在 state 后端添加。0.7.9middleware 关闭 tracing 输入harness profiles 设置excluded_tools时从执行中排除工具RubricMiddleware强制完整 criterion 覆盖澄清execute-timeout0的语义。0.7.10防止本地 shell 命令抢占 TUI 输入沙箱 glob 失败时如实上报而不是报告无匹配。0.7.11为 rubric graders 增加 SDK 集成钩子。0.7.12SDK 支持子代理对话分叉conversation forking修复 glob 排序容忍缺失的modified_at。0.7.13SDK 子代理模式由handoff更名为isolated。其中 0.7.12 的子代理分叉与 graph.py 中关于SubAgent的实验性modefork说明相互印证fork 模式延续父对话并重建系统提示词子 agent 自己的system_prompt追加到继承的提示词之后且 fork 模式不能定义skills。四、回溯 0.5.x – 0.6.x理解 0.7 的前提4.1 harness profiles按模型族定制的声明式覆盖层0.5.40.5.4 是 0.7.0 之前最重要的功能发布。它引入harness profiles——一套声明式覆盖层用于描述随模型族变化的 harness 配置system-prompt 前缀/后缀、工具包含与命名、middleware 选择、子代理配置、skillsProviderProfile决定resolve_model如何构建客户端HarnessProfile/HarnessProfileConfig决定create_deep_agent如何装配 agent二者均以 provideropenai或完整provider:model规格openai:gpt-5.4为键注册是追加式的——切换模型时调用点无需改动。仓库内 profiles/harness/harness_profiles.py 中可以看到GeneralPurposeSubagentProfile控制自动添加的general-purpose子代理含三态enabled字段与HarnessProfileConfigYAML/JSON 可加载的配置子集运行时调整如extra_middleware需用HarnessProfileprofiles/ 目录下提供了 OpenAI、AnthropicHaiku/Sonnet/Opus、NVIDIA 等内置 profile。按 Changelog 记录OpenAI 与 Anthropic 的内置 profile 直接取材自各家官方提示指南Codex 的apply_patch/shell_command约定、Claude 的工具结果反思与主动调查模式且在一组精选 tau2-bench 子集上相比默认 harness 有 10–20 分的提升GPT-5.3 Codex33% → 53%Claude Opus 4.743% → 53%——该数据是 Changelog 原文档记录的评测结果具体数值因评测集与模型版本而异。第三方插件可通过deepagents.provider_profiles与deepagents.harness_profilesentry points 注册。4.2 RubricMiddleware自评式迭代0.6.50.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至少一项失败继续循环、failedrubric 本身畸形或无法评估中间件合成两个 grader 无法自己发出的终态max_iterations_reached迭代上限触发agent 保留最后响应终止与grader_errorgrader 抛异常区别于针对 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.20.5.2 引入 filesystem 访问控制的权限系统规则按声明顺序评估、首个匹配生效、无匹配则放行每条规则mode可为allow默认/deny/interrupt暂停等待人工审批自动安装HumanInTheLoopMiddleware。0.6.8 为权限新增 interrupt 模式源码中有专门的 _fs_interrupt.py。0.7.0 在此基础上把delete归类为写操作见上文 2.40.5.2 还要求权限路径必须以/开头、禁止路径穿越否则抛ValueError。对应配置类型FilesystemPermission与FsToolName均从init.py 顶层导出。4.4 QuickJS 代码解释器与流式事件0.6.00.6.0 新增实验性CodeInterpreterMiddleware通过作用域隔离的 QuickJS 运行时支持代码执行与程序化工具调用安装方式为可选依赖deepagents[quickjs]对应 pyproject.toml 中的quickjs [langchain-quickjs0.3.7]。同版本支持stream_events/astream_events的versionv3事件流。0.6.12 又新增deepagents[aws]extra安装langchain-aws为 Bedrock 用户提供自动提示缓存集成pyproject.toml。五、升级 0.7.x 的迁移清单综合以上分析从 0.6.x 及更早版本升级到 0.7.x 时应按以下清单逐项核对middleware 依赖确认没有依赖默认的TodoListMiddleware/write_todos需要时显式传入TodoListMiddleware()。提示词依赖旧默认提示词的 agent 需显式传system_promptBASE_AGENT_PROMPT引用了TASK_SYSTEM_PROMPT等五个常量需改为自备字符串注意 0.9.0 将移除BASE_AGENT_PROMPT。文件系统边界确认代码不依赖virtual_modeFalse的宽松路径行为绝对路径直通、..逃逸需要旧行为显式传virtual_modeFalse。写语义write_file现在会覆盖已存在文件——审计所有依赖 file-exists 错误的逻辑改用edit_file或权限/中断规则保护。delete 权限为新增的递归delete工具配置 deny/interrupt 规则或从FilesystemMiddleware(tools...)中省略。后端 API移除对ls_info/glob_info/grep_raw等废弃方法及files_update的引用StoreBackend显式配置namespace后端传实例而非工厂。输出解析解析器适配No files found空结果、动态对齐的read_file行号格式、grep/glob的truncated标志与max_count参数。子代理命名涉及子代理模式的代码注意 0.7.13 中handoff→isolated的更名以及 0.7.12 起可选的 fork 模式需注意 fork 子代理不能定义skills。六、相关源码速查graph.pycreate_deep_agent完整签名model/tools/system_prompt/middleware/subagents/skills/memory/permissions/backend/interrupt_on/response_format/state_schema/context_schema等、middleware 堆栈装配顺序与提示词拼接规则。middleware/filesystem.pyFilesystemMiddleware、FilesystemPermission、FsToolName与内置文件系统工具的 allowlist 过滤。middleware/rubric.pygrader 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.pyprofile 注册与配置模型。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 SDKbatteries-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依赖langchain1.4.0,2.0.0、langchain-core1.6.2、langchain-anthropic、langchain-google-genai、langsmith等。从 Changelog 可以看到 SDK 的演进分三个阶段版本区间里程碑主题关键入口0.5.2 – 0.5.4filesystem 权限系统、harness profiles声明式覆盖层0.5.4 的 Highlights 章节0.6.0 – 0.6.12QuickJS 代码解释器、RubricMiddleware、Bedrock 提示缓存、deepagents[aws]extra0.6.0 / 0.6.5 / 0.6.120.7.0 – 0.7.13大版本破坏性变更middleware、prompt、filesystem 语义、backend API随后多轮修复加固0.7.0 的 BREAKING CHANGES 章节其中 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被标记为弃用计划在deepagents0.9.0移除但在 0.9.0 之前仍可导入并返回旧的完整提示词要恢复旧行为可显式传入create_deep_agent(system_promptBASE_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→BASEprofile 的base_system_prompt默认空→SUFFIXprofile 的system_prompt_suffix顺序拼接。若三者均为空模型收到的 authored 提示词即为空——这正是精简语义的落地。2.3 文件系统安全加固virtual_mode 默认开启0.7.0 起FilesystemBackend与LocalShellBackend默认virtual_modeTrue文件路径锚定在root_dir之下拒绝..路径穿越解析到root_dir之外的路径直接抛出ValueError。此前未指定virtual_mode时会发出弃用警告并回退到False——此时使用宿主机的绝对路径原样访问且..可以逃逸root_dir。要恢复旧的宽松行为需显式传virtual_modeFalse。实现可参考 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必须显式配置namespacels/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/GlobResultread_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...)设置默认值1000None禁用模型可在单次调用中用新参数max_count覆盖本地 ripgrep 输出流式处理并在达到上限时终止read_file 分页信息内置read_file分页响应报告返回的源行区间与下一个offset后端知道文件长度时附带总行数与剩余行数视频帧提取通过新 extradeepagents[video]启用read_file将视频采样为 JPEG 帧offset/limit按秒解释见 pyproject.toml 中的video [av18.0.0,19.0.0, pillow12.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.7ContextHubBackend并发变更改为批量执行BackendProtocol.glob对裸模式改为递归。0.7.8files状态仅在 state 后端添加。0.7.9middleware 关闭 tracing 输入harness profiles 设置excluded_tools时从执行中排除工具RubricMiddleware强制完整 criterion 覆盖澄清execute-timeout0的语义。0.7.10防止本地 shell 命令抢占 TUI 输入沙箱 glob 失败时如实上报而不是报告无匹配。0.7.11为 rubric graders 增加 SDK 集成钩子。0.7.12SDK 支持子代理对话分叉conversation forking修复 glob 排序容忍缺失的modified_at。0.7.13SDK 子代理模式由handoff更名为isolated。其中 0.7.12 的子代理分叉与 graph.py 中关于SubAgent的实验性modefork说明相互印证fork 模式延续父对话并重建系统提示词子 agent 自己的system_prompt追加到继承的提示词之后且 fork 模式不能定义skills。四、回溯 0.5.x – 0.6.x理解 0.7 的前提4.1 harness profiles按模型族定制的声明式覆盖层0.5.40.5.4 是 0.7.0 之前最重要的功能发布。它引入harness profiles——一套声明式覆盖层用于描述随模型族变化的 harness 配置system-prompt 前缀/后缀、工具包含与命名、middleware 选择、子代理配置、skillsProviderProfile决定resolve_model如何构建客户端HarnessProfile/HarnessProfileConfig决定create_deep_agent如何装配 agent二者均以 provideropenai或完整provider:model规格openai:gpt-5.4为键注册是追加式的——切换模型时调用点无需改动。仓库内 profiles/harness/harness_profiles.py 中可以看到GeneralPurposeSubagentProfile控制自动添加的general-purpose子代理含三态enabled字段与HarnessProfileConfigYAML/JSON 可加载的配置子集运行时调整如extra_middleware需用HarnessProfileprofiles/ 目录下提供了 OpenAI、AnthropicHaiku/Sonnet/Opus、NVIDIA 等内置 profile。按 Changelog 记录OpenAI 与 Anthropic 的内置 profile 直接取材自各家官方提示指南Codex 的apply_patch/shell_command约定、Claude 的工具结果反思与主动调查模式且在一组精选 tau2-bench 子集上相比默认 harness 有 10–20 分的提升GPT-5.3 Codex33% → 53%Claude Opus 4.743% → 53%——该数据是 Changelog 原文档记录的评测结果具体数值因评测集与模型版本而异。第三方插件可通过deepagents.provider_profiles与deepagents.harness_profilesentry points 注册。4.2 RubricMiddleware自评式迭代0.6.50.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至少一项失败继续循环、failedrubric 本身畸形或无法评估中间件合成两个 grader 无法自己发出的终态max_iterations_reached迭代上限触发agent 保留最后响应终止与grader_errorgrader 抛异常区别于针对 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.20.5.2 引入 filesystem 访问控制的权限系统规则按声明顺序评估、首个匹配生效、无匹配则放行每条规则mode可为allow默认/deny/interrupt暂停等待人工审批自动安装HumanInTheLoopMiddleware。0.6.8 为权限新增 interrupt 模式源码中有专门的 _fs_interrupt.py。0.7.0 在此基础上把delete归类为写操作见上文 2.40.5.2 还要求权限路径必须以/开头、禁止路径穿越否则抛ValueError。对应配置类型FilesystemPermission与FsToolName均从init.py 顶层导出。4.4 QuickJS 代码解释器与流式事件0.6.00.6.0 新增实验性CodeInterpreterMiddleware通过作用域隔离的 QuickJS 运行时支持代码执行与程序化工具调用安装方式为可选依赖deepagents[quickjs]对应 pyproject.toml 中的quickjs [langchain-quickjs0.3.7]。同版本支持stream_events/astream_events的versionv3事件流。0.6.12 又新增deepagents[aws]extra安装langchain-aws为 Bedrock 用户提供自动提示缓存集成pyproject.toml。五、升级 0.7.x 的迁移清单综合以上分析从 0.6.x 及更早版本升级到 0.7.x 时应按以下清单逐项核对middleware 依赖确认没有依赖默认的TodoListMiddleware/write_todos需要时显式传入TodoListMiddleware()。提示词依赖旧默认提示词的 agent 需显式传system_promptBASE_AGENT_PROMPT引用了TASK_SYSTEM_PROMPT等五个常量需改为自备字符串注意 0.9.0 将移除BASE_AGENT_PROMPT。文件系统边界确认代码不依赖virtual_modeFalse的宽松路径行为绝对路径直通、..逃逸需要旧行为显式传virtual_modeFalse。写语义write_file现在会覆盖已存在文件——审计所有依赖 file-exists 错误的逻辑改用edit_file或权限/中断规则保护。delete 权限为新增的递归delete工具配置 deny/interrupt 规则或从FilesystemMiddleware(tools...)中省略。后端 API移除对ls_info/glob_info/grep_raw等废弃方法及files_update的引用StoreBackend显式配置namespace后端传实例而非工厂。输出解析解析器适配No files found空结果、动态对齐的read_file行号格式、grep/glob的truncated标志与max_count参数。子代理命名涉及子代理模式的代码注意 0.7.13 中handoff→isolated的更名以及 0.7.12 起可选的 fork 模式需注意 fork 子代理不能定义skills。六、相关源码速查graph.pycreate_deep_agent完整签名model/tools/system_prompt/middleware/subagents/skills/memory/permissions/backend/interrupt_on/response_format/state_schema/context_schema等、middleware 堆栈装配顺序与提示词拼接规则。middleware/filesystem.pyFilesystemMiddleware、FilesystemPermission、FsToolName与内置文件系统工具的 allowlist 过滤。middleware/rubric.pygrader 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.pyprofile 注册与配置模型。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
