前阵子有个做内部工具平台的开发者朋友跟我吐槽，说他在LangChain上搭了一个带工具调用的问答机器人，单轮问题效果不错，但只要用户的需求稍微绕一点，比如"先查上个月销售额，再对比一下库存周转率，最后出一段分析"，系统就直接拉胯。这个情况其实非常典型，很多人用LangChain做AI应用，从Chain到Agent，看起来已经"智能"了，但真正面对复杂业务场景时，传统Agent的短板暴露得非常明显。这篇笔记就是来聊DeepAgents，也就是深度智能体。它不是一个什么神秘的新框架，而是一套把任务规划、工具调用、记忆管理、自我反思和容错串起来的架构思路。我会把这套思路拆开讲清楚，并给出一套可以在LangChain生态里直接落地的代码骨架。这篇文章适合已经把基础Agent跑通、想往真实业务场景推进的开发者，也适合正在评估智能体方案的架构师。

1. 从"能聊"到"能干"：深度智能体到底解决了什么问题

1.1 普通Chain和浅层Agent为什么扛不住复杂场景

先看一个具体例子。假设要做的是一个"汇总多个数据源的指标，按部门维度生成周报"的机器人。整个任务如果要人工拆解，大概是这样的：先判断要统计哪些指标，然后从销售库拉订单数据、从库存库拉周转数据、可能还要调一个外部API拿汇率，最后把多张结果表合并成一份Markdown报告。这个流程里有一个非常要命的点：第二步的结果会直接影响第三步怎么做，比如某个商品ID在销售库里查不到，那你可能就得换个口径重新查。如果中间一步返回空或者格式不对，整个链条就断了。

如果只用普通Chain，等于把这条流程写死在代码里，一旦某个中间步骤返回空或者异常，整个链路就断了。Agent比Chain灵活，它能根据观察到的结果动态选择工具，但传统Agent往往只有"推理一步→调用工具→看结果→再推理"的内循环。这种内循环擅长处理单步决策，却不擅长处理需要先规划再执行的复杂任务。实际跑起来的表现就是：智能体在一个工具上来回转，或者已经跑偏了却不自知，把错误结果一路带到了最后。

1.2 复杂场景的四大典型特征

什么时候需要上深度智能体？我习惯从四个维度判断一个业务是否真的够"复杂"。

第一是多源异构。数据分散在不同系统、不同格式里，一个任务必须串起多个工具，而且这些工具之间没什么统一的数据格式。第二是动态依赖。后一步做什么，依赖前一步的返回值，没法预先在代码里写死顺序。第三是中间不确定性。查询可能失败、结果可能为空、返回格式可能不符合预期，系统需要根据中间状态灵活调整策略。第四是结果要可验证。不是生成一段文字就算完，还可能需要检查、补充、二次加工。

如果任务只是命中其中一条，普通Agent还能勉强应付。但如果四条都命中了，就不要试图用一条线性链路硬扛，而是应该让智能体先规划、再执行、随时反思、允许重试。深度智能体的核心价值就在这里。

1.3 DeepAgents的核心定义：四个模块协同

我通常会把深度智能体拆成四个模块，缺一不可。

规划器（Planner）负责把一个大目标拆解成可执行的子任务序列，并标注依赖关系。执行器（Executor）负责调用工具完成某个子任务，把结果回填给上下文。记忆区（Memory）需要分短时记忆和长期记忆，短时记忆管当前任务的中间状态，长期记忆管历史知识和用户偏好。反思器（Reflector）在关键节点检查当前结果是否符合预期，不满足就触发修正，甚至重新规划。

这套设计最大的好处，是把"不确定性"隔离在执行器这一层。规划器只负责出方案，执行器只负责处理工具调用和异常，反思器只负责挑毛病。每个模块职责单一，调试的时候就不会满屏逻辑乱成一团。LangChain自带的AgentExecutor已经集成了ReAct循环，但当任务复杂度上来以后，我建议直接用LangGraph这类可以显式控制状态流转的框架来编排这四块。我也因此一直认为，LangChain不是不能做深度智能体，而是大部分人对它的使用深度还停留在表层。

