手把手教你打造生产级AI智能体：DeepAgents架构解析，告别上下文管理噩梦

引言

在之前的文章中，我们介绍了 LangGraph 如何通过图结构来编排 LLM 的工作流。这为我们提供了极大的灵活性。但是，当我们尝试将 Agent 从简单的演示推向生产环境时，往往会面临两个具体的工程挑战：

首先是上下文管理难题。在执行深度调研或代码分析时，Agent 调用的工具可能会返回大量数据（例如网页 HTML 源码或长文档）。这些数据如果直接填入对话历史，会迅速消耗 Token 预算，导致模型推理速度下降，甚至因为超出上下文窗口而报错。

其次是任务执行的稳定性。面对复杂的长流程任务，Agent 容易陷入局部细节而偏离初始目标，或者因为缺乏长期记忆，无法在跨会话中保持行为的一致性。

针对这些问题，LangChain 官方推出了 DeepAgents。它不仅仅是一个工具库，更是一套标准化的运行时环境（Harness）。本文将通过代码实战，展示如何利用 DeepAgents 构建一个具备自动文件管理、子任务委派以及人机协同能力的生产级智能体。

---

一、 DeepAgents 核心架构解析

DeepAgents 的核心在于它预装了一套 Middleware（中间件） 体系，这使得开发者无需从零编写 Prompt 来教 Agent 如何规划或管理内存。

它主要包含三个核心组件：

•文件系统中间件 (Filesystem)：当工具返回的数据量过大时，中间件会自动拦截数据并写入文件，只在上下文中保留文件路径。这让 Agent 能够处理远超其上下文窗口的数据量。•子智能体中间件 (Subagents)：通过将复杂任务委派给拥有独立上下文的子智能体，保持主 Agent 上下文的整洁。•混合存储后端 (Composite Backend)：通过路径路由，将不同类型的数据分别存储在内存（临时数据）或数据库（持久化数据）中。

接下来，我们通过代码逐步实现这些功能。

---

二、 环境准备

本教程基于 Python 环境。DeepAgents 依赖 LangGraph 构建，并推荐使用 Tavily 进行搜索。

安装依赖：

pip install deepagents tavily-python langchain-openai langchain-anthropic langgraph

配置密钥：

