DeepAgents 深度源码解析与全框架工程实践

摘要

DeepAgents 是 LangChain 团队于 2025-2026 年推出的生产级 Agent Harness 框架，构建于 LangGraph 运行时之上，提供了一套开箱即用且可深度扩展的智能体执行架构。本文从源码实现、设计原理、工程实践三个维度，对 DeepAgents 进行全框架、全组件的深度解析。内容涵盖提示词上下文工程、长短期记忆、技能系统、工具与 MCP 集成、中间件管道、权限控制、人类在环（HITL）、多模态、中断与恢复、动态子代理、异步执行、Harness Profile、自动化评估等核心模块，旨在为架构师与高级开发者提供一份完备、细节化的技术参考。

第一章：概述与架构总览

1.1 项目定位与设计哲学

DeepAgents 被明确定义为一个 "batteries-included agent harness"——一种带有强烈主观意见（opinionated）但保持高度可扩展性的智能体控制框架。其设计哲学基于四个核心原则：

1. Opinionated Defaults: 针对长周期、多步骤复杂任务进行默认调优，而非提供最小化的底层原语。

2. Extensibility Without Forking: 任何组件均可通过中间件、配置、钩子进行覆盖或替换，无需 fork 源码。

3. Model Agnostic: 兼容所有支持 tool calling 的模型，包括 frontier（OpenAI、Anthropic、Google）、open-weight（via Fireworks、Baseten）以及本地模型（Ollama、vLLM）。

4. Production Ready: 构建于 LangGraph 之上，原生支持流式处理、持久化、checkpoint、tracing（LangSmith）以及评估体系。

1.2 框架分层与依赖关系

DeepAgents 并非独立框架，而是 LangChain 技术栈中的 第三层抽象：

 这种分层意味着：DeepAgents 的源码实现大量委托给 LangGraph 的基础能力（如状态管理、节点编排、中断机制），而自身聚焦于 Harness 层的能力编排——即如何将文件系统、子代理、记忆、技能等高级特性以标准化的方式注入 Agent 的执行循环。

1.3 核心能力全景

官方文档将 DeepAgents 的能力划分为五大维度：

第二章：Agent Harness 执行引擎深度剖析

2.1 create_deep_agent：入口函数与初始化流水线

create_deep_agent 是整个框架的 工厂函数，其签名隐藏了复杂的初始化逻辑。从源码层面分析，该函数执行以下流水线：

# 伪代码还原核心初始化流程defcreate_deep_agent(    model: str,                          # 模型标识符，如 "anthropic:claude-sonnet-4-6"    tools: list[Callable] = None,         # 用户自定义工具列表    system_prompt: str = None,            # 基础系统提示词    memory: list[str] = None,             # AGENTS.md 文件路径列表    skills: list[str] = None,             # 技能目录路径列表    middleware: list[Middleware] = None,  # 自定义中间件    subagents: list[SubAgentSpec] = None, # 自定义子代理    interrupt_on: dict = None,            # HITL 中断配置    permissions: list[PermissionRule] = None, # 文件权限规则    backend: FilesystemBackend = None,    # 文件系统后端    harness_profile: str = None,          # Harness Profile 名称) -> CompiledStateGraph:

初始化流水线五阶段：

1. 模型解析阶段: 解析 provider:model 格式，加载对应的 LangChain ChatModel。这里使用了延迟加载策略，确保仅在首次调用时才初始化模型客户端。

2. 后端初始化阶段: 若未提供 backend，默认创建 StateBackend（基于 LangGraph 的 Store）。后端负责所有虚拟文件系统的读写、持久化及跨 session 状态共享。

3. Harness Profile 应用阶段: 根据模型名称或显式传入的 profile，加载对应的 HarnessProfile。Profile 中定义了默认工具集、中间件栈、排除项等。这一步是框架 "opinionated" 特性的集中体现——不同模型会获得不同的默认配置。

# openai.yamlbase_system_prompt:Youarehelpful.system_prompt_suffix:Respondbriefly.excluded_tools:-execute-grepexcluded_middleware:-SummarizationMiddleware-my_pkg.middleware:TelemetryMiddlewaregeneral_purpose_subagent:enabled:false

1. 中间件栈组装阶段: 构建默认中间件栈 [FilesystemMiddleware, SummarizationMiddleware, SubAgentMiddleware, MemoryMiddleware, SkillMiddleware]，并将用户自定义中间件按序插入。中间件采用 洋葱模型 执行，每一层均可读取/修改上下文。

2. 图编译阶段: 将所有组件编译为 LangGraph 的 CompiledStateGraph。此时，tool schema、system prompt 组装、interrupt handlers 均被固化到图中。

2.2 Tool Calling Loop：执行循环源码实现

DeepAgents 的核心执行循环继承自 LangGraph，但因中间件的注入而产生了本质差异。其执行循环可描述为：

关键源码设计点：

1. 消息格式标准化: DeepAgents 内部统一使用 LangChain 的 BaseMessage 子类（SystemMessage, HumanMessage, AIMessage, ToolMessage）。在中间件介入前，所有消息经过 MessageNormalizer 进行格式校验。

