Graph Engineering 不是知识图谱，是多 Agent 系统的组织学

如果你最近几个月在折腾多 Agent 系统，大概会撞到同一面墙：单 Agent 已经能跑了，读上下文、拆任务、调工具、失败重试，甚至能挂着过夜跑。但一旦任务跨域——既要改支付逻辑又要保 API 兼容、既要迁数据又要更前端、既要过安全审查又要出发布说明——事情就开始失控。不是 Agent 不够聪明，是组织结构不够清楚。

这个词最近在社区里被反复提到：Graph Engineering。但和大多数人第一反应不一样，它指的不是知识图谱，而是把 Agent 系统本身设计成一张图。这篇文章想把这个区分讲透，并给出一套可以落地的最小清单。

一、先把名字说清楚：这里说的不是知识图谱

Graph Engineering 这个词在 2026 年有两个语境，混在一起会越聊越糊涂。

第一个是传统的 Knowledge Graph Engineering：设计实体、关系、本体、数据集成和图数据库，让系统能围绕"人、组织、事件、文档、产品、决策"做查询和推理。 Microsoft Graph RAG 是这个方向的代表——从非结构化文本里抽实体、关系、声明，做社区发现，生成多层级摘要，再和向量检索结合；查询层分 Local Search 、 Global Search 、 DRIFT Search ，用图结构改进复杂问题的检索质量。 Neo4j 也在推 context graph 概念，强调很多 Agent 问题不是相似度问题，而是结构问题、溯源问题、多跳关系问题。

第二个是 2026 年围绕多 Agent 系统出现的 Agent Graph Engineering：把 Agent 系统本身设计成图。图里的节点不是知识实体，而是 Agent 、角色、组件、检查点；边不是知识关系，而是数据流、控制流、权限流、证据流、失败流。

一句话区分：知识图谱工程解决"系统知道什么"； Agent Graph Engineering 解决"系统由谁组成、如何协作、如何被治理"。

这两个方向会合流，但不能混谈。一个值得在团队里立下的规矩是：每次出现"图"这个词，先问一句"是知识的图，还是组织的图？"——能省掉大半无效讨论。

二、 Prompt 、 Loop 、 Graph ：三层工程化

把 Agent 工程的演进压缩成三句话：

• Prompt Engineering 让一次模型调用更可靠。
• Loop Engineering 让一个 Agent 的行为过程更可靠。
• Graph Engineering 让一组 Agent 的组织协作更可靠。

核心对象在每一层都不一样。 Prompt 关心 instruction——模型看到什么、按什么格式输出、不要做什么。 Loop 关心 control cycle——触发条件、工具调用、状态更新、验证器、重试策略、停止条件。 Graph 关心 topology——节点、边、状态、 artifact 、权限、观测、评价、变更历史。

这三层是互补的，不是替代。每个重要节点内部仍然是一个 loop ；图只是决定 loop 怎么被组织、约束、连接。一个团队如果只在 Prompt 层努力，看不到 Loop 层的工程问题；只在 Loop 层努力，又看不到 Graph 层的组织问题。

判断你站在哪一层有个简单标准：如果你最大的痛点是"模型偶尔输出不对"，你在 Prompt 层；如果是"Agent 跑着跑着就跑偏了"，你在 Loop 层；如果是"多个 Agent 各干各的、结果对不上"，你在 Graph 层。

不是所有任务都需要走到 Graph 层。一个"每天扫一遍 issue 、修简单 bug 、跑测试、开 PR"的清晰 loop ，加图只会增加复杂度。但当任务天然跨域——重构支付系统同时保 API 兼容、迁数据、更前端、过测试、评安全、出发布说明——单 loop 必然变成一团乱麻，你需要的是把"谁做什么、依赖谁、什么并行什么串行、失败怎么隔离、证据怎么留"显式画出来。这件事本质上就是图问题。

三、第一刀：把图拆成 Org Graph 和 Work Graph

最常见的新手错误，是把所有东西画进一张大图。生产系统通常需要两张图。