2. LangChain生态下的DeepAgents组件选型

2.1 范式选型：ReAct与Plan-and-Execute的取舍

选择深度智能体的落地方式，第一个要决策的往往不是某个具体库，而是整体决策范式。

ReAct范式把推理和行动揉在同一个循环里：模型根据当前观察输出一段Thought，再决定Action，看到结果后继续Thought。它的优点是灵活，不需要预先把任务拆好，特别适合连开发者自己都无法准确描述步骤的场景。缺点也很明显：随着循环轮数增加，模型容易陷入局部最优，一直在某个工具上做无意义的尝试，而且整个过程的token消耗非常大。

Plan-and-Execute范式则反其道而行，先让模型一次性输出完整的执行计划，然后逐个执行，遇到意外再局部修正。它的优点是整体可控、调整成本低，遇到问题可以定位到是规划错了还是执行错了。缺点是如果场景太动态，计划很快失效，需要频繁触发重规划。

深度智能体在实际项目里往往不是二选一，而是两者混用。我的经验是：对全局用Plan-and-Execute，让规划器输出一份子任务清单；对每个子任务内部，如果它本身也需要多步推理，就退回ReAct循环，让一个专门的子智能体去跑。这种"全局规划+局部反应"的混合结构，能同时兼顾稳定性和灵活性。

2.2 工具层设计：注册、Schema与参数动态绑定

LangChain里用@tool装饰器注册工具非常方便，但工具一旦超过10个，就会出现一个很常见的问题：模型选错工具，或者传错参数。这通常不是模型本身太笨，而是工具描述和参数Schema写得不够清晰。

我在做工具层时会遵守三条规则。第一，工具描述里先讲清楚"这个工具适合解决什么问题"，再讲"不适合解决什么问题"，后者尤其关键，能显著减少模型误选。第二，参数名和枚举值要贴近自然语言，比如state参数用"已完成/进行中/未开始"，而不是0/1/2，让模型一看就懂。第三，对输入做严格校验，模型传参出错时返回一个"参数错误+正确格式示例"的报错信息，而不是直接抛异常，这样智能体看到提示之后还有机会自动修正。

更深一层的做法是动态工具绑定。我之前做了一个内部Demo，工具列表本身不是固定的，而是根据当前任务阶段，从工具仓库里检索出TopN个相关工具，再拼进系统提示词。这个做法很像RAG，只不过检索对象是工具而不是文档，能有效缓解工具过多带来的选择噪声。实测下来，工具数从30个降到5个之后，工具调用的准确率提升非常明显。

2.3 记忆管理：短期状态、长期知识与工作区隔离

深度智能体的记忆问题比普通聊天机器人更复杂，因为复杂场景的每个子任务都可能修改上下文中的某个状态。我在用LangGraph做状态管理时，会明确划分三种数据。

第一种是会话状态，也就是当前对话轮次、用户输入、上一步输出，这些数据存在于状态节点之间，用字典传递。第二种是临时工作区，包括规划出的子任务列表、执行结果、中间产出，服务于当前这个大任务。第三种是长期记忆，指的是跨会话的历史偏好、已验证的知识条目，通常写入向量库，在需要时检索。

这三类数据必须物理隔离，不能全部堆在同一个prompt里。否则任务执行到第5个子任务时，前面几轮的中间结果已经把上下文撑爆了，模型反而忘了最开始的用户目标。我在实践中一直强调一个原则：系统提示词里只放"当前应该做什么"，而"已经做了什么"尽量在工作区中压缩成摘要，只在真正需要细节时才把原始结果放回去。这个约束能同时改善上下文长度和生成质量。

3. 实操：打造一个多源数据查询与报告生成DeepAgent

3.1 场景定义与技术选型

这一节我来搭建一个可以跑的实例，模拟"某公司运营部门需要每天从多个数据源拉取指标，自动生成一份周报"的场景。它需要访问销售库、库存库、外部API，还要做简单的数值计算和Markdown排版。任务虽然做了简化，但保留了多源数据查询、跨系统关联、条件分支、格式转换、结果检查这些典型难点。