2. 工具 Schema 生成: 通过 Python 类型注解和 docstring 反射，自动生成符合 OpenAI/Anthropic 标准的 tool schema。DeepAgents 额外支持 复合工具——即一个 Python 函数对应多个逻辑工具视角。

3. 流式事件模型: 不同于传统的字符串流，DeepAgents 输出的是 结构化事件流（AgentEvent），事件类型包括：

• message: LLM 生成的消息片段

• tool_call: 工具调用请求

• tool_result: 工具执行结果

• value: 中间计算值或状态更新

• subagent: 子代理委派事件

这种设计支持上层应用对 Agent 行为进行细粒度的实时观测与干预。

2.3 Streaming 架构与事件投影

agent.stream() 返回的并非原始字节流，而是一个 类型化投影（Typed Projection） 生成器。源码中实现了 EventProjector 类，负责将底层 LangGraph 的 state updates 映射为高层语义事件。

# 概念性源码结构classEventProjector:defproject(self, state_update: StateSnapshot) -> Iterator[AgentEvent]:for node_name, node_output in state_update.items():if node_name == "agent":yieldfromself._project_messages(node_output)elif node_name.startswith("tools:"):yieldfromself._project_tool_results(node_output)elif node_name == "subagent":yieldfromself._project_subagent_events(node_output)

对于子代理，stream.subagents 提供了独立的事件句柄，使得主代理的流与子代理的流互不阻塞，实现真正的并行可视化。

第三章：提示词上下文工程设计

3.1 提示词架构的四层模型

DeepAgents 的系统提示词并非单一字符串，而是经过 四层组装 的复合结构：

3.2 静态提示词设计原理

静态提示词（Layer 1-2）具有以下工程特性：

• 可缓存性: 对于 Anthropic Claude 和 Amazon Bedrock 模型，DeepAgents 自动应用 prompt caching，标记静态段落的 cache_control 点。这意味着在多轮对话中，Layer 1-2 的 token 无需重复计算，显著降低延迟与费用。

• 版本控制友好: 静态提示词通常存储在独立的 prompt 模板文件中（或通过 system_prompt 参数传入），便于 A/B 测试与版本管理。

• 结构化注入: 框架通过 PromptAssembler 类将静态提示词与动态上下文拼接，确保格式一致性。源码中使用了 Jinja2 类似的模板语法，支持条件渲染与循环。

3.3 动态提示词生成机制

动态提示词（Layer 3-4）的生成涉及多个中间件的协作：

1. MemoryMiddleware 在每次模型调用前，从后端读取 AGENTS.md 文件并将其内容注入系统提示词。若记忆文件被标记为 auto_update，代理还可根据交互历史追加新的偏好记录。

2. SkillMiddleware 采用 渐进式披露（Progressive Disclosure）：仅加载技能目录下的 SKILL.md 的 frontmatter 到启动上下文；当代理检测到需要使用某技能时，才动态读取完整内容。这种设计避免了启动上下文爆炸。

3. SummarizationMiddleware 在上下文接近 token 阈值时，自动将早期对话历史压缩为摘要，并将原始历史卸载到文件系统的 .context/ 目录下。摘要本身作为动态提示词的一部分重新注入。

3.4 Prompt Caching 策略源码分析

Prompt caching 的实现位于 PromptCachingMiddleware（官方集成）：

# 概念性实现classPromptCachingMiddleware:defprocess_system_prompt(self, messages: list[SystemMessage]) -> list[SystemMessage]:ifself.provider in ["anthropic", "bedrock"]:# 在最后一个静态消息附加 cache_control            messages[-1].additional_kwargs["cache_control"] = {"type": "ephemeral"}return messages

策略细节：

• Anthropic 模型：在 system prompt 最后一个静态内容块后插入 cache_control 标记；首次调用后的多轮交互中，该前缀自动命中缓存。

• 其他模型：通过 provider-specific 的 caching middleware 实现，或退化为无缓存模式。

• 缓存失效：当 memory/skills 文件发生更新时，框架自动触发缓存失效与重新加载。

QWN系列的 cache 实现示例

https://help.aliyun.com/zh/model-studio/context-cache^[1]

class DashScopeContextCacheMiddleware(AgentMiddleware):"""Middleware for caching context in DashScope API.    Please refer to https://help.aliyun.com/zh/model-studio/context-cache    for more details.    Example:        ```python        from langchain_qwq.middleware import DashScopeContextCacheMiddleware        ```    """defwrap_model_call(self,request:ModelRequest,handler:Callable[[ModelRequest],ModelResponse])->ModelCallResult:messages=request.state.get("messages", [])message=messages[-1]request=request.override(messages=[*messages[:-1],message.model_copy(update={"content": [                            {"type":"text","text":message.content,"cache_control": {"type":"ephemeral"},                            }                        ]}),])returnhandler(request)

生产级 Agent 的 system prompt 必须被当作架构问题处理，而非文案问题。DeepAgents 官方实现遵循了业界在 Claude Code 等项目中验证的分层模型，将 system prompt 拆解为五个层次（Layer 1-5），每一层拥有独立的稳定性等级、变更周期与缓存策略。

Layer 1：Base Personality（基础人格层）

这是 Agent 最核心的身份定义：你是谁、你的基本行为准则、沟通风格。DeepAgents 默认的基础人格通常包含在 profiles/ 下针对不同模型的 provider 提示词文件中（例如 Anthropic 模型的 base prompt）。这一层极少变化，可能整个产品生命周期只改动数次。

