图工程有两重含义。《深入图工程》讨论的是以图数据为中心的系统工程——图数据库、图计算引擎、知识图谱。本文讨论第二重：当 Coding Agent 系统本身成为一个图结构的工程制品时，传统图工程的哪些原理可以复用，哪些问题是全新的。

2024-2026 年间，Agent 系统从"一个 LLM 调用 + 几个工具"扩展到多步骤、多角色和可恢复执行。LangGraph 直接使用状态图；CrewAI 以 agents、tasks、crews 和 flows 为主要抽象；AutoGen 同时提供 conversation、team 与实验性的 GraphFlow。图适合作为统一分析视角，但不能把不同框架都改写成同一种图调度器。

Agent 系统中的三类图结构

Agent 系统至少包含三类不同性质的图，它们在生命周期、变化频率和工程约束上各不相同：

执行图（Execution Graph）：Agent 单次任务执行的控制流。每个节点是一个计算步骤（LLM 调用、工具执行、条件判断），边表示控制转移。LangGraph 的 StateGraph 是这一类的典型代表。执行图在运行时动态展开，可能包含循环（Agent 反复修正直到满足条件），因此严格说不是 DAG 而是有向图。

协调图（Coordination Graph）：多个 Agent 之间的通信和协作拓扑。节点是 Agent 实例，边表示消息通道或委派关系。这类图的拓扑在设计时确定，但运行时可能动态增减节点（如按需创建 sub-agent）。

知识图（Knowledge Graph）：Agent 用于理解代码的结构化上下文。节点是代码实体（函数、类、模块、变量），边是调用关系、继承关系、数据流依赖。这类图在 Agent 的 planning 阶段被查询，为 LLM 提供定位精确的上下文而非全量代码。

三类图的交叉点是：协调图决定"谁来做"，执行图决定"怎么做"，知识图提供"代码之间如何关联"的上下文。系统可以只使用其中一类；只有任务确实涉及多 Agent、可恢复执行和跨模块代码理解时，三者才需要共同出现。

执行图：从 LangGraph 状态机说起

LangGraph 的图语义

LangGraph 由 LangChain 团队在 2024 年初公开，v1.0 在 2025 年 10 月发布。它是有状态 Agent 编排的重要实现之一；"使用最广"需要下载量、活跃项目或生产部署等明确口径，本文不作排名。其核心模型包括：

  • 节点（Node）：一个 Python 函数，接收当前状态、返回状态更新。可以是 LLM 调用、工具执行、纯逻辑判断。
  • 边（Edge）：节点间的转移关系。支持条件边（根据状态值路由到不同下游节点）和无条件边。
  • 状态（State）：贯穿整个图执行的共享数据结构，由 TypedDict 或 Pydantic model 定义。节点返回部分状态更新；字段配置 reducer 时按 reducer 合并，未配置时通常覆盖原值。
  • 检查点（Checkpoint）：状态的持久化快照。支持断点续跑、time-travel debugging、human-in-the-loop 中断。

LangGraph 的边支持循环，Agent 可以反复执行"思考→行动→观察"直到满足终止条件。它更接近有状态的有向图运行时，而不是纯 DAG 调度器；由于状态值可能来自文本、工具结果和外部系统，把它严格称为"有限状态机"也会掩盖状态空间并不有限的事实。

执行图的工程问题

把 Agent 工作流建模为图之后，传统图工程的若干经典问题立即浮现：

状态爆炸。当多个二元分支彼此独立时，路径组合可以随分支数指数增长；一般图的路径数还取决于分支度、循环和终止条件。工程上的应对是限制循环次数（如 LangGraph 的 recursion_limit）、覆盖关键不变量，并把模型输出与确定性的状态转移逻辑分开测试。

非确定性。相同输入的 LLM 调用可能产生不同输出，执行路径随之改变。Temporal 等持久化工作流要求工作流代码可确定重放，但把 LLM/API 调用放在 Activity 等外部步骤中；这不意味着外部结果本身确定。Agent 图的重试必须区分状态重放、节点重执行和外部副作用，还要决定是否保留前一次失败信息。