技术选型方面，我用LangChain做工具管理，用LangGraph做状态流转，LLM通过OpenAI兼容接口接入。如果你用的是私有化部署的模型，只要支持函数调用就能照搬这套代码。这个结构本身就符合前面说的DeepAgents思路：规划器负责拆解周报任务，执行器逐个调用工具，反思器最后检查报告完整性。

3.2 环境准备与模型接入

先安装必要的依赖。避免版本踩坑，锁定大版本即可。

pip install langchain langchain-openai langgraph pandas

模型接入层，关键是按OpenAI兼容协议配置：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="your-llm-model", temperature=0.2, max_tokens=2048, timeout=15, api_key=os.environ["LLM_API_KEY"], base_url=os.environ["LLM_BASE_URL"], )

这里有个参数细节想多说一句：我习惯把temperature调成0.2甚至更低。有人觉得智能体要灵活，所以温度应该调高，但深度智能体恰恰需要稳定性——规划结果要足够可预期，工具选择要尽量避免随机波动。如果实在想让它多一些发散性，我建议只在反思器里把温度略调高，因为反思本来就需要"多想几个角度"。

3.3 工具层实现：三个必备工具

工具层是这个Demo的骨架。我用@tool定义了三个工具：第一个查询销售订单表，第二个查询库存表，第三个调用外部汇率API。这里的重点是描述写得足够"窄"，明确标注边界条件。

from langchain_core.tools import tool @tool def query_sales(start_date: str, end_date: str, product_id: int = None) -> str: """查询指定日期范围内销售订单汇总数据。返回JSON字符串。 适合用于周报、日报中的销售额、订单量指标统计。 如果不传product_id则统计全品类，传入则为单品类筛选。""" ... @tool def query_inventory(product_id: int) -> str: """按商品ID查询当前库存水位，返回JSON字符串。 注意此工具只能查询单个商品，不支持批量。""" ... @tool def fetch_exchange_rate(currency: str) -> str: """获取指定币种对人民币汇率，例如currency='USD'表示美元兑人民币。 返回JSON字符串，包含汇率值。""" ...

写完工具后，我会做一步"工具自测"：用一个最简单的LLM调用，把用户问题改成"分别查一下A产品和B产品的库存"，看它是否会连续调用两次query_inventory，以及第二次调用时product_id传没传对。这一步能提前暴露模型对工具描述的理解偏差，比等整个Agent跑起来再排查效率高得多。

3.4 规划器实现：把周报任务拆成可执行步骤

规划器是整个DeepAgent的大脑。我用结构化输出让模型返回一个JSON数组，每一元素包含stepId、description、toolName、parameters。LangChain里可以直接用with_structured_output绑定Pydantic模型实现。

from pydantic import BaseModel from typing import List, Optional class PlanItem(BaseModel): step_id: int description: str tool_name: str parameters: dict class Plan(BaseModel): steps: List[PlanItem] reasoning: Optional[str] = None planner = llm.with_structured_output(Plan)

在真实代码里，我还会在调用planner之前先做一步"需求补充"：把用户一句口语化需求先改写成一个结构化任务清单，再交给规划器。比如用户说"出一份上周的销售报告"，先补全为"统计上周销售额、订单量，按产品品类分组，对比前一周变化率，输出Markdown报告"。这样规划器拿到的输入更规范，拆解出来的计划质量会高很多。不要小看这一步，很多规划失败都是因为输入太含糊。

3.5 用LangGraph编排执行与反思循环

规划器输出计划之后，进入执行阶段。我用LangGraph定义了一个简单的状态图，包含plan节点、execute节点、reflect节点、finish节点。状态图的好处是每个节点的输入输出都是显式声明的，调试时能直接看到是哪一步出了问题。

