深入浅出！用 DeepAgents 搭建高效能大模型应用（收藏版）

m0_48891301

181人浏览 · 2026-03-26 11:44:25

m0_48891301 · 2026-03-26 11:44:25 发布

随着 Agent 任务复杂度提升，上下文窗口限制与成本控制成为核心挑战。DeepAgents 是 LangChain 开源框架，通过任务规划、文件系统访问和子 Agent 委托三大机制，系统化解决长周期任务执行问题。它引入文件系统作为上下文缓冲区，降低 Token 成本，并通过 TodoListMiddleware、SubAgentMiddleware 等中间件提升任务执行效率与可靠性。DeepAgents 支持高度定制化，开发者可自定义 System Prompt、集成专有工具、定义领域特定工作流、实现跨会话记忆等。结合 Milvus 向量存储，Agent 可获得持久化语义记忆，实现更智能的长期任务处理。本文详细解读 DeepAgents 核心功能与定制能力，并提供搭配 Milvus 的快速部署教程，助开发者构建高可靠、低成本的大模型应用。

1、什么是 deepagents

deepagents 是 LangChain 团队开源的 agent 框架项目，专门用于解决长周期任务的执行问题，其核心能力有三:

任务规划(Planning):使用内置 write_todos 和 read_todos 工具将复杂任务分解为结构化待办事项列表,agent 按列表执行并标记完成状态。

文件系统访问(Computer Access):提供 ls、read_file、write_file、edit_file、glob、grep 等工具,让 agent 能够读写文件、搜索文件内容。大型工具调用结果自动保存到文件,避免消耗上下文窗口。

子 agent 委托(Sub-agent Delegation):通过 task 工具将子任务委托给专门的子 agent 执行,每个子 agent 拥有独立的上下文窗口和工具集。

使用 create_deep_agent 创建的 agent 是编译后的 LangGraph StateGraph,可直接使用 LangGraph 的流式输出、检查点、人机交互等特性。

2、为什么要用deepagents？

长周期任务面临的核心挑战是上下文窗口限制与成本控制之间的矛盾。传统 agent 将所有工具调用结果堆入上下文，导致 token 成本激增，同时模型在海量信息中逐渐失焦。

deepagents 的解决思路是重新设计信息流架构：引入文件系统作为上下文缓冲区，大型工具结果自动写入文件，agent 上下文中仅保留路径引用。配合自动摘要和提示缓存机制，系统显著降低成本的同时保持任务执行效率。

此外，deepagents 通过引入TodoListMiddleware 要求 agent 在执行前分解任务，将复杂指令转化为可验证的原子步骤，可以避免因随机探索导致的失败。

在此基础上，SubAgentMiddleware还会为子任务创建独立执行环境，不同任务的上下文互不干扰。

PatchToolCallsMiddleware 则用于处理人机交互中断场景，确保任务恢复后能正确继续。这些机制组合使用，将复杂任务的完成率大幅提升。

架构扩展性则来自模块化中间件设计。deepagents 将 Claude Code 和 Manus 验证的架构模式开源，通过每个能力封装为独立组件，开发者可以根据需求替换或扩展任意中间件，从而构建适合特定领域的 agent 系统。例如将文件存储迁移到云端只需替换 backend 实现。

3、deepagents 的定制能力

通用框架无法满足所有垂直领域的特定需求可以通过定制能力，deepagents 通过提供完整的可扩展机制，允许开发者根据业务场景定制 agent 。

开发者可以：集成专有工具和 API、定义领域特定的工作流程、控制 agent 行为符合业务规则、实现跨会话的知识积累和记忆管理。

以下是deepagents 支持的定制能力：

（1）System Prompt 定制

自定义 system prompt 会附加到中间件注入的默认指令之后，用于定义领域特定的工作流程和约束。

在使用中，我们要注意，应该在自定义 prompt 中包含：

领域工作流程：“数据分析任务先执行探索性分析，再构建模型”
具体示例：“将相似的文献检索任务合并到一个待办事项”
停止标准：“预算超过 100 次工具调用时停止”
工具协同说明：“使用 grep 定位代码位置后再用 read_file 查看详细内容”

不应该包含：

重复中间件已有的工具使用说明
与默认指令冲突的规则（例如禁止使用待办事项）

（2）Tools

deepagents 支持添加自定义工具到内置工具集。工具定义遵循标准 Python 函数签名，docstring 作为工具描述。

from deepagents import create_deep_agent
def internet_search(query: str) -> str:
    """Run a web search"""
    return tavily_client.search(query)
agent = create_deep_agent(tools=[internet_search])
MCP 工具集成通过 langchain-mcp-adapters 连接 Model Context Protocol 工具。

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent
async def main():
    mcp_client = MultiServerMCPClient(...)
    mcp_tools = await mcp_client.get_tools()
    agent = create_deep_agent(tools=mcp_tools)
    async for chunk in agent.astream({"messages": [{"role": "user", "content": "..."}]}):
        chunk["messages"][-1].pretty_print()

（3）Middleware

自定义 middleware 用于注入工具、修改提示或 hook agent 生命周期。

from langchain_core.tools import tool
from deepagents import create_deep_agent
from deepagents.middleware import AgentMiddleware
@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."
class WeatherMiddleware(AgentMiddleware):
    tools = [get_weather]
agent = create_deep_agent(middleware=[WeatherMiddleware()])
内置 middleware 功能清单：
（4）Subagents