Layer 2：Role Instructions（角色指令层）

在基础人格之上，根据应用场景定义专业角色。例如编程助手、研究助理、数据分析专家等。DeepAgents 支持通过 system_prompt 参数传入用户自定义的角色指令，框架会将其与 SDK 默认的角色指令进行拼接。这一层的变更频率高于人格层，但仍属于准静态内容。

Layer 3：Tool Definitions（工具定义层）

描述 Agent 可以使用哪些工具、每个工具的参数格式和使用约束。DeepAgents 的中间件（如 FileSystemMiddleware、SkillsMiddleware）会在构造阶段将内置工具和调用方自定义工具的 schema 注入到系统提示词中。工具层是半动态的：工具集合可能随用户配置或权限变化，但工具本身的描述文本是相对稳定的。

Layer 4：Context Injection（上下文注入层）

这是真正动态的部分。每次对话前，系统根据当前状态注入上下文：当前日期、操作系统信息、工作目录、git 状态、项目结构、可用技能列表、内存摘要等。在 DeepAgents 中，这一层由 EnvironmentMiddleware（或类似功能的内置逻辑）在 before_model 阶段生成并追加到 system prompt。

Layer 5：Dynamic Rules（动态规则层）

最顶层，根据特定条件触发。例如 AGENTS.md / CLAUDE.md 文件中的项目级指令、用户偏好配置、会话级临时规则等。这一层最灵活，也最容易与底层指令冲突，因此需要优先级裁决机制。

3.5 可缓存性：Prompt Caching 与 cache_control

对于生产级 Agent 而言，system prompt 往往占据大量 token（可达 10k-30k 以上）。如果多轮对话中每次都重复发送完全相同的静态文本，既浪费成本又增加延迟。DeepAgents 针对 Anthropic Claude 和 Amazon Bedrock 等支持 prompt caching 的模型，实现了自动缓存标记机制。

核心原理：在构造 system prompt 时，框架将 Layer 1（Base Personality）和 Layer 2（Role Instructions）标记为静态段落，并在调用模型底层 API 时，为这些静态段落附加 cache_control 标记点。以 Anthropic Claude 为例，其 Messages API 支持在消息内容的 content 数组元素上设置 {"type": "text", "text": "...", "cache_control": {"type": "ephemeral"}}。被标记的文本块在首次请求后会被模型提供商缓存，后续请求中只要该块内容不变，就无需重复计算 token，可直接命中缓存。

DeepAgents 的实现路径（基于 ARCHITECTURE.md 及社区源码分析推断）：

• 缓存策略决策点：profiles/ 目录下的 provider-specific profile 文件。当检测到模型属于 Anthropic 系列或 Amazon Bedrock 时，profile 会激活 prompt caching 行为。

• 标记注入点：在 graph.py 或 prompt 组装相关函数中，静态段落（SDK 默认 system prompt 模板 + profile 文本 + 用户传入的 system_prompt）在最终序列化前被打上 cache_control 点。由于社区源码分析指出静态提示词"自动应用 prompt caching"，可以合理推断框架在 _build_system_prompt() 或等效函数内部，构造完静态层后通过 provider adapter 附加缓存标记。

• 具体代码位置推断：

• libs/deepagents/src/deepagents/profiles/anthropic.py（或类似命名的 profile 文件）：负责 Anthropic 模型的 harness adjustment，包含对 cache_control 的支持开关。

• libs/deepagents/src/deepagents/graph.py 中负责 "Composes the system prompt (from caller instructions, SDK defaults, and profile text)" 的构造逻辑：在此处静态层被拼接后，调用 provider profile 的方法注入缓存标记。

缓存带来的工程收益：

1. 延迟降低：多轮对话中，静态段落的处理时间从数百毫秒降至接近零。

2. 成本降低：按 token 计费的模型提供商通常对缓存命中部分收取更低费用（例如 Anthropic 缓存写操作按标准价收费，缓存读操作价格显著降低）。

3. 稳定性提升：静态层的确定性输出减少了因 prompt 微小变动导致的模型行为漂移。

3.6 版本控制友好性

静态提示词（Layer 1-2）通常存储在独立的 prompt 模板文件中，或通过 system_prompt 参数传入。DeepAgents 的设计使得这些文本天然适合版本控制：

• 文件化存储：框架不鼓励将 system prompt 硬编码在业务代码中，而是建议通过 .md 模板文件 + 配置中心/文件系统加载。AGENTS.md、CLAUDE.md 等文件模式就是这一思想的体现。

• A/B 测试支持：由于 system prompt 的组装发生在 create_deep_agent() 阶段，应用层可以通过传入不同的 system_prompt 或切换不同的 profile 轻松实现 prompt 的 A/B 测试，而无需改动核心代码。

• 审计与回滚：prompt 作为文本资产纳入 Git 管理后，每次变更都有 diff、commit message、code review，出现问题时可快速回滚到历史版本。

3.7 结构化注入：PromptAssembler 与模板引擎

PromptAssembler 是 DeepAgents 中负责将多层 prompt 拼接为最终字符串（或消息数组）的核心类/模块。

职责边界：