from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator class AgentState(TypedDict): user_query: str task_plan: List[dict] current_step: int tool_results: Annotated[list, operator.add] final_report: str failed_attempts: int def plan_node(state: AgentState): # 调用规划器生成task_plan ... def execute_node(state: AgentState): # 按current_step调用对应工具，把结果追加到tool_results ... def reflect_node(state: AgentState): # 检查已完成步骤是否满足plan中该步骤的预期结果 # 不满足则重新执行当前步骤，或触发局部重规划 ... def finish_node(state: AgentState): # 汇总所有tool_results，调用LLM生成最终报告 ... graph = StateGraph(AgentState) graph.add_node("plan", plan_node) graph.add_node("execute", execute_node) graph.add_node("reflect", reflect_node) graph.add_node("finish", finish_node) graph.set_entry_point("plan") graph.add_edge("plan", "execute") graph.add_conditional_edge("execute", decide_next_step) graph.add_edge("reflect", "execute") graph.add_edge("finish", END)

执行器的循环控制非常重要。我在AgentState里加了current_step和failed_attempts两个字段，current_step推进的前提是当前步骤执行成功，而failed_attempts一旦超过阈值，就触发局部重规划而不是无限重试。没有这一步保护，智能体很容易在一个错误工具上反复调用，不仅浪费token，还会把错误结果写进最终报告。

3.6 反思器：让智能体学会检查自己的作业

很多Agent方案把"完成"定义成"所有工具执行完毕"，这是一个隐蔽的坑。"执行完毕"和"结果正确"是两件事。我见过太多案例：工具返回了空结果，但Agent照样把空结果当成有效数据写进了报告。反思器要解决的正是这个问题。

我的实现方式是，在每次执行完一个关键步骤后，让LLM根据"该步骤的预期结果描述"和"实际工具返回值"做一个二分类判断，输出{"passed": true/false, "reason": "..."}。如果passed为false，反思器先判断是重试当前步骤、换一个工具，还是调整计划。三类行为对应不同的处理分支。

def reflect(step: PlanItem, result: str): check_prompt = f"""当前步骤的目标是：{step.description} 工具返回的结果是：{result} 请判断这个结果是否满足步骤目标，只输出JSON： {{"passed": true/false, "reason": "判断依据"}}""" resp = checker_llm.invoke(check_prompt) # 根据返回的passed字段决定流转

从工程角度看，反思器这个环节最大的价值是把"模型幻觉"转化为"可验证的偏差"。虽然在执行速度上会多消耗一次甚至两次LLM调用，但换来的稳定性和可信度，在复杂业务场景里是完全值得的。

4. 复杂场景下DeepAgents的常见问题与排查实录

4.1 工具参数总是传错怎么办：从描述和Schema上双重止损

工具参数传错是Agent项目里最经典的问题。表现是模型确实调用了正确的工具，但参数要么缺失、要么类型错误、要么传了一个根本不在枚举范围内的诡异值。单纯怪模型不够聪明没意义，大多数时候是工具定义给模型挖了坑。

排查顺序我会固定为三步。第一，检查参数名是否足够自解释；第二，检查工具描述中是否写明了每个参数允许的取值范围；第三，检查返回的错误信息是否包含正确的调用示例。一个能自动修正的工具调用链，通常在这三步都做到位了。反过来，如果三处都没问题还是频繁传错，那你需要检查是不是一次暴露给模型的工具太多了，前面提到的动态工具绑定就是为这种情况准备的。

4.2 死循环与无意义空转：用最大轮次和失败阈值兜底

死循环几乎每个Agent项目都会遇到。表现是智能体反复调用同一个工具，或者反复修改计划但没有任何进展。LangGraph本身提供了recursion_limit参数，但只在图层面做了步数限制。这不够——错误数据已经被写进状态了，步数一满直接报错，用户什么结果都拿不到。

我的兜底方案是双保险。第一层是全局步数限制，比如max_iterations=8，超出后强制进入finish节点，生成"已尽力但未能完整完成"的报告。第二层是局部失败计数，每个步骤独立记录failed_attempts，超过3次就触发局部重规划，而不是继续在当前工具上死磕。这两层配合以后，死循环基本能被锁死。

4.3 上下文爆掉：用工作区压缩和关键结果摘录解决

