《AI Agent 技术原理与架构·运行时、协议与系统架构》1.1 控制面、执行面、数据面

Agent 的一次运行可以拆成三个平面:控制面决定做什么、执行面承担副作用、数据面记录事实。三者的故障可恢复性完全不同,拆开它们才知道该把重试、幂等与审计分别放在哪一层。本节用同一份计划跑四类故障注入,量化副作用次数,给出 W1/W2/W3 各自的最低平面要求。

以下运行 ID、计划、故障点与数字均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。W3 的"重启服务"是用于展示三平面职责的最小例子,真实系统还需要审批、变更窗口与审计。

一个 Agent 跑一次任务,看起来是一段顺序代码。但在生产里,这次运行横跨了三套不同的职责:谁决定下一步做什么,谁真正去执行副作用,谁记录已经发生的事实。把三者混在一起,是运行时架构最常见的起点错误——因为它们的故障行为完全不同,可恢复性也完全不同。

这一节回答三件事:控制面、执行面、数据面各自是什么;为什么必须拆开;以及故障落在不同平面时,恢复策略分别是什么。最后用一个可运行的最小实验,把四类故障注入到同一份计划上,量化副作用次数。

三个平面:职责、故障与可恢复性

三个平面是一组职责划分,不是三个进程。它们可以部署在同一个进程里,也可以分布在不同的服务上;关键是职责边界清晰。

平面回答的问题典型动作是否有副作用故障时的可恢复性
控制面下一步做什么选动作、调度、重试策略、终止判断否高:决策可以重放
执行面真正执行动作调用工具、调用模型、写数据库是中:取决于副作用是否幂等
数据面发生过什么记录状态、记录动作结果、保存日志追加写依赖:事实丢失则无法恢复

控制面没有副作用,这是它最大的优点。 控制面做的决定(选哪个动作、要不要重试、是否终止)本身不改变外部世界。如果控制面崩溃了,只要数据面还记录着事实,它可以从头重放决策而不产生新的副作用。这正是"持久化执行"能成立的根源:工作流代码可重放,是因为它不碰副作用。

执行面是唯一产生副作用的地方。 工具调用、模型调用、数据库写入,都在这里发生。执行面的故障分两种:副作用没发生,和副作用已发生但结果没记录。前者重试安全,后者重试会制造第二次副作用——这是整个运行时架构里最难处理的故障类型。

数据面记录事实,是另外两个平面的锚点。 没有数据面,控制面不知道走到哪了,执行面不知道什么已经做过。数据面本身也会丢,但那是另一种故障:事实丢失意味着已经发生的副作用无法被追溯,只能对账或人工核对。

为什么必须拆开:故障半径

把三个平面拆开,不是为了整洁,而是为了控制故障半径。

假设控制面和执行面不分家:决定和执行写在同一个函数里。那么"决定错了"和"执行坏了"就会混在一起,重试时你不知道重试的是决策还是副作用。更糟的是,一旦决定本身依赖执行结果(先查再改),两个平面互相纠缠,你既无法重放决策,也无法安全重试执行。

一个反例最能说明问题。早期 Agent 实现里,“调用工具并记录结果"常常写成一个函数:先调用,再写日志,最后返回。如果日志写在调用之后,崩溃恰好发生在两者之间,你就得到"工具已经执行、日志没有记录"的状态。这个状态让所有下游决策都失效,因为控制面无法区分"没执行过"和"执行过但没记录”。三平面分离的实质,就是把"记录事实"提升为一等职责,而不是调用代码里的附带动作。

分拆后的收益可以概括成一句话:控制面可以重放,执行面必须幂等,数据面必须可靠。 三者各自有一套独立的加固手段,而不是一个笼统的"加重试"。

恢复策略取决于故障落在哪个平面

给定同一份计划(动作 A、B、C),故障发生在不同平面时,正确的恢复动作完全不同:

故障位置发生了什么恢复动作副作用变化
控制面决策游标丢失,事实完好从头重放计划,数据面兜底不增加
执行面(副作用前)动作没执行重试该动作增加一次
执行面(副作用后、记录前)副作用已发生,结果没记录重试需外部幂等键去重可能重复
数据面事实全部丢失无法追溯,只能对账不可控