• 接收来自各中间件、profile、用户输入的 prompt 片段。

• 按照固定优先级和顺序（Layer 1 → 2 → 3 → 4 → 5）进行排列。

• 处理分隔符设计（如 XML 标签、Markdown 标题），帮助模型区分不同层次。

• 对支持缓存的模型，在合适的边界点插入 cache_control。

• 执行模板渲染（条件渲染、循环、变量插值）。

模板语法支持：社区源码分析指出，DeepAgents 在 prompt 组装过程中使用了 Jinja2 类似的模板语法。这意味着：

• 中间件可以通过条件渲染（{% if condition %}）动态决定某段 prompt 是否出现。

• 工具列表可以通过循环（{% for tool in tools %}）批量生成描述文本。

• 变量插值（{{ variable }}）将运行时状态（如当前目录路径）注入到 prompt 模板中。

具体代码位置推断：

• libs/deepagents/src/deepagents/graph.py：官方 ARCHITECTURE.md 将 graph.py 列为 "Agent construction, middleware ordering, prompt assembly, default model behavior" 的核心文件。PromptAssembler 类或其等效函数应位于此文件中，或从此文件中导入。

• libs/deepagents/src/deepagents/middleware/_prompt.py（或类似中间件内部文件）：社区文章中提到的 wrap_model_call 等机制在此处将动态上下文附加到 system_prompt。

模板组装的工程细节：

1. 条件化加载：并非所有模块在所有场景下都需要。例如，如果当前工作目录不是 git 仓库，Git Protocols 模块就不应被加载，否则浪费 token。PromptAssembler 在拼接前会评估每个片段的激活条件。

2. 顺序敏感性：大模型对 prompt 中信息的位置高度敏感（首因效应与近因效应）。PromptAssembler 将最关键的人格定义和角色指令放在开头，动态上下文居中，临时规则靠后（但对某些需要强约束的场景，会把高优先级规则通过特殊前缀如 IMPORTANT: 置顶）。