深度智能体是上下文的消耗大户。我曾经在测试一个多步骤任务时，执行到第9个工具调用时上下文接近上限，模型开始答非所问。排查后发现所有中间结果都完整地保留在状态里，包括几个巨大的JSON数组。保留原始数据本身没错，但有些中间结果确实没有必要一直占用上下文窗口。

我现在使用的策略是"工作区压缩"：每完成一个工具调用，就对完整返回值做一次摘要，只保留摘要和关键数字在上下文里。只有反思器需要详细校验时，才临时从工作区取原始数据。同时我会在系统提示词里提醒模型：报告生成阶段只允许引用摘要中的关键数据，禁止引用未经验证的原始返回值。这两招合起来，上下文的压力会小很多。

4.4 结构化输出不稳定：从JSON到Pydantic的降级策略

用with_structured_output绑定Pydantic看起来很美，但我实测发现它在不同模型上表现差异很大。有的模型在planning阶段经常返回缺少字段的JSON，或者把parameters写成一个字符串而不是对象。直接解析失败会让整个流程中断。

可靠的做法是降级解析：先尝试结构化输出，如果解析失败，就调用一次普通文本输出，再用正则或一个小解析器提取关键字段。我在工具调用返回环节也用了类似套路。这个"先严格后宽松"的降级策略，可以把单点失败变成可恢复的延误，在真实项目中非常管用。

4.5 常见问题速查表

5. 深度智能体落地时的设计心得与延伸构思

5.1 复杂度是慢慢加出来的，不是一步到位的

大部分失败的Agent项目，都是因为一开始就追求"全自动、全智能"，结果连最基础的工具调用都还没调稳，就急着堆记忆、堆多智能体合作。我的经验是：先用最简单的方式让一条链路跑通，哪怕中间节点全靠if-else写死也没关系；跑通之后，再逐个把确定性逻辑替换成LLM决策；最后，等整体稳定了，再把反思和重规划加进来。每一步都保留前一步的"确定性兜底"，这样即使某次LLM决策抽风，系统也不至于完全崩掉。

5.2 评测是深度智能体的生命线

我特别想强调评测。很多人搭好Agent后只会人肉点几个例子，觉得"看起来还行"就上线了。深度智能体的链路长、状态多，凭感觉根本把不住质量。建议至少准备一组覆盖正常流程、边界输入、异常输入三个档位的测试用例，每轮修改后都跑一遍，记录"任务成功率""平均调用工具数""平均耗时""失败类型分布"这几个指标。

其中"失败类型分布"最容易被忽略，但它最能暴露问题的共性。比如你统计了一周之后，发现80%的失败都集中在某个特定工具的解析环节，那就不用争论模型强不强了，直接去修那个工具的描述。这种数据驱动的思路，能帮你把智能体的迭代从玄学变成工程。

5.3 从单智能体到多智能体协作的延伸

本质上，前面这套DeepAgents架构是可以横向扩展的。当单一系统的工具和职责过多时，与其把所有逻辑塞进一个大智能体，不如拆成几个职责明确的子智能体，比如数据分析Agent、行动执行Agent、质量审计Agent。它们的协作方式可以复用前面讲的规划-执行-反思框架，只是执行者从工具变成了另一个子智能体。

这种架构带来的最大好处是每个子系统的复杂度可控、提示词独立维护、失败隔离性好。代价是多一个子智能体就多一层通信开销和状态同步成本。我的建议是：当你的工具种类超过15个、或者单条执行链路超过5个关键步骤时，再考虑拆分，否则单个LangGraph图内完成所有逻辑反而是更省心的选择。

我自己在实际跑这些深度智能体的过程中，最大的体会是：智能体能不能在复杂场景里真正顶用，往往不是模型决定的，而是工程细节决定的。同样一个模型，工具描述写得差一点、反思机制缺一环、状态管理乱一层，最终表现天差地别。最后分享一个小技巧：每当你觉得某个Agent环节"总是不稳定"，与其反复改提示词，不如先把这个环节的具体输入输出打印出来看一遍。很多时候，答案早就藏在某一步的工具返回值里了。希望这篇笔记能帮你在LangChain生态里，把"看着能跑"的Agent，打磨成"真的能扛事"的DeepAgents。