从十几行代码到可交付 Agent:LangChain、LangGraph 与 DeepAgents 的工程拆解

掘金一篇技术文章基于 LangChain 1.6、LangGraph 1.7 与 DeepAgents 1.16,拆解 createAgent、Middleware 与复杂 Agent 分层设计,指出 Agent 从 Demo 到可交付的关键工程差距。

分类:大模型

导语:Agent Demo 容易,复杂任务交付更难

用聊天模型加几个工具,做一个“查天气”“查时间”的演示,很多框架都能在十几行代码里完成。但当 Agent 进入复杂任务,问题会很快转移到状态管理、循环路由、持久化、上下文压缩和权限边界。掘金平台一篇技术文章以 LangChain 1.6、LangGraph 1.7 与 DeepAgents 1.16 的 JavaScript / Node.js 实战为例,拆解了从 createAgent、Middleware 到复杂 Agent 的设计路径,并指出 Demo 与可交付 Agent 之间的差距。

createAgent:把 Agent 理解为可扩展的 ReAct 循环

文章的基础示例从一个时间工具开始:使用 zod 定义空对象 schema,用 tool 包装返回当前 UTC 时间的函数,再通过 createAgent 接入模型与系统提示词。调用 agent.invoke 后,Agent 返回最终消息。文章使用 Node.js ESM 编写示例,可以直接保存为 .mjs 文件运行。

相比调用结果,文章更强调 createAgent 背后的流程:开发者提供模型、工具和提示词,框架承担消息循环。其伪代码是:先放入用户输入,再调用模型;如果模型没有工具调用请求,就结束;如果有,就执行工具并把结果写回消息,然后继续循环。

  • 核心循环并不复杂,但真实实现还要处理并行工具、异常、路由、限制和持久化。
  • createAgent 可以被看作一个“可扩展的 ReAct 循环”,而不是黑盒。
  • 如果 Agent 需要工具调用,模型必须正确支持 tool calling;能聊天不代表能稳定产生符合格式的工具调用。

文章给出的核心依赖包括 langchain ^1.6.6、@langchain/langgraph ^1.7.4、@langchain/openai ^1.8.4、deepagents ^1.16.5、dotenv ^18.0.10、zod ^4.6.7。若服务兼容 OpenAI Chat Completions 协议,通常只需要替换 baseURL、模型名称和密钥。

Middleware:日志、权限和上下文注入的拦截层

在基础循环之上,文章把 Middleware 定义为插入 Agent 生命周期的拦截器。它可以位于 beforeAgent、beforeModel、wrapModelCall、afterModel、wrapToolCall、afterAgent 等位置。当多个 wrapModelCall 或 wrapToolCall 同时存在时,行为类似“洋葱模型”:外层先进入,内层后进入;返回时顺序反过来。

这意味着 Middleware 顺序本身就是业务逻辑的一部分。尤其当多个中间件都会修改消息、系统提示词或提前结束流程时,文章建议固定顺序并写测试。

文章还区分了 stateSchema 与 contextSchema。需要被 Agent 写入、累计、恢复的信息适合放进 stateSchema;由宿主应用传入且只读的信息适合放进 contextSchema。例如,“本轮模型调用了几次”适合放状态;“当前租户、当前用户权限、用户偏好”更适合放上下文。

在日志示例中,loggingMiddleware 通过 stateSchema 定义 modelCallCount,默认值为 0。beforeAgent 记录初始消息数,beforeModel 记录当前消息数和历史调用次数,afterModel 截取模型返回内容并把计数加 1,afterAgent 输出累计调用次数。由于 afterModel 返回的对象会合并进 Agent 状态,最终 invoke 结果中也能读取 modelCallCount。

  • Middleware 不只是打日志的装饰器,它返回的状态更新、抛出的异常和路由命令都会改变 Agent 行为。
  • wrapModelCall 可以在模型调用前追加业务规则,例如补充“优先给出结论,再用一句话解释依据”。
  • 修改 systemMessage 时应生成新的系统消息,而不是直接改动消息对象内部内容。
  • wrap 函数承担横切逻辑,不应把核心业务工具塞进 Middleware;领域动作仍应是 Tool。
  • 某些请求可以在模型调用前直接返回,例如输入中出现敏感标记、用户无权访问或系统正在维护。

从 LangGraph 到 DeepAgents:复杂 Agent 需要职责分层

文章将 LangChain、LangGraph 和 DeepAgents 的关系整理为一个按职责拆开的认知模型:最上层是业务 Agent;其下是 DeepAgents Harness,负责规划、文件工作区、子 Agent、摘要压缩、记忆和权限;再往下是 LangChain Agent 抽象,包括 createAgent、messages、model、tools 和 middleware;底层是 LangGraph 运行时,涉及状态机、条件路由、循环、Checkpointer、Store 和流式执行。

文章强调,这一结构不是严格的继承关系,而是帮助开发者理解不同层级职责的模型。换句话说,简单 Demo 可以只依赖 createAgent 和少量工具;但当 Agent 需要长期记忆、子任务协作、文件工作区或权限控制时,就需要更高层的能力组合。

在依赖管理上,文章提到,DeepAgents 使用 LangChain 运行时包作为 peer dependency。应用侧应尽量让这些包只保留一份版本,避免因重复安装产生 instanceof、消息类型或 Command 类型不一致的问题。

从 Demo 到生产:Agent 框架关注点转向工程细节

这篇拆解的价值,在于把“做一个 Agent”和“交付一个 Agent”区分开来。前者关注模型能否调用工具、能否返回答案;后者关注状态是否能恢复、循环是否可控、上下文是否会被压缩、权限边界是否清晰、中间件是否会改变执行结果。

对开发者而言,createAgent 降低了入门门槛,Middleware 提供了横切能力的插入点,LangGraph 和 DeepAgents 则把状态机、路由、记忆、子 Agent 等复杂问题分层处理。对行业而言,Agent 框架的关注点正在从演示效果转向可观测性、可测试性和可维护性。

原创文章,作者:点点,如若转载,请注明出处:https://www.dian8dian.com/cong-shi-ji-xing-dai-ma-dao-ke-jiao-fu-agent-langchain

Like (0)
点点的头像点点
Previous 1小时前
Next 2024年9月22日

相关推荐