深度智能体框架DeepAgent剖析

当我们谈论 AI Agent 时，大多数开发者想到的是一个简单的工具调用循环：LLM 生成工具调用，执行工具，将结果返回给 LLM，继续下一轮。这种浅层架构在处理简单任务时表现良好，但面对复杂的多步骤工作流时，就会暴露出致命缺陷：无法有效规划、上下文管理混乱、缺乏质量审查机制。尽管有类似与Langgraph这样的工作流框架，能够免去开发者在编排workflow上面的耗时，但是Agent的核心能力，比如节点和工具，仍需要自行实现。

LangChain 团队研究了Claude Code、OpenAI Deep Research、Manus等真正在生产环境中解决复杂问题的系统，提炼出了四个关键的特征：

详细的系统提示词：包含工具使用指南和少样本示例的长提示。
规划工具 ：如Claude Code的Todo List，用于任务分解和进度追踪。
子智能体委托：将复杂任务拆分给专注的子智能体处理。
文件系统访问：作为共享工作空间和长期记忆的载体。

DeepAgent正是将这些特征进行抽象后，系统化、框架化的产物，它不是简单的工具调用循环，而是一个完整的Agent Harness，即智能体工具套件。

核心架构

什么是 Agent Harness

DeepAgent将自己定位为Agent Harness，它本质上仍是工具调用循环，但集成了让智能体深度思考 的核心能力。与传统框架不同，DeepAgent通过内置工具和能力，让开发者专注于业务逻辑，而非基础设施搭建。

模块化的中间件

DeepAgent采用可组合的中间件架构，每个中间件负责一个独立的能力域。

python 复制代码

from deepagents import create_deep_agent
from deepagents.middleware import TodoListMiddleware, FilesystemMiddleware, SubAgentMiddleware

# 默认情况下，create_deep_agent 会自动附加三大核心中间件
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    # 以下中间件会自动启用：
    # - TodoListMiddleware: 提供 write_todos 规划工具
    # - FilesystemMiddleware: 提供 6 个文件系统工具
    # - SubAgentMiddleware: 提供 task 工具用于子智能体委托
)

这种设计的优势在于可组合性，让开发者可以根据需求选择启用特定中间件，或添加自定义中间件扩展能力。

文件系统

六大文件系统工具

DeepAgent提供了完整的文件系统操作能力，这是其区别于浅层 Agent 的关键特性：

工具	功能	用途
`ls`	列出文件及元数据，包括大小和修改时间等	探索目录结构
`read_file`	读取文件内容，支持行号和分页	分块读取大文件
`write_file`	创建新文件	保存中间结果
`edit_file`	精确字符串替换	更新已有文件
`glob`	模式匹配查找文件	批量查找文件
`grep`	搜索文件内容	代码搜索，内容定位

自动压缩机制

当工具返回结果超出token阈值时，DeepAgent会自动将其转储到文件系统，防止上下文窗口饱和：

python 复制代码

# 伪代码示例：自动驱逐逻辑
def handle_tool_result(result, threshold=2000):
    if count_tokens(result) > threshold:
        file_path = f"/temp/tool_result_{uuid4()}.txt"
        write_file(file_path, result)
        return f"Large result saved to {file_path}. Use read_file to access."
    return result

这确保了即使调用返回海量数据的工具（如Web 搜索、数据库查询等），智能体也能通过文件系统分块读取，而不会导致上下文崩溃。

灵活的持久化策略

BackendProtocol 协议设计

DeepAgent将文件系统操作抽象为BackendProtocol协议，支持多种存储策略：

python 复制代码

from deepagents.backends import StateBackend, FilesystemBackend, StoreBackend, CompositeBackend

# 1. StateBackend：短期内存（默认）
agent = create_deep_agent()  # 文件存储在 LangGraph State 中

# 2. FilesystemBackend：本地磁盘持久化
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/Users/agent/workspace", virtual_mode=True)
)

# 3. StoreBackend：跨线程持久化（LangGraph Store）
from langgraph.store.memory import InMemoryStore
agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    store=InMemoryStore()
)

# 4. CompositeBackend：混合存储路由
composite = lambda rt: CompositeBackend(
    default=StateBackend(rt),  # 临时文件用 State
    routes={
        "/memories/": StoreBackend(rt),  # 长期记忆持久化
        "/workspace/": FilesystemBackend(root_dir="/real/path")  # 工作文件映射到磁盘
    }
)
agent = create_deep_agent(backend=composite, store=InMemoryStore())

路由策略示例

