企业官网建设流程全解析

本文深入解析LangChain的开源Agent harness——Deep Agents，涵盖其三层架构原理、四大核心组件及实战应用。从3行代码启动Agent，到子智能体委派、上下文管理，再到生产化配置与踩坑指南，文末附有可独立跑通的最小实现代码。适合希望快速上手大模型应用的开发者学习，开箱即用，简化复杂Agent编排。

1 开篇：LangChain 把 Agent 编排做成了开箱即用的默认值

同一个模型，只换 harness 不动参数，终端任务得分从 52.8 涨到 66.5。这是 LangChain 开源的 Deep Agents 交出的答卷。性能差距不一定在模型，可能在 harness。

2026-08-23 时点的仓库数据（GitHub 实时）：

• 28.1k stars / 3.9k forks，MIT 许可，Python 占比 99%，见 GitHub 仓库[1]
• Terminal Bench 2.0：deepagents-cli 仅调 harness、不换模型，52.8 → 66.5（+13.7 分），数据来自 Talk Python 播客 #543[2]

Deep Agents 是一个开箱即用的 Agent harness，标语是 “batteries-included”。官方致谢说得很直白：受 Claude Code 启发，识别其通用性的来源，再往前推进一步。

它的承诺是不用自己拼 prompts、tools、上下文管理和子智能体，一个 create_deep_agent() 调用就能得到一个能工作的 Agent。

“

手写工具调用循环的人都知道，prompts、上下文压缩、子智能体这些活一旦上了生产就全是坑。Deep Agents 把这层做成默认值，正是它存在的理由。

这篇覆盖前置准备、三层架构原理、分步实战、踩坑与生产进阶，最后给一个能独立跑通的最小实现。

2 前置准备：安装、API Key 与模型接入

三个前置条件，缺一不可：

• Python 3.11+，安装pip install deepagents（或uv add deepagents）
• 一个支持 tool calling 的模型 API key：Google / OpenAI / Anthropic 三选一
• 模型以 provider:model 字符串传入，如 google_genai:gemini-3.6-flash

pip install deepagents export GOOGLE_API_KEY="your-api-key" # 三选一：Google / OpenAI / Anthropic

模型无关性是硬特性。同一份代码可以换 OpenAI、Anthropic、Google，也能接 Ollama、vLLM、llama.cpp 自托管的开源模型，本地模型走 OpenAI 兼容端点即可。

• LangSmith 追踪可选：配好 LANGSMITH_TRACING=true 与 API key，就能看完整调用链
• 实测细节：create_deep_agent() 创建时就会初始化模型，API key 没配会立刻报错，错误信息会指明该设哪个环境变量

3 原理：LangChain / LangGraph / Deep Agents 三层架构与四大组件

官方 FAQ 把三者定位成同一技术栈的三个层次：LangChain 是框架，LangGraph 是运行时，Deep Agents 是 create_agent 之上「更具主见」的 harness，把编排决策做成默认值。

“

图注：harness 层内置四大组件，运行与框架层是地基。

四大组件各管一件事：

• 执行环境：自定义函数、MCP 工具、虚拟文件系统，后端可插拔
• 上下文管理：Skills 渐进式披露、记忆（AGENTS.md）、自动摘要与卸载
• 委派：任务规划（write_todos）与临时子智能体
• 控制：工具调用前暂停，等人工批准、编辑或拒绝

上下文在 harness 里走四段流：输入上下文（系统提示、记忆、技能）先压缩，大结果卸载到文件系统，重型子任务隔离成子智能体只回最终报告，最后沉淀到虚拟文件系统做长期记忆。

create_deep_agent() 返回编译后的 LangGraph 图，流式、checkpointer、Studio 全部直接可用：

from deepagents import create_deep_agent agent = create_deep_agent(model="google_genai:gemini-3.6-flash") # 返回编译后的 LangGraph 图：可流式、可持久化、可上 Studio

三个层次怎么选（依据官方 FAQ 三层表格）：