import os
import getpass
# 配置 LLM 和搜索工具的 API Key
# 建议在生产环境中使用 .env 文件管理
if not os.environ.get("OPENAI_API_KEY"):
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter OpenAI API Key: ")
if not os.environ.get("TAVILY_API_KEY"):
os.environ["TAVILY_API_KEY"] = getpass.getpass("Enter Tavily API Key: "

---

三、 虚拟文件系统与自动拦截

3.1 场景描述

在调研场景中，我们需要 Agent 阅读大量网页。传统的做法是将网页内容全部塞给 LLM，这很容易导致 Token 溢出。DeepAgents 的做法是：拦截大结果，转存为文件。

3.2 代码实现：定义搜索工具

为了演示这一功能，我们封装一个搜索工具，并强制其返回网页原始内容。

from tavily import TavilyClient
from typing import Literal
tavily_client = TavilyClient()
def internet_search(
query: str,
max_results: int = 2,
topic: Literal["general", "news"] = "general",
include_raw_content: bool = True,
):
"""
执行互联网搜索。
注意：此工具会返回网页的 HTML 原始内容，数据量较大。
"""
print(f"\n[Tool Call] 正在搜索: {query}...")
response = tavily_client.search(
query,
max_results=max_results,
include_raw_content=include_raw_content,
topic=topic
)
# 数据清洗与填充逻辑
# 目的：确保数据量超过 20000 Token，以触发 DeepAgents 的文件拦截机制
if "results" in response:
for res in response["results"]:
raw_content = res.get("raw_content") or ""
# 如果真实内容不足，人工填充数据以用于演示
if len(raw_content) < 20000:
res["raw_content"] = raw_content + (" [PADDING_DATA] " * 5000)
return response

3.3 代码解析

•include_raw_content=True：这是关键参数。Tavily 默认只返回摘要，开启此选项后会返回完整的 HTML。•数据填充逻辑：DeepAgents 默认的文件拦截阈值是 20,000 Tokens。在演示中，为了确保百分百触发该机制，我们对较短的搜索结果进行了人工填充。在生产环境中，真实的网页通常足够大，不需要这段逻辑。

---

四、 混合存储后端

4.1 场景描述

我们希望 Agent 能够区分“临时记忆”和“长期记忆”。例如，调研过程中的草稿应该随会话结束而销毁，但用户的偏好或最终报告应该持久化保存。

4.2 代码实现：配置路由

我们使用 CompositeBackend 来实现基于文件路径的存储路由。

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
# 初始化全局存储（生产环境建议替换为 PostgresStore）
global_store = InMemoryStore()
def hybrid_backend_factory(runtime):
"""
后端工厂函数：DeepAgents 运行时会自动调用它来创建存储实例。
"""
return CompositeBackend(
# 默认路由：临时文件存入 StateBackend (内存)
# 行为：数据存在 LangGraph 的 State 中，线程结束即释放
default=StateBackend(runtime),
# 特定路由：以 /memories/ 开头的路径存入 StoreBackend (持久化)
# 行为：数据存在 global_store 中，跨线程永久保存
routes={
"/memories/": StoreBackend(runtime)
}
)

4.3 代码解析

•StateBackend：这是瞬时存储。当 Agent 运行 write_file("/draft.txt", ...) 时，文件仅存在于当前运行的内存状态中。•StoreBackend：这是持久化存储。当 Agent 运行 write_file("/memories/report.txt", ...) 时，DeepAgents 会自动将其路由到 global_store 中。

---

五、 子智能体

5.1 场景描述

如果主 Agent 亲自处理所有的搜索、阅读和整理工作，其上下文（Context）会变得非常混乱。我们需要一个专门的“研究员”子智能体来处理这些杂活。

5.2 代码实现：配置子智能体

我们定义一个 deep_researcher 配置字典。

# 子智能体配置
research_subagent_config = {
"name": "deep_researcher",
"description": "专门用于执行复杂的互联网信息检索和分析任务。",
"system_prompt": """你是一个严谨的研究员。
你的任务是：
1. 使用 internet_search 工具搜索信息。
2. 如果搜索结果被存入文件（Output saved to file...），请务必使用 read_file 读取关键部分。
3. 将分析结果整理为摘要返回。""",
# 搜索工具只赋予子智能体
"tools": [internet_search],
"model": "gpt-4o"
}

5.3 代码解析

•工具隔离：注意 tools 列表。我们将在下一步组装主 Agent 时，不给主 Agent 配置搜索工具。这意味着主 Agent 如果想搜索，必须通过 task 工具委派给 deep_researcher。这种强制性的架构设计保证了主 Agent 上下文的整洁。

---

六、 人机协同

6.1 场景描述

Agent 拥有写文件和调用子智能体的能力。为了防止 Agent 覆盖重要数据或在死循环中消耗预算，我们需要在关键操作前引入人工审核。

6.2 代码实现：配置中断策略

在组装主 Agent 时，我们通过 interrupt_on 参数配置安全策略。

from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
# 定义模型
model = ChatOpenAI(model="gpt-4o", temperature=0)
# 定义 Checkpointer (人机协同必须配置此项以保存断点状态)
checkpointer = MemorySaver()
# 创建 Deep Agent
agent = create_deep_agent(
model=model,
# 主 Agent 不直接持有搜索工具，强制委派
tools=[],
# 注入持久化存储和混合后端
store=global_store,
backend=hybrid_backend_factory,
# 注册子智能体
subagents=[research_subagent_config],
# 配置 Human-in-the-loop 中断策略
interrupt_on={
# 当 Agent 试图唤起子智能体时，需要人工批准
"task": {"allowed_decisions": ["approve", "reject"]},
# 当 Agent 试图写文件时，允许人工批准、拒绝或修改内容
"write_file": {"allowed_decisions": ["approve", "reject", "edit"]}
},
checkpointer=checkpointer,
system_prompt="""你是项目经理。
1. 遇到调研任务，必须使用 task 工具委派给 deep_researcher。
2. 将调研的草稿文件保存在根目录（如 /draft.md）。
3. 将最终的重要结论，必须写入 /memories/ 目录（如 /memories/report.txt）。
"""
)

6.3 代码解析

•interrupt_on：这是一个字典，Key 是工具名称，Value 是配置项。•allowed_decisions：定义了人工可以进行的操作。

•approve：放行，按原参数执行。•reject：拒绝，Agent 会收到“操作被拒绝”的错误提示。•edit：修改，允许修改 Agent 传入工具的参数（例如修改写入文件的内容）。

•checkpointer：这是实现暂停与恢复的底层机制。DeepAgents 利用 LangGraph 的 checkpoint 将当前状态保存到内存或数据库中，等待人工介入。

---

七、完整运行流程

由于引入了人机协同，运行逻辑不再是一次性的 invoke，而是需要处理 执行 -> 中断 -> 批准 -> 恢复 的流程。

import uuid
from langgraph.types import Command
# 生成唯一的线程 ID
thread_id = str(uuid.uuid4())
config = {"configurable": {"thread_id": thread_id}}
print(f"--- 启动 Deep Agents 会话: {thread_id} ---")
# 1. 发送初始指令
print("\n>>> 用户发送指令...")
# 这里使用 invoke 而不是 stream，方便处理中断逻辑
result = agent.invoke(
{"messages": [("user", "请调研 LangGraph 的核心架构优势，整理成简报，并保存到我的长期记忆库中。")]},
config=config
)
# 2. 检查系统是否因中断而暂停
if result.get("__interrupt__"):
# 获取中断详情
interrupt_info = result["__interrupt__"][0].value
action_requests = interrupt_info["action_requests"]
tool_name = action_requests[0]["name"]
tool_args = action_requests[0]["args"]
print(f"\n[人机协同] 系统已暂停。Agent 请求执行操作: {tool_name}")
print(f"参数详情: {tool_args}")
# 模拟前端的人工审核过程
user_decision = input(f"是否批准执行 {tool_name}? (输入 y 批准): ")
if user_decision.lower() == "y":
print(f"\n>>> 用户批准，恢复执行...")
# 3. 发送 Resume 指令
# 使用 Command 对象传递 resume 信息，decisions 对应之前的 allowed_decisions
final_result = agent.invoke(
Command(resume={"decisions": [{"type": "approve"}]}),
config=config
)
# 4. 打印最终结果
print("\n--- 最终执行结果 ---")
for msg in final_result["messages"]:
# 检查是否有文件拦截日志
if msg.type == "tool" and "Output saved to" in str(msg.content):
print(f"[系统拦截] 检测到大文件，已自动转存: {msg.content}")
elif msg.type == "ai":
print(f"[AI]: {msg.content}")
# 5. 验证持久化存储
print("\n--- 验证长期记忆存储 ---")
# 通过 (thread_id, namespace) 来查询 Store 中的数据
namespaces = (thread_id, "memories")
memories = global_store.search(namespaces)
if memories:
print(f"成功在数据库中发现 {len(memories)} 个持久化文件。")
for mem in memories:
print(f" - 文件路径: {mem.key}")
else:
print("未发现持久化文件，请检查 Agent 逻辑。")

---

总结

至此，我们完成了一个从“玩具 Demo”到“生产级应用”的改造。并具备以下特征的生产级智能体：

1.无限上下文：通过 FilesystemMiddleware，Agent 能够处理远超模型 Context Window 的海量数据，利用“自动驱逐”机制保持上下文清爽。2.职责清晰：利用 SubAgentMiddleware，主 Agent 专注于规划与管理，将具体的执行细节隔离在子智能体中。3.分级存储：利用 CompositeBackend，实现了临时数据与持久化数据的分离管理。4.安全可控：通过人机协同机制，确保了关键操作的安全性。

DeepAgents 最大的价值，其实不在于它封装了多少具体的函数，而在于它改变了我们构建 Agent 的根本思路：不再试图把所有信息都强行塞进有限的 Context 窗口里，而是像设计传统软件一样，引入了文件系统、存储分级和权限控制。

对于开发者而言，这意味着我们可以从繁琐的 Token 计算和内存管理中解放出来，不再担心检索回来的文档太长会撑爆模型。这种架构上的标准化，才是 Agent 从实验室走向生产环境的关键一步。

如何学习大模型 AI ？

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

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

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

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

我在一线科技企业深耕十二载，见证过太多因技术卡位而跃迁的案例。那些率先拥抱 AI 的同事，早已在效率与薪资上形成代际优势，我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在大模型的学习中的很多困惑。我们整理出这套 AI 大模型突围资料包：

• ✅ 从零到一的 AI 学习路径图
• ✅ 大模型调优实战手册（附医疗/金融等大厂真实案例）
• ✅ 百度/阿里专家闭门录播课
• ✅ 大模型当下最新行业报告
• ✅ 真实大厂面试真题
• ✅ 2025 最新岗位需求图谱

所有资料 ⚡️ ，朋友们如果有需要 《AI大模型入门+进阶学习资源包》，下方扫码获取~

① 全套AI大模型应用开发视频教程

（包含提示工程、RAG、LangChain、Agent、模型微调与部署、DeepSeek等技术点）

② 大模型系统化学习路线

作为学习AI大模型技术的新手，方向至关重要。 正确的学习路线可以为你节省时间，少走弯路；方向不对，努力白费。这里我给大家准备了一份最科学最系统的学习成长路线图和学习规划，带你从零基础入门到精通！

③ 大模型学习书籍&文档

学习AI大模型离不开书籍文档，我精选了一系列大模型技术的书籍和学习文档（电子版），它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。

④ AI大模型最新行业报告

2025最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

⑤ 大模型项目实战&配套源码

学以致用，在项目实战中检验和巩固你所学到的知识，同时为你找工作就业和职业发展打下坚实的基础。

⑥ 大模型大厂面试真题

面试不仅是技术的较量，更需要充分的准备。在你已经掌握了大模型技术之后，就需要开始准备面试，我精心整理了一份大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

以上资料如何领取？

为什么大家都在学大模型？

最近科技巨头英特尔宣布裁员2万人，传统岗位不断缩减，但AI相关技术岗疯狂扩招，有3-5年经验，大厂薪资就能给到50K*20薪！

不出1年，“有AI项目经验”将成为投递简历的门槛。

风口之下，与其像“温水煮青蛙”一样坐等被行业淘汰，不如先人一步，掌握AI大模型原理+应用技术+项目实操经验，“顺风”翻盘！

这些资料真的有用吗？

这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

以上全套大模型资料如何领取？