3. 分隔符设计：DeepAgents 在 prompt 拼接时使用了清晰的视觉分隔。例如用 Markdown 标题 (# Role, # Tools, # Context) 或 XML 风格标签 (<system-reminder>, <env>, <skills>) 标注不同内容块，帮助模型理解结构边界。

4. Token 预算管理：PromptAssembler 在组装过程中会监控各层的 token 消耗。对于超长动态内容（如文件列表、git log），会实施截断和摘要策略，确保 system prompt 不超过预设上限（通常不超过上下文窗口的 15%-20%）。

第四章：记忆系统——长短期记忆架构深度解析

4.1 记忆系统的双轨设计

DeepAgents 的记忆系统采用 显式长期记忆 + 隐式短期记忆 的双轨架构：

4.2 AGENTS.md 规范与实现

AGENTS.md 是 DeepAgents 引入的一种标准化记忆文件格式，遵循 agents.md^[3] 规范：

# Agent Memory## Preferences- Output format: Markdown with code blocks- Communication style: Concise technical## Conventions- Use snake_case for Python variables- Always add type hints## Domain Knowledge- Project uses FastAPI + SQLAlchemy stack- Database migration managed by Alembic

源码实现要点：

1. 加载时机: MemoryMiddleware 在 create_deep_agent 初始化时读取所有 memory 参数指定的文件路径，内容被加载到 SystemMessage 中。文件内容变更通过后端的事件监听机制触发热重载。

2. 后端多样性: 记忆文件可存储于：

• StateBackend: 基于 LangGraph Store 的内存/持久化存储

• StoreBackend: 外部 KV store（如 Redis、PostgreSQL）

• FilesystemBackend: 本地磁盘或虚拟文件系统

3. 自动更新: 代理在完成任务后，可通过内置的 update_memory 工具（可选启用）分析本次交互，提取新的偏好或模式并写入 AGENTS.md。这一机制实现了 代理的自我改进（Self-Improvement）。

4.3 状态管理与 Checkpoint 机制

由于构建于 LangGraph 之上，DeepAgents 天然继承了其 checkpoint 持久化能力。每次模型调用和工具执行后，完整的状态快照（包括消息历史、待办列表、文件系统状态）被序列化并写入配置的 saver（默认为内存，生产环境使用 PostgreSQL 或 Redis）。

这意味着：即使代理执行过程中断（服务重启、人为停止），也可从最后一个 checkpoint 精确恢复，实现 中断与恢复（Interrupt & Resume） 的原子性保证。

第五章：技能系统（Skills）工程化

5.1 Agent Skills 标准

DeepAgents 的技能系统遵循 agentskills.io^[4] 标准，每个技能是一个自包含目录：

skills/└── web_research/    ├── SKILL.md          # 技能元数据 + 完整指令    ├── templates/    │   └── report_template.j2    ├── scripts/    │   └── fetch_sources.py    └── references/        └── search_api_guide.md

5.2 SKILL.md 的结构与渐进式加载

SKILL.md 采用 frontmatter + body 的结构：

---name: web_researchversion: 1.0.0triggers: ["research", "lookup", "investigate"]description: Conduct structured web research and compile reports---## InstructionsWhen the user asks for research on a topic:1. Break down the topic into 3-5 sub-questions2. Use search tools for each sub-question3. Synthesize findings into a structured report

渐进式加载机制（源码级）：

classSkillMiddleware:def__init__(self, skill_dirs: list[str]):self.skill_registry = {}fordirin skill_dirs:            skill = Skill.load(dir)  # 仅加载 frontmatterself.skill_registry[skill.name] = skilldefon_trigger(self, trigger_word: str, context: Context):        matching_skills = [s for s inself.skill_registry.values() if trigger_word in s.triggers]for skill in matching_skills:            full_content = skill.load_full_content()  # 懒加载完整内容            context.inject_skill_prompt(full_content)

这种设计的工程价值在于：启动时仅扫描元数据，保持启动上下文紧凑；运行时按需加载，避免无关技能的 token 浪费。

5.3 技能生态系统

DeepAgents 支持 skills 的组合与继承：

• 技能组合: 一个任务可同时激活多个技能，它们的指令按优先级排序后合并。

• 技能版本: 通过 Semantic Versioning 管理技能迭代，支持向后兼容。

• 技能市场: 技能作为可分发单元，可通过 Git 子模块、pip 包或专用 registry 共享。

第六章：工具系统与 MCP 集成

6.1 Tool Registry 与 Schema 生成

DeepAgents 的工具注册中心在初始化时构建：

classToolRegistry:def__init__(self):self._tools: dict[str, BaseTool] = {}defregister(self, tool: Callable | BaseTool):ifcallable(tool):            tool = StructuredTool.from_function(tool)  # 自动 schema 生成self._tools[tool.name] = tooldefget_schemas(self) -> list[dict]:return [t.get_schema() for t inself._tools.values()]

Schema 生成深度：通过 inspect.signature 解析函数签名，typing 模块解析类型，docstring 提取描述。DeepAgents 对复杂类型（Pydantic models、TypedDict、Enum）提供了一阶支持，确保生成的 JSON Schema 严格符合模型提供商的约束。

6.2 模型上下文协议（MCP）支持

DeepAgents 是 LangChain 生态中最早完整支持 MCP（Model Context Protocol） 的框架之一：

from mcp import ClientSession# 连接 MCP Server 并将其工具注入代理mcp_tools = await load_mcp_tools("https://mcp-server.example.com/sse")agent = create_deep_agent(    model="openai:gpt-5.5",    tools=[*custom_tools, *mcp_tools],)

MCP 的价值在于标准化了工具发现与调用协议，使得 DeepAgents 可以无缝接入数据库、API、文件系统等外部能力，而无需为每个集成编写 adapter。

6.3 内置工具集

除用户自定义工具和 MCP 工具外，DeepAgents 提供丰富的内置工具：

第七章：中间件（Middleware）架构——框架的灵魂

7.1 中间件模型：洋葱管道

Middleware 是 DeepAgents 最具架构价值 的设计。所有高级能力（文件系统、子代理、摘要、记忆、技能）均以中间件形式实现，而非硬编码在核心循环中。

# 洋葱模型执行伪代码asyncdefexecute_with_middlewares(state, middlewares):# 正向：Pre-processingfor mw in middlewares:        state = await mw.pre_process(state)# 核心执行    result = await core_loop(state)# 逆向：Post-processingfor mw inreversed(middlewares):        result = await mw.post_process(result)return result

7.2 默认中间件栈解析

create_deep_agent 的默认中间件栈（按执行顺序）：

1. FilesystemMiddleware: 虚拟文件系统操作、权限检查、多模态文件识别

2. SummarizationMiddleware: 上下文长度监控、自动摘要、历史卸载

3. SubAgentMiddleware: 子代理生命周期管理、任务委派与结果回传

4. MemoryMiddleware: AGENTS.md 加载与自动更新

5. SkillMiddleware: 技能注册、触发检测与指令注入

7.3 FilesystemMiddleware 深度源码分析

这是框架中最复杂的中间件，负责所有与文件相关的交互：

初始化阶段：

classFilesystemMiddleware:def__init__(self, backend: FilesystemBackend, tools: list[str] = None):self.backend = backendself.enabled_tools = tools or ["ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep"]# 权限验证层初始化self.permission_checker = PermissionChecker()

工具调用拦截：当 LLM 调用 write_file 时，中间件执行：

1. 解析目标路径

2. 检查 permissions 规则（first-match-wins）

3. 若通过，调用后端写入

4. 若后端为 SandboxBackendV2，触发 execute 的额外安全检查

5. 记录 telemetry 事件到 LangSmith

多模态支持：read_file 根据文件扩展名（.png, .mp4, .pdf 等）自动返回多模态内容块（ImageBlock, VideoBlock）而非纯文本，使模型能够 "看到" 非文本文件。

7.4 SubAgentMiddleware 实现详解

子代理的中间件实现了 "代理创建代理" 的元能力：

classSubAgentMiddleware:asyncdefhandle_tool_call(self, tool_call: ToolCall, context: Context):if tool_call.name == "task":# 解析任务描述与配置            task_spec = TaskSpec.from_args(tool_call.arguments)# 创建子代理实例：继承父代理部分配置，但隔离上下文            subagent = create_deep_agent(                model=context.model,  # 可继承或自定义                system_prompt=task_spec.system_prompt,                tools=self._filter_tools_for_subagent(task_spec),                backend=self._create_isolated_backend(),  # 隔离文件系统视图            )# 在独立上下文窗口中执行            result = await subagent.ainvoke(task_spec.messages)# 仅返回最终报告，卸载过程上下文return TaskResult(report=result["output"])

关键设计点：

• 上下文隔离: 子代理拥有独立的 message history，不污染父代理的上下文。

• 后端隔离: 默认创建隔离的文件系统视图，但可通过配置共享特定目录。

• 结果压缩: 子代理完整执行轨迹（可能数百轮）被压缩为单条 TaskResult，父代理仅看到最终结果，极大节省 token。

• 并行执行: SubAgentMiddleware 支持并发启动多个子代理，通过 asyncio.gather 实现并行化。

7.5 自定义中间件开发

开发者可轻松扩展中间件：

from deepagents.middleware import MiddlewareclassAuditLogMiddleware(Middleware):asyncdefpre_process(self, state: AgentState) -> AgentState:# 记录每次模型调用的输入 token 数self.logger.info(f"Input tokens: {estimate_tokens(state.messages)}")return stateasyncdefpost_process(self, result: AgentResult) -> AgentResult:# 记录工具调用次数与耗时self.logger.info(f"Tool calls: {len(result.tool_calls)}, latency: {result.latency_ms}ms")return result

通过 middleware=[..., AuditLogMiddleware()] 注入即可生效。

第八章：文件系统与权限控制

8.1 虚拟文件系统后端架构

DeepAgents 的文件系统采用 策略模式（Strategy Pattern） 实现后端解耦：

classFilesystemBackend(ABC):    @abstractmethodasyncdefread(self, path: str, offset: int = 0, limit: int = None) -> str | bytes: ...    @abstractmethodasyncdefwrite(self, path: str, content: str | bytes) -> None: ...    @abstractmethodasyncdeflist(self, path: str) -> list[FileInfo]: ...

内置后端实现：

8.2 权限规则引擎

权限系统采用 声明式规则 + 优先级匹配：

permissions = [    PermissionRule(operations=["read"], paths=["/workspace/**"], mode="allow"),    PermissionRule(operations=["write"], paths=["/workspace/src/**"], mode="allow"),    PermissionRule(operations=["write"], paths=["/workspace/.env"], mode="deny"),]

评估逻辑：

1. 按声明顺序从上到下匹配

2. 首个匹配的规则生效（first-match-wins）

3. 无匹配时默认允许（fail-open 但可配置为 fail-close）

安全边界：权限规则仅约束内置文件系统工具。对于 execute 工具（shell 命令），权限无效，因此生产环境应通过 sandbox 后端强制隔离。

8.3 代码执行沙箱

DeepAgents 支持两种代码执行模式：

1. Sandbox 执行（execute）: 基于 Docker 或 firecracker 的完整 OS 沙箱。支持包安装、CLI 调用、网络访问（可配置）。后端实现 SandboxBackendProtocolV2。

2. 解释器执行（eval）: 嵌入式 QuickJS 运行时，仅支持 JavaScript。无文件系统、网络或 shell 访问，用于轻量级数据转换与确定性脚本。

第九章：委派与子代理（Subagents）

9.1 任务规划：write_todos

write_todos 是框架提供的结构化任务跟踪工具：

# 工具 schema{"name": "write_todos","parameters": {"todos": [      {"id": "1", "description": "Research API endpoints", "status": "in_progress"}    ]  }}

任务状态 (pending, in_progress, completed) 持久化于 Agent State 中，形成轻量级的计划层。源码中 TodoManager 类负责状态的增删改查，并在每次状态变更时触发 on_todo_changed 钩子。

9.2 Subagent 生命周期

：

• Fresh Context: 每个 task 调用创建全新实例，无历史包袱。

• Autonomous Execution: 子代理独立运行至完成，期间父代理不干预。

• Single Handoff: 仅返回一次最终结果，不支持双向持续通信。

• Stateless: 子代理执行结束后状态丢弃，结果通过返回值传递。

9.3 动态子代理与自定义配置

开发者可定义 声明式子代理：

custom_subagent = DeclarativeSubAgent(    name="code_reviewer",    system_prompt="You are a strict code reviewer focusing on security...",    tools=["read_file", "grep"],    model="anthropic:claude-sonnet-4-6",    permissions=[        PermissionRule(operations=["read"], paths=["/workspace/src/**"], mode="allow")    ])agent = create_deep_agent(    model="openai:gpt-5.5",    subagents=[custom_subagent],)

声明式子代理支持独立的权限、工具集与模型选择，实现 最小权限原则（PoLP） 的委派。

第十章：人类在环（HITL）与中断恢复

10.1 LangGraph Interrupt 集成

DeepAgents 的 HITL 并非独立实现，而是深度集成 LangGraph 的 interrupt 机制：

agent = create_deep_agent(    model="anthropic:claude-sonnet-4-6",    interrupt_on={"edit_file": True,        # 每次编辑前暂停"write_file": {"paths": ["*.py"]},  # 仅对 Python 文件写入暂停"execute": True,          # 执行 shell 前暂停    })

中断执行流程：

1. LLM 生成 edit_file 工具调用

2. interrupt_before 触发，执行流程挂起

3. 状态持久化到 checkpoint

4. 通过 UI/API 向人类展示：工具名、参数、变更预览

5. 人类选择："Approve" / "Edit" / "Reject"

6. 若 Edit，修改参数后注入修改后的调用

7. 流程从 checkpoint 恢复，继续执行

10.2 中断恢复的原子性

由于基于 LangGraph 的 checkpoint 机制，中断恢复具有以下保证：

• Exactly-once: 已批准的调用不会重复执行

• State Consistency: 恢复后的状态与中断前完全一致

• Resume Anytime: 中断可持续任意时长（分钟、小时、天），不受进程生命周期限制

10.3 运行时审批的工程实践

生产环境中，HITL 通常通过 LangGraph Server 的 REST API 暴露：

# 异步检查中断状态asyncdefcheck_interrupts(thread_id: str):    status = await client.runs.get_status(thread_id)if status == "interrupted":        interrupt_data = await client.runs.get_interrupts(thread_id)returnawait render_approval_ui(interrupt_data)

这种设计使 DeepAgents 可轻松集成到企业审批工作流中。

第十一章：多模态集成

11.1 多模态文件输入

read_file 工具自动识别多模态文件扩展名，返回对应的内容块类型：

# 内部实现逻辑（概念性）defread_file(path: str) -> list[ContentBlock]:    ext = Path(path).suffix.lower()    content = backend.read(path)if ext in IMAGE_EXTS:return [ImageBlock(data=content, mime_type=f"image/{ext.lstrip('.')}")]elif ext in VIDEO_EXTS:return [VideoBlock(data=content)]elif ext in AUDIO_EXTS:return [AudioBlock(data=content)]elif ext in DOC_EXTS:return [DocumentBlock(data=content, format=ext)]else:return [TextBlock(text=content.decode('utf-8'))]

11.2 多模态上下文管理

多模态内容在上下文中的处理面临特殊挑战：

• Token 计数: 图像/视频/音频的 token 估算需调用模型特定的 vision tokenizer

• 上下文卸载: 大型媒体文件不适合长期保留在 prompt 中；DeepAgents 的策略是保留引用（文件路径）而非原始内容，在需要时重新 read_file

• Summarization: 当前摘要对文本有效，多模态摘要依赖模型能力（如 Gemini 的视频理解）

第十二章：Harness Profile 与配置标准化

12.1 Profile 注册机制

HarnessProfile 是一套面向模型/场景的预设配置：

from deepagents import HarnessProfile, register_harness_profileregister_harness_profile("anthropic:claude-sonnet-4-6",    HarnessProfile(        excluded_tools=frozenset({"execute"}),  # 默认禁用 shell        max_iterations=50,        summarization_threshold=12000,    ))

源码中 ProfileRegistry 维护了 model_pattern -> HarnessProfile 的映射，支持通配符匹配。

12.2 排除工具与中间件

Profile 与运行时参数支持精细化控制：

• excluded_tools: 从模型可见的工具列表中移除特定工具（但中间件仍保留）

• excluded_middleware: 从默认栈中移除中间件（危险操作，如移除 FilesystemMiddleware 会被框架拒绝）

• tools allowlist: 仅暴露文件工具子集（如只读代理）

12.3 结合配置中心的标准化工程

在企业级部署中，建议将 Profile 外置到配置中心：

# config/profiles.yamlprofiles:production:model:"anthropic:claude-sonnet-4-6"excluded_tools: ["execute"]permissions:- { paths: ["/data/**"], operations: ["read"], mode:"allow" }interrupt_on:edit_file:truewrite_file:trueresearch:model:"openai:gpt-5.5"skills: ["web_research", "data_analysis"]subagents:-name:"fact_checker"model:"anthropic:claude-haiku-4-6"

通过 Hydra 或 Pydantic-Settings 加载配置，实现 环境隔离 + 版本控制 + 动态更新。

第十三章：异步 Agent 与并发控制

13.1 异步执行模型

DeepAgents 提供 invoke（同步）与 ainvoke（异步）两种 API。底层基于 asyncio：

asyncdefainvoke(self, input: dict) -> AgentResult:# 创建 LangGraph 异步运行器asyncfor event inself.compiled_graph.astream(input):yieldself.event_projector.project(event)

异步优势：

• 子代理并行委派

• MCP 工具异步 IO

• 流式响应非阻塞

13.2 并发安全

当多个请求共享同一 Agent 实例时，需注意：

• State Isolation: 每次 invoke 创建独立的 StateGraph thread，状态互不干扰

• Backend Concurrency: 文件系统后端需考虑并发写入冲突（StateBackend 天然线程安全，FilesystemBackend 依赖 OS 锁）

• Rate Limiting: 框架不内置 LLM 调用的速率限制，需在上游或模型客户端层实现

第十四章：上下文管理——Summarization & Offloading 源码实现

14.1 压缩算法与策略

SummarizationMiddleware 实现了智能上下文压缩：

classSummarizationMiddleware:def__init__(self, threshold: int = 12000, target: int = 6000):self.threshold = threshold  # 触发压缩的 token 阈值self.target = target        # 压缩后的目标 token 数asyncdefpre_process(self, state: AgentState) -> AgentState:        current_tokens = estimate_tokens(state.messages)if current_tokens > self.threshold:# 保留最近的 N 条消息（通常为系统提示 + 最近 2-3 轮）            preserved = self._get_preserved_messages(state.messages)            to_summarize = state.messages[len(preserved):-3]  # 早期历史            summary = awaitself._generate_summary(to_summarize)# 将原始历史卸载到文件awaitself.backend.write(".context/history_001.md", self._format_history(to_summarize))# 替换为摘要消息            state.messages = preserved + [SystemMessage(content=f"Previous context summary: {summary}")]return state

压缩策略细节：

• 保留轮数: 最近 2-3 轮完整对话保留，确保当前任务上下文不丢失

• 摘要质量: 调用 LLM（通常使用较快的模型如 Haiku 或轻量级本地模型）生成结构化摘要，包含关键决策、工具调用结果和待办状态

• 卸载格式: 原始消息以 Markdown 格式写入 .context/ 目录，包含时间戳与元数据

14.2 Token 预算管理

框架维护 三级 token 预算：

1. 模型上下文上限: 如 200K tokens（Claude 3.5）

2. Harness 压缩阈值: 默认 75% 上限（如 150K）

3. 单次调用预算: 通过 tool result 截断限制单次工具输出

第十五章：安全架构

15.1 安全模型：Trust the LLM？

DeepAgents 明确遵循 "Trust the LLM" 安全模型：

• 代理的能力边界由其可用工具决定

• 安全 enforcement 发生在工具/沙箱层，而非期望模型自律

• 权限系统提供声明式边界，但不应被视为唯一防线

15.2 多层安全防御

15.3 安全最佳实践

1. 生产环境始终使用 SandboxBackend 执行代码

2. 敏感文件（.env, secrets/, .ssh/）默认加入 deny 规则

3. execute 工具必须通过 HITL 审批

4. 定期审查 LangSmith trace，识别异常工具调用模式

第十六章：自动化评估体系

16.1 评估框架集成

DeepAgents 原生支持 LangSmith 评估：

from langsmith import Client# 定义评估指标@evaluatordeftool_accuracy(example, run) -> dict:    expected_tools = example.outputs["expected_tools"]    actual_tools = [tc["name"] for tc in run.outputs["tool_calls"]]return {"score": len(set(expected_tools) & set(actual_tools)) / len(expected_tools),"comment": f"Expected: {expected_tools}, Got: {actual_tools}"    }# 批量评估client.run_on_dataset(    dataset_name="deepagent_eval_set",    llm_or_chain_factory=agent_factory,    evaluators=[tool_accuracy, response_quality],)

16.2 评估维度设计

针对 DeepAgents 的特性，建议的评估维度：

16.3 Harness Engineering 评估

社区提出的 Harness Engineering 方法论强调：不更换模型，通过优化 harness（系统提示词、工具集、中间件配置）提升代理性能。DeepAgents 的 Profile 与中间件体系正是 Harness Engineering 的实践载体。评估 harness 改进的效果需建立稳定的 benchmark suite（如 TerminalBench, SWE-bench）。

第十七章：集成协议与扩展性

17.1 配置中心集成方案

企业级部署中，DeepAgents 推荐与配置中心（如 Nacos）集成：

from deepagents import create_deep_agentfrom config_center import ConfigClientconfig = ConfigClient(pull_interval=30)  # 30秒刷新@config.on_change("agent.profile.production")defreload_profile(new_config):global agent    agent = create_deep_agent(        model=new_config.model,        permissions=new_config.permissions,        interrupt_on=new_config.interrupt_on,    )

17.2 自定义扩展点

DeepAgents 提供丰富的扩展接口：

17.3 生态系统集成

• LangSmith/opik: 全链路 tracing、评估、监控

• LangGraph Platform: 部署为 REST API / WebSocket 服务

• MCP Ecosystem: 接入数据库、浏览器、文档处理等 hundreds of servers

• Docker / Kubernetes: 容器化沙箱部署

第十八章：工程化最佳实践总结

18.1 标准化工程方案

基于全文的分析，推荐以下标准化工程结构：

project/├── agents/│   ├── __init__.py│   ├── main_agent.py          # create_deep_agent 封装│   ├── profiles.yaml          # Harness Profile 定义│   └── subagents/│       ├── code_reviewer.py│       └── test_generator.py├── skills/│   ├── web_research/SKILL.md│   └── data_analysis/SKILL.md├── memory/│   └── AGENTS.md              # 项目级记忆├── tools/│   ├── internal_api.py│   └── db_query.py├── permissions/│   └── production.yaml        # 权限规则├── config/│   ├── development.yaml│   └── production.yaml├── tests/│   ├── test_agent.py│   └── eval_dataset.jsonl└── Dockerfile                 # 沙箱镜像

参考文献与资源

• DeepAgents 官方文档: https://docs.langchain.com/oss/python/deepagents/overview^[5]

• DeepAgents GitHub: https://github.com/langchain-ai/deepagents^[6]

• LangGraph 文档: https://langchain-ai.github.io/langgraph/^[7]

• MCP 协议规范: https://modelcontextprotocol.io/^[8]

• Agent Skills 标准: https://agentskills.io/^[9]

• AGENTS.md 规范: https://agents.md/^[10]

引用链接