一句话结论：要开箱即用选 Deep Agents，只要轻量工具循环就退回 create_agent，Agent 循环本身不是合适形状时回 LangGraph 自己画图。

4 分步实战：3 行代码启动、委派子智能体、上下文卸载

4.1 最小起步：create_deep_agent + invoke

create_deep_agent() 返回编译后的 LangGraph 图，默认自带文件系统中间件与通用子智能体。自定义工具就是一个普通 Python 函数，类型提示加 docstring，框架自动解析成 JSON schema 交给模型。想换模型就改字符串，同一个 agent 定义可以直接切 OpenAI 或 Anthropic：

from deepagents import create_deep_agent def get_weather(city: str) -> str: """Get weather for a given city.""" # docstring 自动变成工具描述 return f"It's always sunny in {city}!" agent = create_deep_agent( model="google_genai:gemini-3.6-flash", tools=[get_weather], system_prompt="You are a helpful assistant", ) agent.invoke({"messages": [{"role": "user", "content": "what is the weather in sf"}]})

4.2 子智能体委派：隔离上下文，单次移交

内置 task 工具可以随时创建临时子智能体，核心特性六条：

• 全新上下文：每次调用创建新实例，独立上下文窗口
• 自主执行：独立运行到完成
• 单次移交：只向主智能体返回最终报告
• 可配置策略：默认 general-purpose，也可自定义
• 无状态：不能发送多条消息
• 上下文与 token 高效：重型子任务隔离压缩

多个子智能体可以并行跑不同研究路径，互不干扰，主智能体的上下文窗口不被污染。

声明式子智能体用字典配置，可以覆盖模型。贵的模型做规划，便宜的模型做执行：

internet_search = {"google_search": {}} # 内置搜索工具，免额外安装 research_subagent = { "name": "research-agent", "description": "Used to research more in depth questions", "system_prompt": "You are a great researcher", "tools": [internet_search], "model": "openai:gpt-5.5", # 可选覆盖：子智能体换模型 } agent = create_deep_agent( model="google_genai:gemini-3.6-flash", subagents=[research_subagent], )

4.3 上下文管理：自动摘要 + 文件系统卸载 + Prompt caching

长任务靠三个机制配合，把上下文溢出从「要手动处理」变成「harness 自动处理」：

• SummarizationMiddleware：上下文快满时自动压缩较早对话，就是 Claude Code 用户熟悉的 compacting 步骤
• 文件系统工具（read_file / write_file / edit_file / glob / grep）：把大结果卸载到虚拟文件系统，而不是堆在消息里
• Prompt caching：Anthropic / Bedrock 模型自动启用，缓存系统提示的静态部分，动态内容不受影响，降延迟降成本

长时任务另外两个配置入口，记忆与技能：