使用CompositeBackend时，不同路径前缀的文件会路由到不同的后端：

/workspace/plan.md → StateBackend（短期）
/memories/agent_context.txt → StoreBackend（跨会话持久化）
/docs/api_spec.yaml → FilesystemBackend（真实文件系统）

这种设计让智能体能够同时管理临时草稿和长期知识库。

子智能体机制

为什么需要子智能体

子智能体解决了上下文膨胀问题，实现任务委托与上下文隔离。当智能体使用大输出工具（如多次 Web 搜索）时，主智能体的上下文会迅速填满中间结果。子智能体通过隔离详细工作，让主智能体只接收最终结果，而非生成该结果的几十次工具调用。

两种定义方式

字典配置

python 复制代码

research_subagent = {
    "name": "research-agent",
    "description": "用于深度研究复杂问题",
    "system_prompt": "你是一个专业的研究助手，擅长多步骤信息收集和综合",
    "tools": [internet_search, summarize],
    "model": "openai:gpt-4o",  # 可选：覆盖主智能体模型
    "interrupt_on": {"internet_search": True}  # 可选：HITL 配置
}

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    subagents=[research_subagent]
)

编译图

对于复杂工作流，可以使用预构建的LangGraph图：

python 复制代码

from deepagents import CompiledSubAgent
from langgraph.graph import StateGraph

# 创建自定义图
def create_analysis_graph():
    workflow = StateGraph(...)
    # ... 构建复杂的分析流程
    return workflow.compile()

analysis_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="执行多步骤数据分析任务",
    runnable=create_analysis_graph()
)

agent = create_deep_agent(subagents=[analysis_subagent])

默认子智能体

除了用户定义的子智能体，DeepAgent始终提供一个general-purpose子智能体：

与主智能体相同的系统提示词和工具
主要用途：上下文隔离（而非专业化）
使用场景：主智能体可以将复杂任务委托给它，获得简洁结果而不受中间过程污染

python 复制代码

# 主智能体可以这样使用：
# "请使用 general-purpose 子智能体分析这 100 个文件，返回摘要"
# 子智能体完成工作后，主智能体只收到摘要，而非 100 次文件读取的详细内容

生产级特性

针对生产环境，DeepAgent还提供了许多有用的特性。

1. 对话历史自动摘要

当 token 使用量过高时，DeepAgent会自动压缩旧对话历史：

python 复制代码

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    # 配置摘要触发阈值和目标长度
)

2. 工具调用自动修复

当工具调用被中断或取消时，DeepAgent会自动修复消息历史：

问题场景 ：用户在工具执行过程中取消操作，导致tool_call消息没有对应的tool_result，破坏了消息序列的完整性。

解决方案 ：DeepAgent会自动注入占位符ToolMessage，确保消息历史的连贯性，避免 LLM 在后续轮次中因不完整的上下文而产生困惑。

3. Prompt缓存机制

对于使用Anthropic模型的智能体，DeepAgent启用了prompt caching功能：

自动标记可缓存的提示词部分（如系统提示词、工具定义）
减少重复 token 处理，显著降低成本和延迟
对于长系统提示词的深度智能体尤其有价值

4. Human-in-the-Loop

DeepAgent支持在特定工具调用时暂停执行，等待人工审批：

python 复制代码

from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[delete_file, send_email, read_file],
    interrupt_on={
        "delete_file": True,  # 需要审批（approve/edit/reject）
        "send_email": {"allowed_decisions": ["approve", "reject"]},  # 只能批准或拒绝
        "read_file": False  # 无需审批
    },
    checkpointer=MemorySaver()  # HITL 必须使用 checkpointer
)

# 使用示例
config = {"configurable": {"thread_id": "session-123"}}
result = agent.invoke({"messages": [...]}, config=config)

if result.get("__interrupt__"):
    # 处理中断，展示待审批操作
    interrupts = result["__interrupt__"][0].value
    action_requests = interrupts["action_requests"]
    
    # 用户决策
    decisions = [{"type": "approve"}]  # 或 "edit"、"reject"
    
    # 恢复执行
    result = agent.invoke(
        Command(resume={"decisions": decisions}),
        config=config  # 必须使用相同的 config
    )

总结

DeepAgent实现了从浅层Agent到深度Agent的范式转变，其核心价值在于将复杂任务自动化系统所需的核心能力封装为可组合、生产就绪的模块化中间件。

有了这些生产特性，无论是在构建研究助手、代码生成工具、数据分析平台还是智能客服系统，DeepAgent的设计模式都值得深入学习和应用。