很多团队在把 Agent 从“聊天机器人”推向业务系统时会遇到一个很典型的现象简单问答很好用但一旦构建“多步骤、有审批、有分支、有交付物”的复杂流程Agent 的表现就会变得随机。同一个需求换个提问方式跑三次流程可能就不一样了该走人工复核的节点被跳过不该调用的工具却被调用了。问题往往不是模型不够聪明而是流程没有被约束住。LLM 擅长的是“一次推理”并不擅长“必须按文档顺序执行完每一步”。Graph Engineering 解决的就是这个问题。它不是要把流程画成好看的示意图也不是非要引入图数据库而是把一条业务流程变成一张可执行、可回滚、可观测的图图的节点定义“做什么”图的边定义“下一步去哪”LLM 只负责节点内部的判断和内容生成流程的方向由图结构说了算。把 Agent 的 SOP 画成 graph本质上就是用工程手段接管流程控制权让 Agent 从“自由发挥”变成“在轨道上推理”。这篇文章会从问题出发先讲清 SOP 和 Graph 为什么能对应再给出一个不依赖任何第三方框架的最小图执行引擎示例最后讨论生产落地时的架构模式、常见坑和边界。读完你可以直接照着搭一个最小 Demo也能理解 LangGraph、Spring AI Alibaba Graph 这类框架背后的设计思路。1. 为什么 Agent 总是“跑着跑着就偏了”先说一个判断当前大多数 Agent 应用效果不稳定不是模型能力不足而是缺少“流程边界”。纯 Prompt 驱动的 Agent 工作方式很简单把用户需求和大段指令一起交给 LLM让模型自己判断“下一步该做什么”。这种方式的优点是没有约束、交互自然但缺点也在这里。对模型来说自然语言指令是概率性理解的不是确定性执行的。你写“请严格按照步骤一、二、三执行”模型很可能在对话轮数变多、上下文变长之后把步骤二和步骤三的顺序调换或者跳过某个看似“不那么重要”的确认环节。简单任务影响不大但复杂业务场景会放大这个问题。举例来说一个生产环境发布的 SOP 通常包含检查变更内容、执行预检查、走审批确认、灰度发布、观察健康状态、更新变更记录。这个流程中“是否执行灰度”是一个条件判断“审批是否通过”可能还要暂停等待人工输入。如果用纯 Prompt 描述给 Agent当上下文超过一定长度后它可能把“预检查失败”当成“可以继续发布”这就是事故。而 Graph 驱动的 Agent 改变了控制逻辑流程不再是模型“想起来才执行”的文本而是代码里真实存在的状态机。每个节点是确定函数每条边是确定转移条件。LLM 只能在指定节点里给结果不能决定整张图的走向。用一个表格对比更直观维度纯 Prompt 驱动 AgentGraph 驱动 Agent流程控制权交给 LLM 自行判断由图的节点和边决定步骤顺序可能漂移固定除非显式设计分支可回滚难对话状态难恢复容易节点状态可持久化可观测看模型日志看节点流转、边触发条件适合场景开放探索、问答有明确 SOP 的业务流程实现成本低略高但值得从材料看最近社区对 Agent 的开发讨论越来越集中在“编排”“技能”“图结构”这些词上LangGraph 这类工作流框架流行本质上就是开发者发现了同一个问题Agent 需要骨架。Graph 就是这个骨架最自然的表达方式。2. 核心概念SOP 与 Graph 如何对应SOP 是 Standard Operating Procedure标准作业程序。它把一项任务拆成有序步骤规定每一步的操作、判断标准、产出物和责任角色。传统上 SOP 是给人读的文档最大问题是“无法直接执行”。人可以根据经验补齐文档中省略的隐含分支机器做不到。Graph 是图结构由节点和边组成。在图驱动的 Agent 系统中节点对应一个具体操作单元边对应节点之间的流转关系。把 SOP 转成 Graph就是执行一次“流程编程”把自然语言步骤翻译成机器可执行的节点和路径。例如一个客服退款 SOP 可以这样拆节点 A接收退款申请节点 B校验订单是否在可退款范围内节点 C校验通过进入退款审批节点 D校验失败向用户返回拒绝原因节点 E退款审批通过后调用支付平台退款节点 F通知用户结果对应的图关系是A - BB 根据条件分别走 C 或 DC 通过后到 EE 完成后到 F。这里要特别强调一种容易混淆的认知Graph 不等于知识图谱。知识图谱关注的是实体关系比如“用户买了商品”“商品属于类目”它回答的是“事实是什么”。Agent 的 SOP 图关注的是流程流转比如“这个操作完成后下一步是谁”它回答的是“下一步做什么”。两者虽然都叫 graph但在 Agent 工程中的定位完全不同。同时也要区分“图数据”和“图执行”。有些读者看到 Graph Engineering 会误以为必须用 Neo4j 之类的图数据库来存推荐关系。实际在 Agent 的场景里SOP 图的规模通常只有几十个节点用普通对象、JSON、甚至状态机就可以了。图数据库的主要应用场景是深度关系查询而不是驱动一次流程执行。还有一个关键设计点图的节点一定要职责单一。一个节点只做一件事比如“调用订单服务查询订单状态”是一个节点“根据订单状态决定下一步”通常是边上的条件逻辑或者是一个专属判断节点。如果节点内部塞了一长串逻辑图就退化成普通代码函数失去了可视化编排的意义。3. 图驱动的 Agent 架构有哪些常见模式把 SOP 画成 graph 不只是画一张流程图而是要确定走图时可能出现的几种拓扑结构。实际业务中大部分复杂流程都可以用下面几种模式组合出来。3.1 顺序链模式最简单也最常用。所有节点按固定顺序依次执行没有分支。比如“接收任务 - 解析需求 - 生成初稿 - 返回结果”每一步都必须在前一步完成后触发。顺序链适合线性流程例如标准化报告生成、数据清洗流程。实现上每个节点完成之后调用set_next指定下一跳即可。不要使用全局“目前在第几步”的整数状态那会导致代码里到处是if step 3图结构完全散落。3.2 条件分支模式节点执行完成后根据结果选择不同后续节点。例如“检查用户输入是否合法合法走 A不合法走 B”。这是 SOP 中“如果……那么……”规则的自然映射。条件分支在实现时建议集中管理判断逻辑把判断放在单独的边条件函数中而不是在节点内部执行跳转。这样整张图的路径可以审计也为后续可视化提供了可能。3.3 并行扇出模式一个节点产生任务后同时分发到多个子节点并行处理全部完成后再汇总。例如“Agent 需要同时检索多个数据源然后汇总结果”。并行模式真正的工程难点不是并行本身而是汇合节点的“等待策略”是等全部子节点完成还是只要有一个成功就继续这个问题必须由 SOP 业务规则确定。如果规则没有定义默认应该选择“等待全部完成并采集失败信息”的稳妥策略而不是碰到一个失败就放弃整个任务。3.4 循环与重试模式流程中可能需要循环比如“生成文本 - 校验 - 不合格则重新生成”直到质量过关或达到最大重试次数。图里允许节点连接到前置节点形成环。设计循环最需要注意的是终止条件。常见做法是给循环边增加“最大重试次数”的守卫条件超过后将流程导向失败节点避免 LLM 生成一直不合格导致死循环。3.5 子图模式当一个节点内部本身有复杂逻辑时可以把它扩展为一个子图。子图对外表现为一个节点内部可以有完整的流程结构。这种模式特别适合多层 SOP比如“发布流程”包含“变更评审”“灰度发布”“健康检查”三个子流程其中“灰度发布”又独立成一张小图。子图让主图保持清晰又不会丢失细节。这些模式组合起来足以表达绝大多数流程型 Agent。更稳妥的判断是先梳理清业务规则再选架构模式然后再选框架顺序不要反。4. 落地实操最小图执行引擎实现下面开始动手。这个 Demo 不依赖 LangGraph 或任何云服务用 Python 标准库就能跑通目的是把“把 SOP 画成 graphAgent 就能自己跑”的核心思想表现出来。4.1 场景设计一个带条件的 SOP我们设计一个“代码变更申请处理”流程带有条件和失败分支。SOP 如下接收变更申请检验变更描述是否完整检验通过进入人工审批检验不通过直接拒绝并记录原因审批通过后生成执行计划审批不通过结束并通知用户对应图结构为节点 start接收变更申请节点 validate校验描述节点 approve人工审批节点 plan生成执行计划节点 reject拒绝申请节点 end结束执行路径start - validatevalidate 通过 - approvevalidate 不通过 - rejectapprove 通过 - planapprove 不通过 - endplan - end4.2 代码实现节点、边、执行器文件路径agent_sop_graph.pyfrom dataclasses import dataclass, field from typing import Any, Callable, Optional dataclass class Node: SOP 执行图中的节点。 name: str handler: Callable[[dict], dict] metadata: dict field(default_factorydict) def run(self, state: dict) - dict: result self.handler(state) print(f[node] {self.name} 执行完成) return result dataclass class Edge: 节点之间的边可带条件函数。 source: str target: str condition: Optional[Callable[[dict], bool]] None def should_go(self, state: dict) - bool: if self.condition is None: return True return self.condition(state) class SOPGraph: 最小图执行引擎。 def __init__(self): self.nodes: dict[str, Node] {} self.edges: dict[str, list[Edge]] {} self.final_nodes: set[str] set() def add_node(self, node: Node) - None: self.nodes[node.name] node self.edges.setdefault(node.name, []) def add_edge(self, edge: Edge) - None: self.edges.setdefault(edge.source, []).append(edge) def set_final(self, node_name: str) - None: self.final_nodes.add(node_name) def execute(self, start_node: str, initial_state: dict) - dict: current start_node state initial_state.copy() while current not in self.final_nodes: if current not in self.nodes: raise RuntimeError(f未知节点: {current}) latest self.nodes[current].run(state) state.update(latest) next_node None for edge in self.edges.get(current, []): if edge.should_go(state): next_node edge.target break if next_node is None: raise RuntimeError(f节点 {current} 没有满足条件的边流程中断) print(f[edge] {current} - {next_node}) current next_node self.nodes[current].run(state) return state这段代码的核心概念是state字典。所有节点的输入和输出都通过同一个 state 传递接收输入是完整状态返回的字典会合并进状态中。这模仿了 LangGraph 一类框架的 StateGraph 思想。边上的条件函数接收当前 state返回是否走这条边。4.3 用 JSON 表达 SOP 图为了让流程和代码解耦可以把 SOP 图写成配置文件。文件路径sop_config.json{ start: start, final_nodes: [end], nodes: [ { name: start, handler: receive_request, metadata: { description: 接收变更申请 } }, { name: validate, handler: validate_request, metadata: { description: 校验描述完整性 } }, { name: approve, handler: approve_by_human, metadata: { description: 人工审批 } }, { name: plan, handler: generate_plan, metadata: { description: 生成执行计划 } }, { name: reject, handler: reject_request, metadata: { description: 拒绝申请 } }, { name: end, handler: finish, metadata: { description: 结束 } } ], edges: [ { source: start, target: validate }, { source: validate, target: approve, condition: is_pass }, { source: validate, target: reject, condition: is_rejected }, { source: approve, target: plan, condition: is_approved }, { source: approve, target: end, condition: is_not_approved }, { source: plan, target: end }, { source: reject, target: end } ] }JSON 的好处是让 SOP 配置和代码逻辑分离。业务人员可以维护节点和边开发人员只需关注 handler 的实现。如果有多个流程只需要新增配置文件。4.4 编写节点 handler 并驱动执行文件路径run_demo.pyimport json from agent_sop_graph import SOPGraph, Node, Edge def receive_request(state): return {request_id: state.get(request_id, REQ-001)} def validate_request(state): desc state.get(description, ) is_pass len(desc) 10 return {validate_pass: is_pass, validate_reason: 描述超过10个字 if is_pass else 描述过短} def is_pass(state): return state.get(validate_pass, False) def is_rejected(state): return not state.get(validate_pass, False) def approve_by_human(state): # 生产环境中这里通常是一个等待人工审批的节点 return {approved: state.get(manual_approve, True)} def is_approved(state): return state.get(approved, False) def is_not_approved(state): return not state.get(approved, False) def generate_plan(state): plan f已为 {state[request_id]} 生成部署计划 return {plan_result: plan, output: plan} def reject_request(state): msg f申请被拒绝原因{state.get(validate_reason, 未通过校验)} return {output: msg} def finish(state): print(流程结束最终输出, state.get(output)) return state def build_graph(): graph SOPGraph() graph.add_node(Node(start, receive_request)) graph.add_node(Node(validate, validate_request)) graph.add_node(Node(approve, approve_by_human)) graph.add_node(Node(plan, generate_plan)) graph.add_node(Node(reject, reject_request)) graph.add_node(Node(end, finish)) graph.add_edge(Edge(start, validate)) graph.add_edge(Edge(validate, approve, conditionis_pass)) graph.add_edge(Edge(validate, reject, conditionis_rejected)) graph.add_edge(Edge(approve, plan, conditionis_approved)) graph.add_edge(Edge(approve, end, conditionis_not_approved)) graph.add_edge(Edge(plan, end)) graph.add_edge(Edge(reject, end)) graph.set_final(end) return graph if __name__ __main__: with open(sop_config.json, r, encodingutf-8) as f: config json.load(f) graph build_graph() state {request_id: REQ-1001, description: 修复登录接口超时问题} final_state graph.execute(start, state) print(final_state)这段示例中的approve_by_human先采用“默认通过”的临时策略真正生产环境会改成等待外部事件或人工点击确认这部分在后面的工程化建议中展开。运行方式很简单python run_demo.py预期输出中会出现节点执行日志和边跳转日志从日志中就能看到流程按 SOP 预设路径走完了。5. 放进真实 AgentLLM 节点、条件边与工具调用上面这个引擎可以独立跑通流程但还不是真正的 Agent。真正的 Agent 需要在节点里调用 LLM在条件边里用 LLM 判断结果在节点中触发工具调用。5.1 LLM 节点怎么设计LLM 节点和普通节点的差异是“内部调用模型”。一个配置了模型的节点可以接收当前 state将上下文组装成 Prompt再调用模型得到结果把结果写入 state。设计原则是把模型调用封装在节点内部而不是让模型自己决定下一步。下面的代码展示了一个简化实现思路假设你通过环境变量配置了模型 API 地址和密钥import os from openai import OpenAI def llm_generate(state): client OpenAI(api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_API_BASE)) messages [ {role: system, content: 你是 SOP 节点的执行器只专注于当前节点任务。}, {role: user, content: state[task_input]} ] response client.chat.completions.create( modelos.getenv(LLM_MODEL, qwen-plus), messagesmessages, temperature0.2 ) content response.choices[0].message.content return {llm_output: content, output: content}这里的关键是 system 提示词只定义节点内的行为不要写“接下来你要做什么”之类的流程指令。流程由图的边控制。5.2 用 LLM 做条件判断条件边不一定非要写死规则也可以用 LLM 判断。比如校验“用户反馈是否包含明确诉求”时规则写起来很麻烦可以交给模型返回一个 JSON 结构。def llm_condition(state): text state.get(description, ) prompt f这是一个变更申请描述请判断描述是否清晰明确只返回 true 或 false{text} # 调用模型获取判定这里省略请求细节 result call_llm_simple(prompt) return result.strip().lower() true这种写法让 LLM 负责任务理解和语义判断让图引擎负责流程推进。这也是当前 Agent 编排框架普遍采用的分工方式。5.3 工具调用节点工具调用本质上也是一个节点。节点内调用检索、数据库查询、外部 API然后把结果写回 state。一个明确的技巧是把工具的输入参数从 state 中显式取出来不要直接传整个 state 给工具这样可以让工具调用的行为可预测也方便记录审计日志。如果要引入生产级框架Python 生态可以重点看 LangGraph它的核心抽象就是 StateGraph、节点、边和条件边状态流转与上文的最小实现思路一致。Java 生态可以关注 Spring AI Alibaba 的 Graph 模块它把 Agent 编排和 Spring 技术栈融合适合已经在用 Spring 的团队。还有不少低代码平台用可视化节点连线方式配置 Agent 流程底层同样是把 SOP 映射成图执行。6. 运行验证从日志看一条任务怎么走完图图驱动 Agent 的一个重要优势是可观测性。运行过程中应该能看到“执行到哪个节点”“为什么选择这条边”“节点耗时多少”“最终的输出是什么”。以第 4 节的 Demo 为例运行后预期输出类似[node] start 执行完成 [edge] start - validate [node] validate 执行完成 [edge] validate - approve [node] approve 执行完成 [edge] approve - plan [node] plan 执行完成 [edge] plan - end [node] end 执行完成 流程结束最终输出 已为 REQ-1001 生成部署计划判断成功的标准有两条所有节点都按 SOP 顺序执行没有跳过。条件分支只走了匹配的那条边其他候选边没有被选中。如果运行失败先看三个位置节点内部是否抛异常。因为任何节点 handler 出错都会中断循环。条件边是否全部不满足。如果出现“没有满足条件的边流程中断”说明图配置或条件函数有问题。是否进入了非预期节点。这说明边的条件函数优先级写反了多个边同时满足且顺序不对。为了将日志用于生产排障建议每个节点执行时记录 trace_id、node_name、耗时和输入输出摘要汇总到日志中心或调用链系统。这样即使图很长也能回溯问题在哪一步发生。7. 常见问题与排查思路问题现象可能原因排查方式解决方案流程跳到错误节点条件函数优先级或逻辑写错打印每个候选边条件返回值用显式条件函数避免多个条件同时为 true 且顺序不可控出现死循环循环边缺少终止条件或重试次数观察节点日志中反复出现的节点名为循环边增加最大循环次数超限进入失败节点节点执行超时LLM 调用变慢或外部 API 无响应查看调用链耗时确认慢在哪个环节为节点设置超时时间增加重试与降级策略state 被污染节点间共享可变对象打印 state 变化前后的差异节点返回新对象不做原地修改流程卡住不流转等待人工输入的节点没有触发事件检查事件监听和回调地址将人工审批节点改为异步事件驱动配置回调映射LLM 判断不稳定条件边完全依赖模型输出对比多轮输出查看是否随机波动尽量用规则优先无法规则化时再交给 LLM并设置温度接近 0图配置分散在代码里业务人员无法维护 SOP图上没有配置管理将图定义持久化为 JSON/YAML并支持可视化页面预览这里最需要警惕的是“图表达了不该表达的歧义”。如果一条边的条件写得像“如果用户满意”模型很难稳定判断。更好的做法是让 SOP 本身提供判断标准比如“用户明确给出好评关键词”再决定是否交给规则或模型。8. 工程化建议从 demo 到生产把最小 Demo 推向团队和生产环境有几个问题需要在设计阶段就考虑清楚。第一节点要版本化。SOP 会持续优化图定义和节点 handler 应该纳入 Git 管理并且每次修改都要有变更记录。发布新流程时可以采用灰度模式同一份 SOP 先给少量请求使用验证无异常后再全量开放。第二确定性的逻辑不要交给模型。能写规则的条件判断就用代码写死。模型只负责开放性内容生成和语义判断。原因很简单代码是稳定的模型输出是概率性的。SOP 图是流程可靠性的最后防线不能把防线自身也建立在概率之上。第三人工审批节点要做成事件驱动。真实业务中一个审批可能等几小时甚至几天不可能让执行线程一直阻塞等待。更稳妥的做法是把“等待审批”的节点状态持久化到数据库通过消息队列或回调事件恢复流程。小 Demo 为了跑通流程可以同步等待生产环境必须改成异步恢复。第四安全边界要落实到节点级。不同的节点应该持有不同权限。例如“生成执行计划”的节点可以只读权限“调用支付接口”的节点必须有专门的凭证而且凭证不应该放在全局 state 里避免被日志打印出来。最小权限原则同样适用于 Agent 的工具调用。第五超时与重试要成体系。LLM 节点、外部 API 节点、数据库节点都可能失败。建议为节点统一设置超时时间和重试策略重试要有指数退避同时设定最大重试次数。重试后仍然失败流程应该进入失败节点而不是在线程中无限等待。第六可观测性要前置。图执行引擎天然适合输出结构化日志节点名、节点类型、节点耗时、输入输出摘要、边条件命中情况、trace_id。上线之前就要设计好日志规范而不是等出了问题再补。还有一个经常被忽视的点不要一上来就引入复杂框架。先用一个最小的图引擎跑通业务理解节点、边、条件、状态之间的关系如果流程规模变大再切换到 LangGraph 或 Spring AI Alibaba Graph 等成熟实现。技术的价值在于解决实际问题不在于第一步就选一个最重的架构。9. 图不是银弹什么场景不适合硬上 GraphGraph Engineering 能解决流程控制问题但并不是所有 Agent 场景都适合。如果你的需求是开放聊天、头脑风暴、自由问答流程本来就是发散式的强行画图只会限制模型还增加维护成本。这种情况更适合保留纯 Prompt 模式或者只在顶层做一个“判断是否走流程”的分类节点。如果你的 SOP 规则经常变化而且变化频率以天甚至小时为单位那么维护图的成本会变得很高。此时首先要问的不是“怎么画图”而是“SOP 本身是否稳定”。不稳定的流程稳定地执行它没有意义。如果你的流程非常简单只有两三个步骤也没有分支和审批那也不需要图引擎。直接用顺序代码调用更直接。图的价值在于它能把重复出现的流程模式沉淀为可视化资产这个价值在小流程里体现不出来。另外要区分“图执行”和“图数据库”。很多读者看到 Graph Engineering会下意识想用 Neo4j、JanusGraph 之类的图数据库来存 SOP。这是不必要的。Agent 的 SOP 图规模通常不大执行时只需要遍历节点和边内存中的对象或 JSON 配置已经足够。图数据库更适合做深度的关系分析例如社交关系挖掘、知识图谱推理而不是驱动一次流程执行。还要注意一点把 SOP 画成 graph 并不等于放弃 LLM。恰恰相反图的出现让 LLM 可以专注于它最擅长的事情——语义理解、生成内容、处理开放输入。而流程的确定性、可审计性、可恢复性由 Graph Engine 承担。这本质上是一种“分工”图是骨架LLM 是血肉。接下来要做的事情其实很具体找一个你团队里最烦琐、最容易出错、当前靠在线文档和口头交接维持的 SOP把它拆成节点和边先用这套最小的思路跑一遍。你会发现当流程变成图Agent 的稳定性、可控性和可维护性都会有一个非常明显的变化。