热点节点。执行图中某些服务会被多条路径共享，例如代码审查或大型模型调用。是否需要扩容应由并发数、队列时间、限流和缓存命中率证明。复制无状态 worker 属于普通水平扩展，不等同于图计算的 vertex-cut；如果节点读写共享状态，复制还会引入一致性问题。

可观测性。单条执行 trace 通常表现为调用树；异步因果关系通过 OpenTelemetry links 等机制可以形成 DAG。LangSmith、Langfuse 等平台能做路径、延迟和失败分析，但跨线程共享状态、重试和异步工具调用需要显式关联，不能只靠树形父子 span 还原。

与传统工作流的对比

维度 Airflow Temporal LangGraph
控制结构 DAG 可分支、循环的持久化工作流代码 允许循环的有向状态图
计算单元 Operator/Task Workflow + Activity 普通函数、工具或 LLM 节点
路由来源 DAG 与条件 确定性工作流代码 确定性条件或模型结果
状态与历史 XCom、外部存储 事件历史与持久化状态 共享状态与 checkpoint
恢复语义 任务重试、补数 重放 Workflow、重试 Activity 从 checkpoint 恢复或重执行节点
终止条件 DAG run 完成 Workflow 返回或终止 业务条件、结束节点或递归上限

协调图：多 Agent 拓扑

四种基本拓扑

当系统需要多个 Agent 协作时，它们的通信结构形成一张协调图。2026 年的框架和生产系统中观察到四种基本拓扑：

星形（Supervisor）。一个中心 Agent 负责任务分解和分发，多个专职 Agent 执行子任务并向中心报告。LangGraph 的 multi-agent 示例、Claude Code 的 subagent 模式都是这种拓扑。优点是控制流清晰、容易推理；缺点是中心 Agent 成为瓶颈和单点故障。

链式（Pipeline）。Agent 按固定顺序依次处理，前一个的输出是后一个的输入。适合明确的阶段性任务（需求分析 → 设计 → 编码 → 测试）。CrewAI 的 sequential process 属于此类。优点是简单可预测；缺点是缺乏反馈循环，前期错误会传播到后期。

层级（Hierarchical）。多层 supervisor 形成树状结构，顶层 Agent 分解为子任务，子任务 Agent 可以进一步分解。AutoGen 的嵌套对话和 LangGraph 的子图（subgraph）机制支持这种模式。适合复杂任务的递归分解。

handoff 网络。Agent 通过工具调用把控制权交给另一个 Agent。OpenAI Swarm 是 2024 年的实验性示例，但官方仓库已经说明它由 OpenAI Agents SDK 取代。Swarm 的 handoff 仍由客户端运行时协调，不能据此推断系统没有中心控制或单点故障。

协调图的工程约束

从图工程角度看，协调图的设计面临几个硬约束：

通信开销与图直径。两个 Agent 之间的信息传递跳数会影响协作延迟。星形拓扑在 worker 之间的直径是 2；全连接图的直径是 1；任意连通图的最坏直径是 n-1。真实延迟还受消息大小、上下文重建和模型调用支配，图直径只能解释其中一部分。

状态一致性。多个 Agent 并发修改共享代码库时，一致性问题等同于分布式系统中的并发写入。实际方案包括：乐观锁（每个 Agent 基于当前快照修改，提交时检测冲突并重做）、悲观锁（一次只有一个 Agent 持有某文件的修改权）、或分区隔离（每个 Agent 只修改自己负责的文件集）。

容错与优雅降级。协调图中的某个 Agent 失败（LLM 调用超时、工具执行报错）时的处理策略：重试该节点、将任务转交给其他同类 Agent、或向 supervisor 报告并由其重新规划。这与分布式系统中的故障检测和任务重调度是同构问题。

Agent 记忆的图结构

Episodic Memory Graph