Org Graph （组织图）：相对稳定，描述长期角色和边界。一个工程团队的 Agent 组织可能有产品、架构、前端、后端、数据、安全、测试、发布、成本这几个角色。它们的价值来自长期上下文——一个 Security Agent 知道哪些接口有遗留风险、历史上出过哪些认证问题、哪些日志绝对不能暴露。这些记忆不随任务结束而消失。

Work Graph （工作图）：为某次任务运行临时生成的图。不同任务——登录重构、计费改造、多租户迁移——产生不同的工作图。工作图描述这次任务怎么拆、怎么并行、怎么汇合、怎么终止。分支可以动态增加（发现数据迁移复杂度上升，临时加一个 Data Migration 分支），也可以提前终止（安全检查发现没动权限模型，直接收掉这条线）。

• Org Graph 回答：长期谁在、谁负责什么。
• Work Graph 回答：这次任务现在在哪、下一步谁依赖谁。

很多团队失败的原因是想用一张固定流程图覆盖所有任务——简单任务被过度编排，复杂任务又缺弹性。好的 Graph Engineering 让稳定角色和动态任务共存： Org Graph 是底座， Work Graph 是每次任务在上面长出来的临时拓扑。

四、节点不是"多个 Chatbot"

很多多 Agent demo 看着很酷，其实只是把一个混乱的聊天线程拆成几个有名字的参与者。真正的图节点必须有工程含义。一个合格的节点要定义六件事：

1. 责任边界：管什么、不管什么。 Security Agent 可以否决权限变更，但不能改产品需求。
2. 输入契约：启动需要哪些 artifact 。 Test Agent 需要的是 spec 、 diff 、失败日志、测试环境约束，不是一句"帮我测一下"。
3. 输出契约：必须交付哪些结构化结果。不是"看着没问题"，而是风险列表、覆盖缺口、可复现步骤、是否阻塞发布。
4. 工具权限：能读什么、写什么、执行什么。安全节点能读审计日志，但可能不能部署服务。
5. 状态范围：长期记忆保留什么、任务内 scratchpad 写什么、必须写到 ADR 或项目日志的又是什么。
6. 退出条件：什么时候算完成、什么时候重试、什么时候升级到人。

Anthropic 的多 Agent 研究系统架构是个好参照： lead agent 创建专门的 subagent 做并行探索，然后聚合结果。 Claude Agent SDK 强调 context isolation——subagent 在独立上下文里工作，父节点只接收最终结果。这些设计防止上下文污染、降低主上下文负担、让并行探索可控。

Graph Engineering 在这之上多走一步：不只是能 spawn subagent ，而是把"谁能 spawn 、怎么收回、怎么验证结果、怎么隔离失败"做成图规则。这一步从"运行时能力"变成"设计时约束"，是工程化和 demo 的分水岭。

五、边比节点更重要

如果节点是角色，边就是组织制度。很多 Agent 系统的失败不在节点，在边。 Graph Engineering 要求把边也设计成契约，每条边表达五类语义：

1. 数据流：上游输出什么、下游消费什么（ spec 、 ticket 、 diff 、 trace 、 eval 报告）。
2. 控制流：下游什么时候启动——总是、有条件、并行、 join 、需要人批准。
3. 权限流：下游是继承上游权限，还是申请最小权限。
4. 证据流：哪些中间证据必须留全量、哪些可以摘要、哪些必须带引用。
5. 失败流：上游失败时下游怎么办——重试、降级、跳过、中止、升级。

LangGraph 的 StateGraph 把这部分工程直觉产品化了：定义状态、加节点、用普通边和条件边连起来。它的价值不在于"图"这个词新，而在于把藏在 prompt 里的隐式流程逼到明面上。但框架只是基础设施，真正的工程能力是能不能说清每条边的契约。

一个可参考的验收标准：拿一张 Agent 系统的图给一个新来的工程师看，如果他能在 10 分钟内说清"谁向谁要什么、失败怎么办"，设计就过关；如果还要回头翻 prompt 才能理解，那就是画了张好看的图，没真做工程。

六、四类状态，必须分开管