这份表是运行时架构评审的起点:先问"故障可能落在哪个平面",再决定用哪套机制。把"加重试"挂在嘴边,但说不清要防的是哪个平面的故障,等于没有策略。

最小实验:四类故障注入

下面的实验把三个平面写成可运行的类,用同一份计划 A→B→C 跑四类场景。它不依赖数据库、消息队列或工作流引擎,全部状态在内存里;生产系统把数据面换成持久化实现,但语义不变。

# file: agp_lab/control_planes.py | write
# tier: 3
# verify: python3 -m unittest tests.test_control_planes
"""控制面、执行面、数据面:职责分离与故障注入。

Agent 的一次运行可以看作三个平面的协作:

- 控制面:从计划里选出下一个动作(决策,本身无副作用);
- 执行面:真正执行工具调用(副作用在这里发生);
- 数据面:保存已发生的事实(动作结果)。

可恢复性与故障落在哪个平面强相关。本模块用同一份计划
跑四类场景(无故障 / 控制面故障 / 执行面"副作用已发生
未记录" / 数据面丢失),统计副作用次数,说明:
控制面故障可以靠数据面幂等兜底,执行面崩溃需要幂等键,
数据面丢失则无法自动恢复。
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


@dataclass(frozen=True)
class Action:
    name: str


@dataclass
class DataPlane:
    """数据面:只追加地记录已发生的事实(动作结果)。"""

    results: dict[str, str] = field(default_factory=dict)

    def record(self, name: str, result: str) -> None:
        self.results[name] = result

    def has(self, name: str) -> bool:
        return name in self.results

    def get(self, name: str) -> str:
        return self.results[name]

    def wipe(self) -> None:
        self.results.clear()


class ControlPlane:
    """控制面:从计划中依次选出动作;游标丢失可从头重放。"""

    def __init__(self, plan: list[str]) -> None:
        self.plan = list(plan)
        self.index = 0

    def next_action(self) -> Action | None:
        if self.index >= len(self.plan):
            return None
        action = Action(self.plan[self.index])
        self.index += 1
        return action

    def reset(self) -> None:
        """模拟控制面故障:游标丢失,计划可从头重放。"""
        self.index = 0


class ExecutionPlane:
    """执行面:真正产生副作用;幂等去重由数据面兜底。"""

    def __init__(self, data: DataPlane) -> None:
        self.data = data
        self.side_effects = 0

    def execute(self, action: Action, crash_after_side_effect: bool = False) -> str | None:
        if self.data.has(action.name):
            return self.data.get(action.name)
        # 真正的副作用:只在这里 +1。
        self.side_effects += 1
        result = f"done:{action.name}"
        if crash_after_side_effect:
            # 模拟崩溃:副作用已经发生,但结果还没写进数据面。
            return None
        self.data.record(action.name, result)
        return result


PLAN = ["A", "B", "C"]


def simulate(fault: str) -> dict[str, Any]:
    """按故障类型运行 PLAN,返回副作用次数与已记录事实。

    fault 取值:
    - "none"        :正常运行;
    - "control"     :第一次完成后控制面游标丢失,重放由数据面兜底;
    - "exec-side"   :B 的副作用已发生但结果未记录,恢复时无幂等键;
    - "data"        :崩溃后数据面事实全部丢失。
    """
    data = DataPlane()
    exec_plane = ExecutionPlane(data)

    def replay(names: list[str]) -> None:
        for name in names:
            exec_plane.execute(Action(name))

    if fault == "none":
        replay(PLAN)
        return {"side_effects": exec_plane.side_effects, "recorded": sorted(data.results)}

    if fault == "control":
        replay(PLAN)
        # 控制面故障:游标归零,重放计划;结果全部命中数据面缓存。
        replay(PLAN)
        return {
            "side_effects": exec_plane.side_effects,
            "recorded": sorted(data.results),
            "note": "重放命中缓存,副作用不增加",
        }

    if fault == "exec-side":
        # 崩溃点:A 已确认,B 副作用已发生但结果未记录,C 未执行。
        exec_plane.execute(Action("A"))
        exec_plane.execute(Action("B"), crash_after_side_effect=True)
        # 恢复:重放 B、C。无外部幂等键时,B 的副作用会重复。
        replay(["B", "C"])
        return {
            "side_effects": exec_plane.side_effects,
            "recorded": sorted(data.results),
            "note": "B 副作用重复,需要外部幂等键",
        }

    if fault == "data":
        replay(PLAN)
        data.wipe()
        replay(PLAN)
        return {
            "side_effects": exec_plane.side_effects,
            "recorded": sorted(data.results),
            "note": "事实全部丢失,副作用全部重复",
        }
    raise ValueError(f"未知故障类型: {fault}")


def demo() -> dict[str, Any]:
    """打印四类故障下的副作用次数对比。"""
    rows = {}
    for fault in ["none", "control", "exec-side", "data"]:
        rows[fault] = simulate(fault)
    return rows


if __name__ == "__main__":
    print(f"{'fault':<12}{'side_effects':<14}{'recorded':<20}note")
    for fault, result in demo().items():
        print(
            f"{fault:<12}{result['side_effects']:<14}"
            f"{','.join(result['recorded']):<20}{result.get('note', '-')}"
        )

运行:

cd private/labs/agp-lab
python3 -m agp_lab.control_planes

输出:

fault       side_effects  recorded            note
none        3             A,B,C               -
control     3             A,B,C               重放命中缓存,副作用不增加
exec-side   4             A,B,C               B 副作用重复,需要外部幂等键
data        6             A,B,C               事实全部丢失,副作用全部重复

四行输出对应四个场景:

  1. none:A、B、C 各执行一次,副作用 3 次。
  2. control:控制面游标丢失,从头重放计划。因为数据面记录着全部结果,重放全部命中缓存,副作用仍是 3 次。这就是"控制面可重放"的含义:重放决策不重复副作用。
  3. exec-side:B 的副作用已经发生,但结果没有写入数据面。恢复时重放 B、C,B 的副作用执行了第二次——因为这里没有外部幂等键。副作用从 3 变 4。
  4. data:数据面事实全部丢失。恢复时所有动作重新执行,副作用从 3 变 6。

实验刻意把"没有外部幂等键"和"数据面丢失"单独列出来,因为它们正是最容易在生产里被忽略的两种情况。exec-side 场景尤其值得记住:副作用已发生但结果未记录,是这个模型里唯一让重试失效的故障。 它的解法不在本节的实验里,而在执行面的幂等键设计(见 2.2 与 5.2)。

架构判据

三平面分离是否合格,用六条判据检查:

判据合格的样子不合格的样子
职责边界决策、执行、记录各自有明确的入口一个函数里既调用又写日志
副作用位置只有执行面产生副作用控制面代码里直接调用工具
事实记录动作结果先落数据面再确认先返回成功,再异步写日志
决策可重放控制面崩溃后可从头重放决策依赖未记录的执行结果
幂等键执行面对副作用去重重试就重复副作用
数据面可靠事实持久化,可追溯事实在内存里,重启即丢

判据不需要一次全做到。W1 的只读检索可以只要职责边界与事实记录;W3 的不可逆操作至少要有副作用位置、事实记录与幂等键。判据的作用是把"运行时做到什么程度"变成有依据的决定。

小结

  • 控制面决定做什么,没有副作用,故障可重放;执行面产生副作用,故障需要幂等;数据面记录事实,故障不可自动恢复。
  • 三平面分离的本质是让"记录事实"成为一等职责,而不是调用代码里的附带动作。
  • 恢复策略取决于故障落在哪个平面:控制面重放、执行面幂等、数据面对账。
  • 最难处理的故障是"副作用已发生但结果未记录",重试会制造第二次副作用。

阅读导航:上一节:目录与学习路径 · 下一节:1.2 引擎、服务、Worker、存储的职责 。

常见错误与边界

  1. 把三平面当三个进程。 三平面是职责划分,不是部署要求。单进程里也可以职责清晰,微服务里也可以混成一团。
  2. 在执行面之外产生副作用。 控制面里直接调用工具,会让决策不再可重放,这是最隐蔽的架构违规。
  3. 先确认成功,再记录结果。 崩溃会留下"外部已成功、内部不知道"的状态;正确顺序是结果先落数据面再确认。
  4. 把重试当恢复。 重试只能处理"副作用没发生"的故障;副作用已发生未记录时,重试会重复,需要幂等键。
  5. 数据面不是日志。 日志是给人看的,数据面是给控制面和执行面读的;两者都可能丢,但丢了之后的恢复策略完全不同。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图