导读

在开发 AI 应用时你是否遇到过：传统的 LangChain 链式结构无法处理复杂的循环逻辑？当你的 Agent 需要“自我反思、纠错或反复迭代”时代码是否变得变得极其臃肿且难以维护？不过，

基础概念

什么是 LangGraph？

LangGraph 是由 LangChain 团队开发的一个用于建立 复杂、多 Agent还有有状态环形逻辑应用的开源框架。

如果说标准的 LangChain 擅长处理 线性的、链式的步骤，那么 LangGraph 就是为了处理复杂的、有循环的、图状的交互逻辑而生的。

从主要痛点来看，为什么需要 LangGraph？

在建立先进的 AI 应用时我们经常需要让 LLM 进行 自我反思、纠错或循环迭代。

例如这方面，写代码 → 运行测试 → 报错 → 将错误塞回给 LLM 修复 → 重新测试。

传统的 LangChain 链式结构很难无法了以下问题：

1. 支持循环： 允许 Agent 在满足特定条件前，反复执行某个步骤。不过，
2. 内置状态管理： 自动在图的各个节点之间传递、维护并持久化上下文状态。
3. 人类介入： 原生支持在某个节点暂停，等待人工审批或修改后继续运行。

LangGraph 的三大主要概念

LangGraph 的设计完全基于图论，主要由以下三个要素构成：

. State

图的全局上下文与“单一数据源”。 在 JS 中。它是一个通过 Annotation.Root 定义的强类型对象，代表应用运行时的所有记忆。其实，图中的节点不能直接修改全局变量。而是通过返回一个新对象来提交增量更新。框架内置了 reducer 机制，会自动将新数据与原状态进行合并。

. Nodes

图中的具体执行单元。 本质上是一个 JavaScript 异步函数或 LangChain 的 Runnable 对象。每个节点代表一个具体步骤。它接收当前的 State 作为输入。执行完业务逻辑后返回一个包含更新字段的 JS 对象，以此触发状态更新并驱动流程进入接下来。

. Edges

定义节点之间的控制流与状态流转方向。 它决定了应用如何从一个步骤走向下一个步骤，分为两种：

• 普通边： 无条件连接。使用 .addEdge 明确指定节点 A 执行完后百分之百直接进入节点 B。
• 条件边： 动态路由。使用 .addConditionalEdges 绑定一个 JS 路由函数。该函数会读取当前 State并返回一个标签，图会根据这个标签动态决定接下来是去调用工具还是直接结束流程。

再看典型使用场景，

• RAG 纠错流： 检索出文档后先让节点 A 评估文档相关性。如果不相关，流转到节点 B 重新生成查询关键词；按理说，如果相关，再流转到节点 C 生成回答。
• 多智能体协作： 定义多个 Node。每个 Node 代表一个拥有不同 Prompt 和工具的专业 Agent，它们通过共享的 State 协同完成一个复杂任务。
• 长流程审批程序： AI 生成方案 → 触发条件边暂停 → 等待人类前端确认/修改 → 汇入状态继续执行后续部署。

什么是 LangSmith？

简单LangSmith 是由 LangChain 团队推出的一款专门针对大语言模型应用的生产级网站。

如果说 LangChain/LangGraph 是帮你把 AI 应用“组装”出来的骨架，那么 LangSmith 就是给这个应用装上的高精度雷达、黑匣子和仪表盘。它解决了大模型开发中最大的痛点：黑盒、不可控、难以评估。

主要功能矩阵

⚙️ 链路追踪与调试

大模型应用的内部执行往往嵌套非常深。一个简单的问题，背后可能触发多次检索、工具调用和多次 LLM 思考。

• 可视化黑匣子： LangSmith 可以把每一次请求的完整周期变成一张结构化的图。
• 精准定位： 你可以清晰看到每一步输入了什么、输出了什么、哪个哪个 API、花了多少 Token、哪一步耗时。怎么说呢，

📊 自动化评估

传统的软件测试靠断言。但大模型的输出是生成式的，很难用绝对值来衡量。 老实说，

• LLM-as-Judge： 支持引入另一个模型来当“裁判”。实时或批量给应用打分，
• 黄金数据集： 你可以把生产环境中报错的真实 Case 一键保存为测试集，在修改提示词或更换模型后进行全量回归。老实说，

📈 线上监控与成本

应用上线后你需要掌握整体运行健康度：

• LangSmith 提供开箱即用的仪表盘。实时监控 P50/P99 延迟、错误率变动还有最关心的 Token 消耗。

🧑💻 提示词管理