Agent 的对话历史和任务执行轨迹形成一张时序事件图（episodic memory graph）。节点是事件（用户请求、Agent 决策、工具调用结果），边表示因果关系或时间顺序。当 Agent 需要回顾"上次遇到类似问题时怎么解决的"，本质上是在这张图上做模式匹配。

Zep 把 temporal knowledge graph 作为记忆能力的一部分。Mem0 曾提供 graph memory，但当前迁移文档说明开源 SDK 已移除 graph store，改用 entity linking。两者都不支持"图遍历取代向量检索"这一概括：生产记忆通常混合实体链接、时间、关键词和向量相似度，图中的边也只有在抽取和来源可靠时才能代表因果关系。

Skill Dependency Graph

Coding Agent 的能力集合形成一张依赖图。每个 skill（如"运行测试"、“创建 PR”、“安装依赖”）是一个节点，skill 之间的前置条件是有向边。比如"创建 PR"依赖"提交代码"，“提交代码"依赖"通过测试”。

Skill dependency graph 可以作为 harness 的显式设计：用前置条件约束工具顺序，再按成本、风险或权限选择可行路径。但公开资料不足以证明 Claude Code、Codex 都用带权最短路径完成 planning。这里描述的是一种可实现的工程模型，而不是这些产品的已知内部机制。

代码知识图谱作为 Agent 运行时上下文

代码知识图谱将代码库的结构关系（调用图、继承树、模块依赖、数据流）持久化为可查询的图结构。与直接在 prompt 里塞代码文本相比，图结构的优势是支持精确的多跳定位：

  • “这个函数的调用者中有哪些也修改了同一个全局变量”——两跳查询
  • “这个接口的所有实现类里，哪些覆盖了 validate 方法”——条件过滤遍历
  • “从这个入口函数出发，经过最多 3 次调用能到达哪些数据库操作”——限定深度的可达性分析

Graphify 和 Sourcegraph SCIP 代表两条路线。Graphify 对代码使用 tree-sitter 做确定性解析，对文档等非代码资产再做语义抽取，并可用 Leiden 做社区发现；SCIP 提供精确的符号、定义和引用索引。LSIF 是 SCIP 的前身，不应再与 SCIP 并列为当前推荐格式。

关键工程决策是知识图谱的更新策略。代码库在开发过程中持续变化，知识图谱如果不能增量更新就会快速过时。实际方案分三种：

  1. 全量重建：每次 Agent 任务开始时重新扫描整个代码库。简单但慢，只适合小型代码库。
  2. 增量更新：监听文件变更事件，只重建受影响的子图。需要精确的依赖追踪——修改一个函数签名可能需要更新所有调用者节点。
  3. 惰性验证：图结构保持旧状态，查询结果在使用前与当前文件内容做一致性校验。查到的节点如果对应的代码已变更则标记为 stale 并实时刷新。

从传统图工程到 Agent 图工程

可复用的原理

传统图工程的若干核心洞察直接适用于 Agent 图系统：

热点需要测量，不能预设幂律。Supervisor 或共享工具可能成为高负载节点，代码知识图中的核心模块也可能高入度，但是否呈幂律要由 trace 和度分布验证。确认热点后，才选择限流、缓存、分片、副本或采样。

任务切分可以借用图分区目标。当任务有显式依赖图、通信成本可估计且每个子任务有清晰所有权时，可以用"减少跨分区边"分析分工。一般的自然语言任务分解还受权限、上下文窗口、专业能力和可并行性约束，不能直接宣布为同一个 NP-hard 图分区问题。

可观测性问题可以借用图分析语言。热点路径、关键路径、循环次数和扇出适合用图指标描述；但 Agent trace 还需要 token、模型、提示词版本、工具副作用和人工审批等图数据库没有的维度。

全新的挑战

但 Agent 图有几个传统图工程从未面对的问题：