单 Agent 的 loop 通常管这几样东西：对话上下文、 scratchpad 、工具结果、最终输出。图系统至少要分四类状态：

1. Run State：当前这次运行在哪——哪些节点完成、哪些失败、哪些分支在等 join 。
2. Artifact State：系统产出过什么——PRD 、 spec 、设计文档、 diff 、测试报告、评审意见、发布说明。这些不应该埋在聊天历史里。
3. Memory State：跨运行要保留什么。 LangChain 的长期记忆按 namespace + key 组织成 JSON 文档，记忆应该是可定位、可更新、可搜索的工程对象，不是一坨历史对话。
4. Evidence State：当前判断的依据是什么——来源链接、日志片段、 trace span 、测试输出、用户确认、人工审批。

这四类必须分开管。混在一起必然出问题：

• 把 Run State 写进长期记忆， Agent 会把一次临时失败当成项目事实。
• 把 Evidence State 压缩成一句总结， Review Agent 就没法审计判断。
• 把 Artifact State 只存在聊天里，下一轮任务会重新发明设计。
• 把 Memory State 不分命名空间，多个 Agent 会互相污染。

Graph Engineering 的本质之一，就是让状态不再漂在上下文窗口里，而是被图的节点和边显式持有。这一条做不做得到，是图系统和"多开几个聊天窗口"的区别。

七、 Anchor ：防止图自己骗自己

多 Agent 系统最危险的地方，不是某个 Agent 犯错，而是错误在图里被放大。

一个 Research Agent 找到低质量资料， Writer Agent 写得很流畅， Reviewer Agent 只检查结构不查来源， Publisher Agent 顺利发布。每个节点都"完成了自己的任务"，但整个系统输出了错误内容。这就是图系统的自洽幻觉——每个节点都自洽，整体却错了。

Graph Engineering 必须设计 Anchor，也就是系统不能随意改写的外部参照。 Anchor 可以是：来源 URL 、测试执行结果、人工审批、版本锁定的 spec 、不可变审计日志。

一条实用规则：没有任何优化节点可以单方面修改自己的目标函数。

• Cost Optimizer 可以建议减少模型调用，但不能降低质量阈值。
• Release Agent 可以建议跳过非阻塞检查，但不能改"必须过安全审查"这条。
• Writer Agent 可以压缩引用，但不能删掉关键事实来源。

没有 anchor 的图，只是一个更复杂的 loop 。

这句话值得贴在团队 wiki 第一页。多 Agent 系统出怪问题的时候，先问一句"它的 anchor 在哪？"，多半能定位到根因。

八、最小落地清单： 5 个文件，不是上个平台

要在真实团队里启动 Graph Engineering ，不需要一个庞大的多 Agent 平台。从这 5 个文件开始：

1. org-graph.md：长期 Agent 角色、责任边界、工具权限、长期记忆位置、升级路径。
2. work-graph-template.md：常见任务的工作图模板（功能交付、 bug 诊断、安全审查、内容发布、数据迁移）。
3. artifact-contracts.md：每种 artifact 的输入、输出、验收标准（ spec 格式、评审意见必填字段、测试报告复现要求）。
4. edge-policies.md：边的规则——哪些边允许并行、哪些要人工批准、哪些只传摘要、哪些必须传全量证据。
5. graph-observability.md：每次运行必须记录什么——run id 、 node id 、 edge id 、 artifact id 、 token 成本、延迟、工具调用、失败原因、人工介入点、最终结果。

这 5 个文件不性感，但比"再加三个 Agent"更接近工程。一个推荐的落地路径是：把这 5 个 markdown 放进仓库的 .agent-graph/ 目录，每次任务跑完用脚本对一遍 observability 和 edge-policies ，对不上就开 issue 。坚持下去，多 Agent 系统的"诡异失败"会逐渐从随机出现变成可定位——不是因为模型变聪明了，是因为错的地方被显式约束住了。

九、什么时候别用图

Graph Engineering 有真实成本：设计角色、定边界、维护状态、记 trace 、处理失败传播、避免 Agent 间信息过载。