• 提供内置的 Playground 和版本控制。老实说，团队和产品经理可以在网站上修改提示词，查看历史版本。并直接通过 API 拉取最新的提示词，无需重新打包代码。

LangSmith Engine 的演进

引入了更深度的自动化。将人工看日志、写测试的链路进一步自动化：

• 自动聚类错误： 它会自动分析线上成千万条 Trace，把相似的错误聚类成一个 Issue。
• 自动提 PR： 如果绑定了代码仓库。它甚至能结合上下文自动生成修复提示词或代码的 Pull Request，为你防止该错误再犯。

常见误区与环境协同

实践

. 新建工程项目，导入 LangGraph 相关依赖

mkdir langgraph-agent-demo cd langgraph-agent-demo npm add @langchain/community @langchain/core @langchain/deepseek @langchain/langgraph @langchain/tavily dotenv

库名	说明
@langchain/core	LangChain 的底层主要。定义模型、链、工具等标准接口
@langchain/community	社区维护的各种工具集
@langchain/deepseek	让 LangChain 能调用 DeepSeek 大模型
@langchain/langgraph	用来编排多步骤、有状态的 AI 工作流和 Agent
@langchain/tavily	给 AI 用的实时搜索工具，用来查最新互联网信息
dotenv	读取 .env 文件，管理 API Key 等环境变量

. 在环境变量填好 Key

新建 .env 文件，填入你的：

DESEEKAPIKEY="你的 DeepSeek apikey" TILYAPIKEY="你的 tavily apikey"

注意：.env 要写入 .gitignore 中避免泄露。

. 编写智能体代码

新建 agent.mts 文件，这是主要原因所在：

import "dotenv/config";不过，import { TavilySearch } from "@langchain/tavily";import { ChatDeepSeek } from "@langchain/deepseek";import { MemorySaver,StateGraph,MessagesAnnotation。START } from "@langchain/langgraph";import { ToolNode,toolsCondition } from "@langchain/langgraph/prebuilt";// 定义智能体使用的工具 const agentTools =;说起来，// 将工具绑定到模型上。以便模型知道可以这些工具 const agentModel = new ChatDeepSeek.bindTools;// 定义调用模型的节点 const callModel = async => { const response = await agentModel.invoke;// MessagesAnnotation 的 reducer 会自动将新消息追加到历史中。return { messages: };}，// 定义状态图 const workflow = new StateGraph .addNode .addNode) .addEdge .addConditionalEdges .addEdge;// 初始化内存以多次运行之间持久化状态 const checkpointer = new MemorySaver;// 将工作流编译为带点的智能体 export const agent = workflow.compile;

关键代码在于 new StateGraph...。通过增加节点、边和条件边完成整个 Agent 的编排，而 MessagesAnnotation 就是整个运行过程中传递的状态。

. 增加测试文件，测试效果

新增 test.mts 文件：

import "dotenv/config";import { HumanMessage } from "@langchain/core/messages";// 动态导入 agent，避免触发循环 const { agent } = await import;老实说，// 测试智能体 const agentFinalState = await agent.invoke( { messages: }。{ config: { threadid: "1" } } );console.log，const agentNextState = await agent.invoke( { messages: },{ config: { threadid: "1" } } );怎么说呢，console.log;按理说，

执行命令的观点是，npx tsx test.mts

. 加入 LangSmith

LangSmith 和 LangGraph 是一家公司出的，环境衔接非常好。几行代码和命令就可以完成：

1. 添加 LangSmith 依赖：

npm add langsmith

2. 在 .env 文件中加入配置和 API key：

// 你的 LangSmith apikey LANGSMITHAPIKEY="你的 LangSmith apikey" // 开启追踪 LANGSMITHTRACING="true" // 项目名称自定义 LANGSMITHPROJECT="wear-search-agent"

接下来在 Tracing 标签页面就可以看到你新建的项目数据。点击进去可以看到每次执行的详情，包括工具调用、大模型返回等。其实，

. 接入 LangSmith Studio

LangSmith 还有一个功能可以可视化看你的 Agent 编排流程图、运行情况。还可以直接在线调试，老实说，这个功能就叫 LangSmith Studio。

修改 package.json：

{ + "scripts": { + "dev": "npx @langchain/langgraph-cli dev",+ "test": "npx tsx test.mts" + },"dependencies": { "@langchain/community": "^.","@langchain/core": "^.","@langchain/deepseek": "^.","@langchain/langgraph": "^."。"@langchain/tavily": "^.","dotenv": "^.","langsmith": "^." },"devDependencies": { "@types/node": "^.","typescript": "^." } }

新建 langgraph.json 配置文件：

运行 npm run dev 即可进入可视化调试界面。

---