节点行为包含概率性部分。相同输入的 LLM 节点不保证相同输出，这会扩大状态空间并削弱简单回归断言，但不会让死锁检测和终止性分析整体失效。确定性外壳仍可检查最大步数、资源上限和允许的状态转移；概率模型则需要统计测试或概率模型检查。

运行实例和图定义需要分开。Agent 可以创建 sub-agent 实例，也可以在代码索引中发现新边，但这不等于框架的编译图被自我修改。LangGraph 的 subgraph 通常需要在构建时可发现；动态 Send、Command 或 handoff 改变的是本次执行的路由和实例集合。

成本模型完全不同。传统图计算主要消耗 CPU 和网络带宽，Agent 图的瓶颈则常是 LLM API 的延迟和费用。一次不必要的 LLM 调用，代价远高于传统图计算中的一次冗余消息传递。因此，设计图时应标出高成本边，先用确定性逻辑过滤，再决定是否触发 LLM 节点。

工程实践模式

执行图的分层设计

复杂 Coding Agent 可以采用分层执行图：

  • 顶层：任务级 DAG（需求分析 → 方案设计 → 实现 → 验证），节点间是粗粒度依赖
  • 中层：每个顶层节点内部展开为一个可循环的状态机（思考 → 行动 → 观察 → 判断是否完成）
  • 底层：单次 LLM 调用 + 工具执行的原子操作

分层的价值是隔离复杂度：顶层表达跨阶段依赖，中层控制局部循环与恢复，底层封装模型和工具副作用。小型任务不需要三层；普通函数调用和单一循环更容易测试时，应优先保留简单结构。

测试 Agent 图

Agent 图的测试困难程度高于传统工作流：

  • 路径覆盖不现实：有循环的图路径数量无限，只能测试关键路径和边界条件
  • 断言难以写：LLM 输出的正确性是模糊的（"回答是否有帮助"没有精确的 assertEqual）
  • 环境依赖重：Coding Agent 需要真实的代码库、文件系统、构建工具链作为测试环境

实际方案是分层测试：

  1. 节点级单测：用确定性的 mock LLM 响应测试单个节点的状态更新逻辑
  2. 子图集成测试：用小型代码库 fixture 测试关键子图的端到端行为
  3. 全图回归测试：保存脱敏输入、图版本和 checkpoint，从选定状态重新执行，并用结构化规则或评审器比较结果。外部工具必须使用只读、沙箱或幂等替身

图的版本管理

Agent 执行图本身也需要版本管理。当你修改了一个 Agent 的 prompt 或增加了一条条件边，如何确保不会引入回归？

LangGraph 的检查点机制可以保存状态并从既有 checkpoint 继续执行，但 replay 会重新执行后续节点，LLM 和 API 调用也可能再次发生。因此新旧图对比不能直接把 checkpoint 当作确定性回归 oracle。Shadow 测试必须隔离写操作、凭证和费用，使用脱敏流量、只读工具、幂等键或沙箱副本，才能避免重复提交代码、发消息或调用生产接口。

选型参考

需求场景 推荐起点 理由
单 Agent + 工具调用 + 简单循环 LangGraph StateGraph 状态管理和循环支持是核心价值
固定流程的多 Agent 协作 CrewAI sequential/hierarchical 声明式配置比编程式 graph 更快上手
需要按任务扇出临时 worker LangGraph Send/Command 或 Agent Framework workflow 动态实例与编译图定义分开管理
研究性多 Agent 对话 AutoGen / Microsoft Agent Framework 对话式协调比图式调度更灵活
代码库级别的知识图谱构建 先评估 SCIP/LSP；跨资产语义关系再评估 Graphify 精确符号索引优先，语义图按收益增量引入
需要 Human-in-the-loop LangGraph checkpoint + interrupt 内置中断/恢复机制

这张表不是默认采购清单。代码库规模不大、任务以局部符号查找为主时，grep、LSP/SCIP 和普通调用栈通常比图数据库更便宜；流程没有循环、恢复和人工中断时，普通函数或 durable workflow 也比引入 Agent 图更容易验证。

参考资料