不要用图的场景：任务是单域、线性、低风险，成功标准清晰，不需要跨运行记忆，不需要可审计证据。一个 loop 甚至一个好 prompt 就够了。强行上图等于给自己加协调负担。

考虑用图的场景：任务跨多个域，需要不同工具权限，需要并行探索再汇合，需要审计轨迹和证据保留，是长流程需要中间检查点，需要在特定点上接入人工。

判断标准不是"是不是多 Agent"，而是"拓扑里有没有承载真实约束"。如果图只是好看，那是装饰；如果图决定了谁能做什么、信息怎么流、失败怎么恢复、证据怎么留，那才是工程。

两种典型反例和正例可以帮助校准判断。反例：给"生成一份周报"这种单域任务画 8 个节点的图，每个节点一个 Agent ，跑一次十几分钟、几十美元——这是把图当装饰。正例：用 3 个节点的图管"代码改动 -> 安全审查 -> 发布"，节点之间有清晰的 artifact 传递和人工 gate——这才是图该干的事。区别不在节点多少，在于边和状态是否承载真实约束。

十、回到根本：下一代 Agent 工程不是聊得更好

Agent 能力会继续涨——模型更强、工具调用更稳、上下文更长、代码能力更好。但工程问题不会消失。

一个 Agent 你可以用 prompt 、 loop 、人工盯、脚本管。几十个 Agent 、几十个工具、多块长期记忆、动态任务分支、不同权限边界放在一起，你需要的不是"更聪明的助手"，而是可治理的组织结构。

Graph Engineering 要求把 Agent 系统当成分布式组织来设计：每个节点有责任，每条边有契约，每类状态有归属，每个判断有证据，每次变更可重放。

• Prompt 让模型听懂你。
• Loop 让 Agent 持续行动。
• Graph 让一群 Agent 在行动中不失控。

这是"会用工具的 Agent 工程"和"能上生产的 Agent 工程"之间的分界线。

如果你已经在 Loop 层做得不错，下一步不是把模型换得更强，而是把你团队现在跑的多 Agent 流程画成一张图——先画 Org Graph ，再为最近一次真实任务画 Work Graph ，对照本文的 5 个文件清单补齐缺口。这一步走完，你会看到完全不同的工程画面。

JOTO 企业落地观察

• 对企业部署意味着：Graph Engineering 不是引入新框架，而是将已有 Agent 流程显式建模为 Org/Work 双图结构，其核心挑战在于组织角色定义与状态生命周期管理，而非技术选型。
• 这类系统的取舍在于：当任务涉及跨职能协作与强审计要求时，图结构带来的可观测性与失败隔离能力，远超其设计与维护成本；反之，单域线性任务强行图化反而增加协调熵。
• 在智能体工程中，Graph Engineering 的落地成败取决于能否将“边”的五类契约（数据流、控制流、权限流、证据流、失败流）转化为可验证的运行时约束，而非仅停留在设计图层面。
• 对 AI 安全治理而言，Anchor 机制提供了关键抓手：它要求所有优化类节点不得篡改基线目标函数，从而将安全红线从模型层下沉至系统拓扑层，形成可审计的硬性边界。

JOTO 企业落地观察

• 对企业部署意味着：Graph Engineering 不是引入新框架，而是将已有 Agent 流程显式建模为 Org/Work 双图结构，其核心挑战在于组织角色定义与状态生命周期管理，而非技术选型。
• 这类系统的取舍在于：当任务涉及跨职能协作与强审计要求时，图结构带来的可观测性与失败隔离能力，远超其设计与维护成本；反之，单域线性任务强行图化反而增加协调熵。
• 在智能体工程中，Graph Engineering 的落地成败取决于能否将“边”的五类契约（数据流、控制流、权限流、证据流、失败流）转化为可验证的运行时约束，而非仅停留在设计图层面。
• 对 AI 安全治理而言，Anchor 机制提供了关键抓手：它要求所有优化类节点不得篡改基线目标函数，从而将安全红线从模型层下沉至系统拓扑层，形成可审计的硬性边界。