主 agent 通过 task 工具将子任务委托给子 agent。子 agent 在隔离的上下文窗口中执行，拥有独立的工具集和系统提示。

from deepagents import create_deep_agent
research_subagent = {
    "name": "research-agent",
    "description": "Used to research in-depth questions",
    "prompt": "You are an expert researcher",
    "tools": [internet_search],
    "model": "openai:gpt-4o",  # Optional, defaults to main agent model
}
agent = create_deep_agent(subagents=[research_subagent])
对于复杂情况,可以传入预先构建的 LangGraph:

from deepagents import CompiledSubAgent, create_deep_agent
custom_graph = create_agent(model=..., tools=..., prompt=...)
agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="data-analyzer",
        description="Specialized agent for data analysis",
        runnable=custom_graph
    )]
)

（5）interrupt_on

通过 interrupt_on 参数配置需要人工审批的工具,agent 会暂停执行等待人工反馈。

from langchain_core.tools import tool
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
@tool
def delete_file(path: str) -> str:
    """Delete a file from the filesystem."""
    return f"Deleted {path}"
agent = create_deep_agent(
    tools=[delete_file],
    interrupt_on={
        "delete_file": {
            "allowed_decisions": ["approve", "edit", "reject"]
        }
    },
    checkpointer=MemorySaver()
)

（6）Backends 定制

配置不同的存储后端控制文件操作行为,支持 StateBackend(临时)、FilesystemBackend(本地磁盘)、

StoreBackend(持久化)、CompositeBackend(混合路由)。
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/path/to/project")
)

4、为什么deepagents 需要搭配Milvus使用

Agent 需要跨会话能力用于保存用户偏好配置、从多次对话中积累领域知识、记录反馈用于行为调整、维护跨会话的长期研究任务进度。

但是deepagents默认的 StateBackend 只支持单次会话存储,而持久化 backend 能够解决跨会话数据保留问题。

因此，我们需要引入Milvus 作为向量存储层，配合 StoreBackend 实现语义记忆的持久化。过程中，Agent 对话内容和重要工具结果会自动转换为 embedding 存储到 Milvus,每次任务执行时通过语义检索找回相关历史记忆。

Milvus 的计算存储分离架构能很好地支持 Agent 的高并发读写，可水平扩展至十亿级向量规模，同时支持高并发查询和流式数据实时更新，适合生产环境的 agent 记忆存储场景。

在这个方案中，deepagents 通过 CompositeBackend 实现混合存储,将不同路径路由到不同 backend:

/workspace/、/temp/ → StateBackend(临时文件)
/memories/、/knowledge/ → StoreBackend + Milvus(持久化数据)

使用 CompositeBackend可以将特定路径(如 /memories/)路由到持久化存储,实现跨会话记忆的具体配置代码请见下文的快速开始部分。

5、快速开始：构建带 Milvus 记忆的Agent

以下示例展示如何为 deepagents 添加持久化记忆。

步骤 1：安装依赖

pip install deepagents tavily-python langchain-milvus
步骤 2：配置记忆后端

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langchain_milvus.storage import MilvusStore
# from langgraph.store.memory import InMemoryStore # 仅测试用
# 配置 Milvus 存储
milvus_store = MilvusStore(
    collection_name="agent_memories",
    embedding_service=... # 这里需要 embedding，或者 MilvusStore 默认配置
)
backend = CompositeBackend(
    default=StateBackend(),
    routes={"/memories/": StoreBackend(store=InMemoryStore())} 
)
步骤 3：创建 Agent

from tavily import TavilyClient
import os
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(query: str, max_results: int = 5) -> str:
    """执行网络搜索"""
    results = tavily_client.search(query, max_results=max_results)
    return "
".join([f"{r['title']}: {r['content']}" for r in results["results"]])
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="你是研究专家，将重要发现写入 /memories/ 目录以便跨会话复用",
    backend=backend
)
运行 agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 Milvus 向量数据库的技术特点"}]
})

说明：

/memories/ 路径下的文件会持久化存储，跨会话可访问
替换 InMemoryStore() 可为 Milvus 适配器即可实现生产级语义检索
Agent 会自动将研究结果写入 /memories/，下次任务时检索相关内容

6、内置工具概览

deepagents 通过中间件提供以下内置工具：

任务管理工具（TodoListMiddleware）：

write_todos：创建结构化待办事项列表，包含任务描述、优先级、依赖关系
read_todos：读取当前待办事项状态，显示已完成和待处理的任务

文件系统工具（FilesystemMiddleware）：

ls：列出目录中的文件，需要绝对路径（以 / 开头）
read_file：读取文件内容，支持分页参数（offset/limit）处理大文件
write_file：创建新文件或覆盖现有文件
edit_file：在文件中执行精确字符串替换
glob：使用模式匹配查找文件，例如 **/*.py 查找所有 Python 文件
grep：在文件中搜索文本模式
execute：在沙箱环境中执行 shell 命令（需要 backend 实现 SandboxBackendProtocol）

子 agent 委托工具（SubAgentMiddleware）：

task：将子任务委托给专门的子 agent 执行，参数包括子 agent 名称和任务描述

工具使用模式：

大型工具调用结果自动保存到文件。例如 internet_search 返回 100KB 内容时，FilesystemMiddleware 自动将结果写入 /tool_results/internet_search_1.txt，agent 上下文中只保留文件路径，避免消耗 token。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】