agent = create_deep_agent( model="google_genai:gemini-3.6-flash", memory=["./AGENTS.md"], # 启动时加载的项目记忆，始终在上下文里 skills=["./skills/"], # 技能目录：SKILL.md 渐进式披露，按需加载 )

5 踩坑：中间件替换、子智能体继承与版本断点

五个真实坑，逐个排掉：

1. 中间件覆盖是替换，不是合并。传入 .name 匹配内置栈条目的实例会原地替换（>=0.7）。覆盖 FilesystemMiddleware 时要把 backend 显式传上：不传会静默回落默认的 StateBackend，你配的沙箱或持久化后端不会生效：

FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"])

2. 初始化后不要修改中间件实例属性，会引发竞态条件。要跟踪值就用 graph state。

3. 声明式子智能体不继承主智能体的中间件自定义，只有自动添加的通用子智能体会继承。

4. 限制文件系统工具子集时，read_file 必须包含，否则直接 ValueError。

5. 版本断点：Task planning 自 v0.7 起改为 opt-in，要 write_todos 得手动加 TodoListMiddleware。delete 工具和工具 allowlist 也要求 >=0.7。截至 2026-08-23，PyPI 最新版本 0.7.8，这些特性已在当前版本内：

from langchain.agents.middleware import TodoListMiddleware agent = create_deep_agent( model="google_genai:gemini-3.6-flash", middleware=[TodoListMiddleware()], )

6 生产进阶：后端选择、人工审批、结构化输出与 MCP

生产化四条腿：后端按持久化需求选，危险操作必配人工审批，对外输出走结构化 schema，外部数据源用 MCP 接。

后端按持久化需求挑，内置常用五种：

• StateBackend（默认，线程级存储）
• FilesystemBackend（本地磁盘）
• LocalShellBackend（本地 shell）
• StoreBackend（跨线程持久）
• CompositeBackend（组合路由，比如 /memories/ 走 Store）
• 另有 6 种沙箱后端：LangSmith / Daytona / E2B / Modal / Runloop / Vercel

execute 工具只在沙箱后端出现，要跑代码就选沙箱。人工审批按工具配置，checkpointer 必需。默认给 approve / edit / reject / respond 四个决策，approve 后工具才会真正执行，edit 允许改参数再放行，也可以收窄：

from langgraph.checkpoint.memory import MemorySaver checkpointer = MemorySaver() # 人工干预必需 agent = create_deep_agent( model="google_genai:gemini-3.6-flash", tools=[remove_file, notify_email], # remove_file / notify_email 为 @tool 工具 interrupt_on={ "remove_file": True, # 默认 approve / edit / reject / respond "notify_email": {"allowed_decisions": ["approve", "reject"]}, # 不允许编辑 }, checkpointer=checkpointer, )

结构化输出用 response_format 加 Pydantic schema，结果落在 structured_response 键：

from pydantic import BaseModel, Field class WeatherReport(BaseModel): location: str = Field(description="The location for this weather report") temperature: float = Field(description="Current temperature in Celsius") agent = create_deep_agent( model="google_genai:gemini-3.6-flash", response_format=WeatherReport, tools=[internet_search], # internet_search 见 §4.2 ) result = agent.invoke({"messages": [{"role": "user", "content": "Weather in SF?"}]}) print(result["structured_response"]) # 结构化结果落在这个键

MCP 工具一行接入：MultiServerMCPClient 拉回工具列表，直接塞进 tools=。比如把公司内部数据库封装成 MCP 工具服务器，agent 就能以标准协议消费它，跨团队复用预构建集成。官方安全模型也讲得坦白：trust the LLM，边界在工具与沙盒层强制，不指望模型自我约束。

7 资源：官方仓库与文档入口

• GitHub 仓库：github.com/langchain-ai/deepagents[3]
• 官方文档：overview / quickstart / customization（docs.langchain.com/oss/python/deepagents/）
• API 参考：reference.langchain.com/python/deepagents/，社区论坛：forum.langchain.com
• JavaScript 版本 deepagents.js 也已开源

下一步建议从 CLI 实战入手，或者去读 deepagents.js，同一套能力前端团队可以直接复用，两条路都能把本文的原理落到真实项目里。

最小实现

单文件闭环：配置 API key，创建一个带搜索能力的研究型 Deep Agent，让它调研一个主题，打印最终小结。规划、上下文管理、文件系统卸载都由 harness 自动接管，代码里看不到，行为上可见：

"""最小实现：3 步启动一个带搜索能力的研究型 Deep Agent 运行前配置任一模型 API key： export GOOGLE_API_KEY="..." # 或 ANTHROPIC_API_KEY / OPENAI_API_KEY """ from deepagents import create_deep_agent # 1. Google 内置搜索，免额外安装、免额外 API key internet_search = {"google_search": {}} # 2. 创建 agent：规划、读写文件、子智能体由 harness 自动接管 agent = create_deep_agent( model="google_genai:gemini-3.6-flash", tools=[internet_search], system_prompt="You are an expert researcher. Conduct thorough research and write a polished report.", ) # 3. 跑一次调研 result = agent.invoke({"messages": [{"role": "user", "content": "What is langgraph?"}]}) print(result["messages"][-1].content)

预期效果：配置 GOOGLE_API_KEY（或 ANTHROPIC_API_KEY / OPENAI_API_KEY）后运行，终端打印一份关于 LangGraph 的研究小结。过程中 agent 会自动调用搜索工具、把大结果写入虚拟文件系统、必要时生成子智能体，这些都是 harness 的默认行为。

“

运行提示：需要 Python 3.11+ 与pip install deepagents，本示例需配置 API key 后运行。代码基于官方 Quickstart Step 3–6 逐字语义，本机已用 deepagents 0.7.8 验证脚本编译通过、文中全部 API 导入成功。因环境无 API key，未跑通端到端调用。

如何学习大模型 AI ？

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

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

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

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

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

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

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

为什么要学习大模型？

我国在A大模型领域面临人才短缺,数量与质量均落后于发达国家。2023年，人才缺口已超百万，凸显培养不足。随着AI技术飞速发展，预计到2025年,这一缺口将急剧扩大至400万,严重制约我国AI产业的创新步伐。加强人才培养,优化教育体系,国际合作并进是破解困局、推动AI发展的关键。

大模型入门到实战全套学习大礼包

1、大模型系统化学习路线

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

2、大模型学习书籍&文档

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

3、AI大模型最新行业报告

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

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

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

5、大模型大厂面试真题

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

适用人群

第一阶段（10天）：初阶应用

该阶段让大家对大模型 AI有一个最前沿的认识，对大模型 AI 的理解超过 95% 的人，可以在相关讨论时发表高级、不跟风、又接地气的见解，别人只会和 AI 聊天，而你能调教 AI，并能用代码将大模型和业务衔接。

• 大模型 AI 能干什么？
• 大模型是怎样获得「智能」的？
• 用好 AI 的核心心法
• 大模型应用业务架构
• 大模型应用技术架构
• 代码示例：向 GPT-3.5 灌入新知识
• 提示工程的意义和核心思想
• Prompt 典型构成
• 指令调优方法论
• 思维链和思维树
• Prompt 攻击和防范
• …

第二阶段（30天）：高阶应用

该阶段我们正式进入大模型 AI 进阶实战学习，学会构造私有知识库，扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架，抓住最新的技术进展，适合 Python 和 JavaScript 程序员。

• 为什么要做 RAG
• 搭建一个简单的 ChatPDF
• 检索的基础概念
• 什么是向量表示（Embeddings）
• 向量数据库与向量检索
• 基于向量检索的 RAG
• 搭建 RAG 系统的扩展知识
• 混合检索与 RAG-Fusion 简介
• 向量模型本地部署
• …

第三阶段（30天）：模型训练

恭喜你，如果学到这里，你基本可以找到一份大模型 AI相关的工作，自己也能训练 GPT 了！通过微调，训练自己的垂直大模型，能独立训练开源多模态大模型，掌握更多技术方案。

到此为止，大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗？

• 为什么要做 RAG
• 什么是模型
• 什么是模型训练
• 求解器 & 损失函数简介
• 小实验2：手写一个简单的神经网络并训练它
• 什么是训练/预训练/微调/轻量化微调
• Transformer结构简介
• 轻量化微调
• 实验数据集的构建
• …

第四阶段（20天）：商业闭环

对全球大模型从性能、吞吐量、成本等方面有一定的认知，可以在云端和本地等多种环境下部署大模型，找到适合自己的项目/创业方向，做一名被 AI 武装的产品经理。

• 硬件选型
• 带你了解全球大模型
• 使用国产大模型服务
• 搭建 OpenAI 代理
• 热身：基于阿里云 PAI 部署 Stable Diffusion
• 在本地计算机运行大模型
• 大模型的私有化部署
• 基于 vLLM 部署大模型
• 案例：如何优雅地在阿里云私有部署开源大模型
• 部署一套开源 LLM 项目
• 内容安全
• 互联网信息服务算法备案
• …

学习是一个过程，只要学习就会有挑战。天道酬勤，你越努力，就会成为越优秀的自己。

如果你能在15天内完成所有的任务，那你堪称天才。然而，如果你能完成 60-70% 的内容，你就已经开始具备成为一名大模型 AI 的正确特征了。

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