47 LangGraph Node：拆分意图、检索、订单与工单节点
LangGraph Node：拆分意图、检索、订单与工单节点
Node 应该职责清晰、输入输出稳定、可独立测试。不要一个节点做完整个 Agent。
[TOC]
1. 先把 Agent 想清楚
很多人一听到 Agent，就会想到“让大模型自己决定下一步”。这个理解只对了一半。
在真实项目里，Agent 更像是一个被工程规则约束住的任务执行器：
模型负责理解自然语言、提出候选动作
代码负责权限校验、状态流转、工具执行
业务接口负责最终事实和写操作
日志审计负责事后追踪
如果一个节点同时识别意图、查知识库、查订单、创建工单和生成回答，调试时根本不知道错在哪里。
所以这一阶段的博客不要写成“模型越来越聪明”。更准确的写法是：我们正在学习如何把模型的灵活性放进一个可控的工作流里。
2. 一个业务场景
售后 Agent 至少可以拆成意图识别节点、知识库检索节点、订单查询节点、工单预览节点、确认节点和最终回答节点。
这个场景里面最重要的不是模型能不能说出一段好听的话，而是：
它选了哪个工具
为什么能调用这个工具
参数从哪里来
权限在哪里校验
失败后状态怎么变
用户确认前会不会产生真实写入
把这些问题问清楚，Agent 项目才不会变成一个不可解释的聊天黑盒。
这一节要先按职责拆节点，而不是按代码文件拆。
判断顺序可以这样写：
1. 先画出任务链路：理解问题、检索知识、查询订单、判断是否创建工单、确认、执行
2. 每个节点只做一类事，输入和输出都写进 state3. 模型节点负责理解和生成候选动作，工具节点负责拿事实，业务节点负责确定性执行
4. 节点失败要能返回可处理状态，而不是直接让整条链路断掉
5. 最后检查每个节点是否能单独测试和打日志
它解决的是可维护性问题：节点边界越清楚，Agent 越容易排查、替换和扩展。
3. 核心概念
1. 意图识别节点
输出有限枚举、置信度和实体，不直接执行业务动作。
这一点在项目里要落到具体规则：识别不等于执行。
2. 知识库检索节点
调用 RAG Tool，返回证据列表和来源，不负责最终业务判断。
这一点在项目里要落到具体规则：检索只提供证据。
3. 订单查询节点
调用订单 API，返回脱敏订单摘要和领域错误。
这一点在项目里要落到具体规则：订单来自业务系统。
4. 工单节点
写操作拆成预览和创建，创建前必须有确认。
这一点在项目里要落到具体规则：写动作要单独节点。
4. 整体流程
graph TD;
A["意图识别"] --> B["条件路由"];
B["条件路由"] --> C["知识库检索"];
C["知识库检索"] --> D["订单查询"];
D["订单查询"] --> E["工单预览"];
E["工单预览"] --> F["等待确认"];
F["等待确认"] --> G["工单创建"];
G["工单创建"] --> H["最终回答"];
这张图里，模型只是其中一个节点。工具、状态、权限、确认和审计同样重要。
如果一个 Agent 图里只有“用户 -> 模型 -> 答案”，那它还只是 Chat，不是能进入业务系统的 Agent。
5. 落地步骤
1. 定义节点输入输出
每个节点接收 State，返回增量 State。不要直接改全局对象。
完成后应该能看到：节点契约。
2. 统一结果结构
工具节点返回 status、data、errorCode、retryable。
完成后应该能看到：统一 ToolResult。
3. 隔离模型节点和业务节点
模型节点做理解，业务节点做校验和执行。
完成后应该能看到：节点边界图。
4. 单独测试节点
用固定 State 输入测试每个节点。
完成后应该能看到：节点单元测试。
6. 状态、接口或工具字段
| 项目 | 说明 |
|---|---|
| nodeName | 节点名称 |
| inputFields | 读取的 State 字段 |
| outputFields | 写入的 State 字段 |
| canRetry | 是否可重试 |
| sideEffect | 是否有副作用 |
字段设计要尽量结构化。不要让下游通过一段自然语言去猜“成功了没有”“下一步要干什么”。
7. 示例
intent_node 输入 rawInput输出 intent、entities、confidence
order_query_node 输入 userId、entities.orderId
输出 orderResult 或 error
ticket_create_node 输入 confirmedAction输出 ticketResult
示例里的字段不一定照搬，但思想要保留：输入、状态、输出、错误和审计信息要分开。
8. 哪些事不能交给模型自由发挥
模型节点不应该直接调用写接口。即使模型判断“需要创建工单”，也只能进入预览和确认流程。
这一节特别重要。Agent 项目最容易踩坑的地方，就是把“理解意图”和“执行业务动作”混成一件事。
模型可以建议动作，但最终执行必须经过代码和业务系统的规则。
9. 测试路径
建议至少准备下面几类测试：
正常路径：输入完整，工具正常返回
缺字段路径：订单号、联系方式、问题描述不完整
权限路径：查询别人的订单、访问无权知识库
失败路径：工具超时、模型输出非法、检索为空
恢复路径：等待确认时服务重启、重复确认、超时确认
Agent 的测试不能只看最终回答。你要检查状态、工具调用、审计日志和是否产生真实副作用。
10. 工程取舍
- 节点拆细更易测试，但图会更长。
- 节点太粗开发快，但排查困难。
- 写节点必须考虑幂等和恢复。
取舍讲清楚以后，读者才能知道你为什么这样设计，而不是以为所有问题都要上 Agent。
11. 常见坑
- 一个节点做所有事情。
- 下游通过字符串判断工具是否成功。
- 节点直接读取全局用户身份。
- 恢复执行造成重复创建。
这些坑本质上都和一个问题有关：没有把模型输出当成“不可信的候选结果”。
12. 验收清单
- ☐ 节点职责单一
- ☐ 输入输出字段明确
- ☐ 写节点有幂等
- ☐ 节点可独立测试
- ☐ 错误结果结构统一
如果这些检查项没过，先不要急着加更多工具。工具越多，边界越乱，排查越难。
13. 落地清单
- ☐ 画出售后 Agent 节点图
- ☐ 为每个节点写输入输出
- ☐ 写一个节点测试样例
- ☐ 标记哪些节点有副作用
练习时可以先用 Mock，不要一开始就连真实订单或工单系统。等状态、权限和幂等设计清楚后，再接真实接口。
14. 小结
Node 的质量决定 Agent 的可维护性。职责越清楚，越容易测试、重试和恢复。
Agent 的价值来自灵活性，但安全来自边界。能把这两件事同时讲清楚，才算真正理解 Agent 工程化。