Deep Agents 学习笔记（一）：从 Agent Harness 到第一个 Deep Agent-北京尧图网络

最近开始系统学习 Datawhale 的《Deep Agents in Action》。前两章主要解决两个问题Deep Agents 到底是什么它和 LangChain、LangGraph 有什么区别一个最简单的 Deep Agent 是怎么构建和运行起来的如果只是看 API很容易把 Deep Agents 理解成“又一个 Agent 框架”。但学习完前两章后我目前更倾向于把它理解为Deep Agents 的重点不是重新定义 Agent而是在已有 Agent Framework 和 Runtime 之上为复杂 Agent 提供一套开箱即用的 Harness。1. 为什么已经有 LangChain 和 LangGraph还需要 Deep Agents假设现在要开发一个类似 AI Coding Agent 的系统。它不只是需要调用一次大模型而需要阅读代码文件搜索整个项目分析问题制定修改步骤执行多个工具保存中间结果必要时拆分子任务长任务过程中控制上下文多轮运行时保存部分状态。理论上这些都可以自己基于 LangChain 或 LangGraph 实现。问题在于几乎每开发一个复杂 Agent都要重复实现这些基础能力。因此 Deep Agents 的思路不是提供一个更底层的 Agent API而是把复杂 Agent 中反复出现的工程模式提前封装起来。2. Agent 技术栈的三个层次理解 Deep Agents首先需要区分三个概念┌──────────────────────────────┐ │ Agent Harness │ │ Deep Agents │ │ 文件系统 / 子Agent / 上下文管理 │ ├──────────────────────────────┤ │ Agent Framework │ │ LangChain │ │ Model / Tool / Agent Loop │ ├──────────────────────────────┤ │ Agent Runtime │ │ LangGraph │ │ 状态 / 持久化 / 执行 / 恢复 │ └──────────────────────────────┘它们不是竞争关系而是一个自底向上的技术栈。2.1 RuntimeAgent 怎么可靠地运行代表LangGraphRuntime 关注的是执行问题例如Agent 执行到一半失败怎么办状态怎么保存如何暂停后等待用户确认如何恢复任务多轮执行中的状态如何管理所以 LangGraph 更接近 Agent 的执行引擎。可以粗略理解为LangGraph ≈ Agent 的 Runtime / Workflow Engine它解决的是Agent 怎么跑。而不是具体告诉 Agent 应该具备什么业务能力。3. FrameworkAgent 怎么构建代表LangChainLangChain 在 Runtime 之上进一步提供Model 抽象Tool 接口Agent LoopMiddlewarePromptTool Calling 等。例如agent create_agent( modelmodel, tools[search, calculator], system_promptYou are a helpful assistant. )开发者不用再手动实现完整的调用模型 ↓ 模型判断是否调用工具 ↓ 调用工具 ↓ 把工具结果返回模型 ↓ 模型继续判断 ↓ 最终回答LangChain 已经帮我们抽象了这个 Agent Loop。因此我目前的理解是LangGraph负责执行 Agent LangChain负责构建 Agent4. HarnessAgent 如何真正完成复杂任务这就是 Deep Agents 所处的位置。Deep Agents Agent Harness它建立在 LangChain 和 LangGraph 之上进一步提供复杂 Agent 常见的基础设施例如能力作用文件系统读取、写入、搜索和编辑文件Context Management控制长任务中的上下文规模SubAgent将子任务委派给其他 AgentSkills按需加载专业能力Memory保存长期信息Todo / Planning维护复杂任务计划Human-in-the-loop高风险操作前请求人工确认其中需要特别注意**Deep Agents v0.7 并不是默认开启所有能力。**例如任务规划需要显式加入TodoListMiddlewareSkills、Memory 和人工审批等能力同样需要按需求配置。所以三层可以总结成层次代表核心问题RuntimeLangGraphAgent 怎么可靠运行FrameworkLangChainAgent 怎么构建HarnessDeep Agents怎样让 Agent 更容易完成复杂长期任务5. 为什么叫 HarnessHarness 原意有“装备、套件、控制系统”的意思。我觉得可以把 Agent 开发想象成开发一个机器人。LangGraph 给机器人提供状态机执行环境恢复机制LangChain 给机器人提供大脑接口工具调用接口 Agent Loop而 Deep Agents 则进一步给机器人装备文件系统任务列表长期记忆专业技能子 Agent 上下文管理权限机制所以 Deep Agents 并不是“另一个更大的 Agent”。更加准确的说法应该是它给 Agent 装上一套完成复杂任务所需要的工程装备。这也是我认为理解 Harness 最重要的一点。6. Deep Agents 的核心思想Context Engineering这一部分是第一章中我认为最值得关注的内容。传统 LLM 应用经常采用Prompt 用户问题所有相关资料所有历史记录所有文件全部塞入 Context。这种方式面对复杂任务会产生几个问题Context 越来越大 ↓ Token 消耗增加 ↓ 关键信息被稀释 ↓ 模型越来越难定位真正需要的信息Deep Agents 更强调不要把所有信息一直放在上下文里而是让 Agent 在需要的时候主动获取信息。例如Agent │ ├── read_file() ├── write_file() ├── grep() ├── glob() └── edit_file()需要一个文件时才读取。需要保存大量中间信息时就write_file(...)需要搜索项目时grep(...)大文件则只读取局部内容。因此传统方式所有信息 ↓ Prompt ↓ LLM Deep Agents ┌── File System │ LLM ←──── Context ──── Search │ ├── Memory ├── Skills └── SubAgent这实际上把Prompt Engineering进一步扩展成了Context Engineering核心问题从Prompt 怎么写变成模型在当前时刻到底应该看到什么信息Deep Agents 通过虚拟文件系统以及可插拔 Backend使 Agent 可以按需读取和保存信息而不是持续把所有信息堆进 Prompt。7. Tool、Middleware 和 Backend 必须区分这是理解 Deep Agents 架构时非常重要的一组概念。可以先简单记Tool Agent 能做什么 Middleware Agent 的行为如何被增强/控制 Backend 操作真正在哪里执行和存储例如模型决定read_file(main.py)表面上这是一个 Tool Calling。背后其实是LLM ↓ read_file Tool ↓ FilesystemMiddleware ↓ Backend ↓ 真正读取文件因此 Backend 自身并不是 Agent也不负责思考。它负责文件存在哪里文件怎么读取数据如何持久化是否使用本地磁盘是否使用数据库是否使用远程 SandboxMiddleware 则处于 Agent Loop 中可以在模型调用和工具执行等阶段加入额外逻辑。8. 第一个 Deep Agent理解完架构后第二章开始真正运行 Deep Agent。安装pip install deepagents langchain-openai当前教程要求 Python 3.11。最核心的 API 是from deepagents import create_deep_agent一个最简单的 Agent 可以写成from langchain_openai import ChatOpenAI from deepagents import create_deep_agent model ChatOpenAI( modelyour-model, api_keyyour-api-key, base_urlyour-base-url ) def get_weather(city: str) - str: Get the weather information of a city. return fThe weather in {city} is sunny. agent create_deep_agent( modelmodel, tools[get_weather], system_promptYou are a helpful assistant. )然后result agent.invoke({ messages: [ { role: user, content: 北京天气怎么样 } ] })最终结果可以从result[messages][-1].content获取。9. create_deep_agent() 到底做了什么表面上我们只写了agent create_deep_agent(...)但其内部实际上完成了更复杂的装配。大致可以理解成业务配置 │ ├── Model ├── Tools ├── System Prompt ├── Middleware └── Backend │ ↓ create_deep_agent() │ ↓ 装配 Deep Agent Harness │ ↓ LangChain create_agent() │ ↓ Agent Loop │ ↓ LangGraph Runtime也就是说create_deep_agent() 并没有替代 LangChain而是在 LangChain Agent 周围装配了一系列 Harness 能力最终仍然由 LangGraph 执行。这一点非常关键。10. Tool 本质上是什么Deep Agents 中一个普通 Python Function 就可以作为 Tool。例如def search_paper( query: str, max_results: int 10 ) - list: Search papers according to a research query. ...对于 Agent 来说最重要的是三个东西1. 参数名称和类型 2. Docstring 3. 默认参数因为 LLM 会根据这些信息判断这个工具是干什么的什么时候使用应该传什么参数哪些参数可以省略因此Tool 的 docstring 实际上就是写给 Agent 阅读的 API 文档。工具描述写得含糊Agent 的 Tool Calling 质量自然也会下降。11. agent.invoke() 并不是“调用一次模型”这一点很容易产生误解。代码agent.invoke(...)看起来只有一次调用。实际上内部可能发生User ↓ LLM ↓ 决定调用 Search ↓ Search Tool ↓ 结果返回 LLM ↓ LLM ↓ 决定读取文件 ↓ read_file ↓ LLM ↓ 决定调用 SubAgent ↓ task() ↓ SubAgent ↓ 返回结果 ↓ LLM ↓ Final Answer所以更准确的结构是while True: response model(context) if response.need_tool: result tool(response.tool_call) context.add(result) else: return response当然实际实现比这复杂很多因为 Middleware 还会介入模型调用、工具执行、上下文处理和审批等环节。12. 一个 Research Agent 可能怎么工作如果给 Agent 一个任务调研 LangGraph并生成一份研究报告假如我们显式开启了 Todo Planning它可能自己完成用户任务 ↓ 1. write_todos() ↓ 2. internet_search() ↓ 3. internet_search() ↓ 4. write_file() ↓ 5. task(SubAgent) ↓ 6. read_file() ↓ 7. 综合信息 ↓ 8. 输出报告这里最有意思的是开发者可能只写了一句agent.invoke(...)但是 Agent 内部可能进行了十几次模型和工具交互。Harness 的价值就是隐藏大量重复的 Agent Engineering 基础设施同时保留配置能力。13. Planning 并不是固定工作流这里还有一个很重要的认识。例如Planning → Search → File → SubAgent → Final Answer只是 Agent可能选择的一条路径。它不是传统 Workflowstep1() step2() step3() step4()真正执行的时候模型可能认为任务很简单于是直接User ↓ Search ↓ Answer也可能User ↓ Planning ↓ Search ↓ Search ↓ File ↓ SubAgent ↓ Search ↓ Answer所以 Agent 系统的一个重要特点就是开发者定义能力空间模型在运行时决定具体路径。这和传统 Workflow Programming 有明显区别。14. 为什么 Agent 开发必须做 Observability普通程序报错通常可以看Exception Stack Trace Log但 Agent 出现的问题可能是模型为什么没有调用 Search 为什么调用了错误的 Tool 为什么参数传错为什么 SubAgent 没有被调用为什么消耗了大量 Token 为什么 Agent 循环十几次还没结束这些问题只看最终输出很难分析。因此复杂 Agent 开发需要 Trace。教程中使用 LangSmith可以查看每次模型调用Tool CallingTool 参数Tool 返回值SubAgent 执行Token 消耗执行耗时文件变化等。所以我目前认为LLM Application Tool Calling Agent Loop Trace才构成比较完整的 Agent 开发闭环。15. 我目前对 Deep Agents 的整体理解学习前我容易把Deep Agents理解成一个用于构建 Agent 的新框架。现在感觉这种理解并不准确。更合理的是Application │ ↓ ┌───────────────┐ │ Deep Agents │ │ Agent Harness │ └───────┬───────┘ │ ┌───────▼───────┐ │ LangChain │ │ Agent Framework│ └───────┬───────┘ │ ┌───────▼───────┐ │ LangGraph │ │ Agent Runtime │ └───────────────┘Deep Agents 真正有价值的地方是把复杂 Agent 中已经反复被验证有效的工程模式进行了封装。例如Filesystem Planning SubAgent Memory Skills Context Management Human-in-the-loop Sandbox开发者不再需要每做一个 Agent 都从零重新实现。16. Deep Agents 和 Codex / Claude Code 应该怎么理解从 Harness 这个角度再去理解 Codex、Claude Code 这类产品会清楚很多。它们并不是LLM 一个 Shell 工具而更接近LLM Agent Loop Filesystem Search Shell Planning Context Management Permission Sandbox Observability也就是说真正复杂的 Agent 产品核心竞争力很大一部分其实存在于模型之外的 Harness。模型决定Agent 能有多聪明Harness 决定这个聪明的模型能不能稳定地完成复杂任务这是我学习这两章之后最大的认知变化。17. 两章学习后的知识地图最后把目前内容压缩成一张知识图Deep Agents │ ├── 1. Runtime │ └── LangGraph │ ├── State │ ├── Persistence │ ├── Durable Execution │ └── Human-in-the-loop │ ├── 2. Framework │ └── LangChain │ ├── Model │ ├── Tool │ ├── Agent Loop │ └── Middleware │ └── 3. Harness └── Deep Agents ├── Filesystem ├── Context Engineering ├── SubAgent ├── Planning ├── Skills ├── Memory ├── Backend └── Human-in-the-loop而一次实际运行可以概括成User ↓ Deep Agent ↓ Model ↓ 判断下一步 ├───────────────┐ ↓ ↓ Tool Final Answer ↓ Middleware ↓ Backend / External API ↓ Result ↓ 重新进入 Model18. 小结前两章真正需要掌握的我认为不是create_deep_agent()这个 API而是下面几个概念第一区分 Runtime、Framework 和 Harness。LangGraph → Runtime LangChain → Framework Deep Agents → Harness第二理解 Deep Agents 为什么强调 Context Engineering。复杂 Agent 的核心问题已经不仅是 Prompt 怎么写而是什么信息在什么时间以什么形式进入模型 Context第三理解 Agent 是一个循环而不是一次 LLM 调用。Model ↕ Tools会持续交互直到模型认为任务完成。第四理解 Tool、Middleware、Backend 三者职责。Tool → 能做什么 Middleware → 怎么控制和增强 Backend → 在哪里真正执行和保存第五Harness 才是复杂 Agent 产品非常关键的工程层。模型能力当然重要但一个真正能够长期、稳定执行任务的 Agent还需要文件系统、上下文管理、权限、规划、子任务委派、Sandbox 和可观测性等大量模型之外的工程能力。这也是继续学习 Deep Agents 时我认为最值得保持的一条主线不要只学习“怎么调用 Agent API”而要理解一个复杂 Agent Harness 是如何被设计出来的。参考资料Datawhale《Deep Agents in Action》第 1 章从 Agent Framework 到 Agent HarnessDatawhale《Deep Agents in Action》第 2 章快速上手——构建第一个 Deep Agent

Deep Agents 学习笔记（一）：从 Agent Harness 到第一个 Deep Agent

相关推荐

WorkBuddy_AI Harness架构解析3_Harness_vs_传统Agent框架

消解教学质控供需错配：智圣新创AI智慧教学与督导管理平台全域效能升级建设指南

supabase-postgres-best-practices - conn-idle-timeout

更多资讯

LoRa模块原理图深度解读：从射频匹配到PCB布局避坑指南

AI辅助代码审计实战：从180个候选到22个真实漏洞的工作流拆解

AI代理运行时安全测试：从标准到工程实践

3D 4K荧光内窥镜系统装机全攻略：从链路组网到避坑实战

机构设计公差分析：从极值法到蒙特卡洛仿真的实战指南

Cherry Studio 多模型 AI 客户端实测：一个桌面接入全部大模型与知识库 RAG

今日更新

防关联浏览器哪个好？三款产品实测差异解析

2026钢铁行业AI转型系统选型对比：多基地排产、大宗原燃料采购与质量追溯，六家厂商能力差异在哪里

影刀RPA深度实战：大模型Fine-tuning定制RPA专用Prompt与指令生成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？