以下工作负载、预算与数字均为教学假设,不构成对任何真实产品、供应商或生产系统的承诺。三条工作负载的完整定义见本站书稿专题的案例事实表口径。
Agent 的讨论很容易从框架开始:LangGraph 怎么建图、PydanticAI 怎么注入依赖、Claude Agent SDK 怎么配子代理。这些当然有用,但它们回答的是“用什么写”,不是“为什么这样写才成立”。一旦系统出问题,框架知识往往帮不上忙:工具调错了、循环停不下来、同一个退款执行了两次、两个 Agent 互相等待——这些故障的根因分散在完全不同的层,而“换个框架”通常只是把故障换了个位置。
这一节先不写任何框架。它只做一件事:画一张地图,把 Agent 的技术栈拆成四层,把这本书关心的结论分成三条主线,再用三条工作负载给每条结论标上适用范围。后面每一章都会回到这张图:我们讨论的是哪一层、哪条主线、在哪种负载下成立。
为什么先画地图
先看一个真实的归因困难。某个 Agent 在回答里引用了一篇不存在的文档。团队的第一反应是“模型幻觉”,于是换了一个更大的模型;换完之后引用看起来更流畅了,但仍然是假的。第二次归因是“检索没做好”,于是调大了召回数量;召回变多后,模型开始引用不相关的文档。第三次归因是“提示词没写清楚”,于是加了一段“只引用给定文档”的指令;模型确实不再编造文档名,但开始漏答。
同一个症状,至少牵扯四个不同的层:
- 模型层:模型是否具备“只根据给定材料回答”的能力,以及在材料不足时是否愿意说“不知道”。
- 决策层:Agent 是否决定去检索、检索几次、什么时候停止检索。
- 运行时层:检索结果是否被正确拼接进上下文,引用编号是否在压缩后仍然对得上。
- 系统层:检索服务返回的是不是最新文档,权限过滤是否把不该看的文档混了进来。
没有地图时,团队会在四个层之间跳来跳去,每次只修一个点,然后被下一个症状推回来。地图的价值不是分类,而是把“修哪一层”变成一个有依据的决定。
四层技术栈
这本书把 Agent 的技术栈分成四层。分层依据不是代码目录,而是失败时谁负责:每一层都有一个必须回答的问题,以及一份可以被评审的产物。
| 层 | 名称 | 必须回答的问题 | 可评审的产物 | 失败后果 | 典型误修 |
|---|---|---|---|---|---|
| L1 | 模型层 | 模型能做什么、不能做什么 | 能力卡、评测集、选型矩阵 | 承诺了做不到的能力 | 换更大的模型 |
| L2 | 决策层 | Agent 如何根据观测选择动作 | 策略、计划、终止条件 | 目标漂移、死循环、错误动作 | 加提示词 |
| L3 | 运行时层 | 动作如何被执行、恢复与终止 | 状态机、事件日志、沙箱 | 重复副作用、丢状态、无法恢复 | 加重试 |
| L4 | 系统层 | 多个 Agent、工具与租户如何组合 | 协议、网关、配额、治理 | 级联失败、越权、成本失控 | 加监控 |
四层之间有明确的依赖方向:L2 使用 L1 的能力,L3 执行 L2 的决定,L4 组合多个 L3。失败会向上传播,修复要向下找。 模型层承诺不了的能力,决策层再聪明也补不回来;决策层没有终止条件,运行时层再可靠也只是把死循环执行得更稳定;运行时层没有幂等,系统层加多少审批都挡不住重复副作用。
也要避免另一种误解:四层不是组织架构,也不是四个独立服务。一个进程里可以同时包含四层的代码;一个团队也可以同时负责多层。分层的意义是在讨论故障时能指名道姓,而不是画组织图。
三条主线
四层回答“在哪里”,三条主线回答“凭什么说”。这本书不写纯概念介绍,也不写纯操作手册;每一条结论都必须挂在一条主线上,并且能被证据支持。
| 主线 | 核心问题 | 主要落在 | 证据形式 | 反例 |
|---|---|---|---|---|
| 能力线 | 模型到底能做什么 | 卷一 | 能力卡 + 边界清单 + 评测 | 只看榜单,不看任务 |
| 决策线 | Agent 如何选择动作 | 卷二 | 形式化 + 反事实实验 | 只看成功案例,不看失败轨迹 |
| 执行线 | 动作如何可靠执行 | 卷三 | 状态机 + 故障注入 | 只看正常路径,不看崩溃重试 |
能力线的关键是“边界”,不是“峰值”。一个模型在 demo 里能写出一段可运行代码,不代表它能在 40 步的仓库任务里稳定修复 bug;一个模型能通过某张榜单,不代表它在你自己的工具集上会正确选择工具。能力线的证据必须包含失败样本,否则只是宣传材料。
决策线的关键是“可证伪”。说“ReAct 比一次性生成更好”不是结论,除非你能说清楚在什么观测条件下更好、多花多少 token、在哪种任务上更差。决策线的证据通常是一个反事实实验:改变一个变量,看轨迹和结果怎么变。
执行线的关键是“崩溃之后”。正常路径谁都能跑通,真正决定系统能不能上生产的是崩溃、重试、重复投递和取消。执行线的证据必须来自故障注入,而不是“我们加了重试”这种声明。
三条工作负载
同一个结论,在不同负载下可能完全相反。为了不让“某次 demo 有效”被误当成“普遍成立”,这本书用三条工作负载作为对照。它们不是三个客户案例,而是三类约束的代表。
| 编号 | 负载 | 时间跨度 | 可逆性 | 可验证性 | 延迟预算 | 单任务成本 | 失败影响 |
|---|---|---|---|---|---|---|---|
| W1 | 检索问答 | 3–8 步 | 只读,可重试 | 引用可核对 | p95 ≤ 8 s | ≤ $0.02 | 低 |
| W2 | 代码修复 | 10–40 步 | 写分支,可回滚 | 测试可判定 | p95 ≤ 5 min | ≤ $0.50 | 中 |
| W3 | 运维处置 | 2–6 步 | 不可逆,需审批 | 健康检查可判定 | p95 ≤ 60 s | ≤ $0.05 | 高 |
三条负载压的是不同的轴:
- 时间跨度:W1 只有几步,W3 更短但每步更重,W2 可能几十步。长程任务会放大上下文压缩、记忆和终止性的问题。
- 可逆性:W1 只读,错了可以重试;W2 写分支,可以回滚;W3 不可逆,错了要补偿甚至停机。可逆性决定“能不能靠重试兜底”。
- 可验证性:W1 的引用可以逐条核对,W2 的测试是硬判据,W3 的健康检查只能证明“现在活着”,不能证明“做对了”。可验证性决定评测能不能自动化。
- 延迟与成本:W1 要秒级,W2 可以分钟级,W3 要秒级但不能频繁调用。预算决定哪些技术手段根本用不起。
- 失败影响:W1 错了重答,W2 错了回滚,W3 错了可能影响线上。影响等级决定审批、沙箱和人工介入的位置。
一个结论只有在至少一条负载上成立、并且说清楚在其他负载上为什么不成立,才算完整。比如“多听一次观测再行动”在 W1 里通常值得,因为延迟预算允许;在 W3 里可能不值得,因为告警处置窗口只有几十秒。本书不会给出“永远应该多听”的结论,只会给出“在什么预算下值得”的判据。
判据格式
地图要能用,每条原理就必须写成同一种结构。本书使用五个字段:
| 字段 | 含义 | 反例 |
|---|---|---|
| 层 | 这条原理落在 L1–L4 的哪一层 | “Agent 要可靠” |
| 问题 | 它回答哪个可判定的问题 | “Agent 要好用” |
| 判据 | 怎么检查它成立或不成立 | “效果不错” |
| 证据 | 论文、规范、源码或实验 | “大家都这么说” |
| 负载 | 在 W1/W2/W3 中哪条上验证过 | “所有场景都适用” |
这五个字段看起来像表格洁癖,实际是防止两种常见退化:一是把“经验”写成“原理”,二是把“在 W1 上有效”写成“通用有效”。只要有一个字段填不出来,这条结论就不应该进入正文;它可以留在笔记里,但不能冒充原理。
下面的实验把这张地图写成一个可运行的数据结构。它不实现 Agent,只检查“原理条目是否完整”,并统计每层在每条负载上覆盖了多少条判据。空单元格不是错误,但它必须被解释:要么补一条判据,要么在评审记录里写明“这一层在这条负载上不适用”。
# file: agp_lab/stack_map.py | write
# tier: 1
# verify: python3 -m unittest tests.test_stack_map
"""四层技术栈、三条工作负载与判据覆盖矩阵的最小数据模型。"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Iterable
@dataclass(frozen=True)
class Layer:
key: str
name: str
question: str
artifact: str
@dataclass(frozen=True)
class Workload:
key: str
name: str
horizon: str
reversibility: str
verifiability: str
latency_budget: str
cost_budget: str
impact: str
@dataclass(frozen=True)
class Principle:
key: str
layer: str
question: str
criterion: str
evidence: str
workloads: tuple[str, ...] = ()
def validate(self) -> list[str]:
errors: list[str] = []
if self.layer not in {layer.key for layer in LAYERS}:
errors.append(f"{self.key}: 未知层 {self.layer}")
if not self.question.strip():
errors.append(f"{self.key}: 缺问题")
if not self.criterion.strip():
errors.append(f"{self.key}: 缺判据")
if not self.evidence.strip():
errors.append(f"{self.key}: 缺证据")
known = {workload.key for workload in WORKLOADS}
unknown = [key for key in self.workloads if key not in known]
if unknown:
errors.append(f"{self.key}: 未知工作负载 {unknown}")
if not self.workloads:
errors.append(f"{self.key}: 至少绑定一条工作负载")
return errors
LAYERS = (
Layer("L1", "模型层", "模型能做什么、不能做什么", "能力卡与评测集"),
Layer("L2", "决策层", "Agent 如何根据观测选择动作", "策略、计划与终止条件"),
Layer("L3", "运行时层", "动作如何被执行、恢复与终止", "状态机与事件日志"),
Layer("L4", "系统层", "多个 Agent、工具与租户如何组合", "协议、网关与配额"),
)
WORKLOADS = (
Workload("W1", "检索问答", "3–8 步", "只读,可重试", "引用可核对", "p95 ≤ 8 s", "≤ $0.02", "低"),
Workload("W2", "代码修复", "10–40 步", "写分支,可回滚", "测试可判定", "p95 ≤ 5 min", "≤ $0.50", "中"),
Workload("W3", "运维处置", "2–6 步", "不可逆,需审批", "健康检查可判定", "p95 ≤ 60 s", "≤ $0.05", "高"),
)
def validate_map(principles: Iterable[Principle]) -> list[str]:
"""返回全部结构错误;空列表表示这张原理地图可被评审。"""
items = list(principles)
errors: list[str] = []
for principle in items:
errors.extend(principle.validate())
keys = [principle.key for principle in items]
duplicates = sorted({key for key in keys if keys.count(key) > 1})
if duplicates:
errors.append(f"重复 key: {duplicates}")
return errors
def coverage(principles: Iterable[Principle]) -> dict[tuple[str, str], int]:
"""统计每层在每条工作负载上覆盖了多少条判据。"""
grid = {
(layer.key, workload.key): 0
for layer in LAYERS
for workload in WORKLOADS
}
for principle in principles:
for workload_key in principle.workloads:
cell = (principle.layer, workload_key)
if cell in grid:
grid[cell] += 1
return grid
def format_coverage(principles: Iterable[Principle]) -> str:
"""把覆盖矩阵渲染成固定宽度的文本表,便于粘贴进评审文档。"""
grid = coverage(principles)
header = "层\\负载 " + " ".join(workload.key for workload in WORKLOADS)
lines = [header]
for layer in LAYERS:
cells = " ".join(
f"{grid[(layer.key, workload.key)]:>2}"
for workload in WORKLOADS
)
lines.append(f"{layer.key:<6} {cells}")
return "\n".join(lines)
DEMO = (
Principle(
"M-01",
"L1",
"模型在长上下文里还能用中间信息吗",
"给出中间位置召回率与上下文长度的关系",
"Liu et al. 2023, Lost in the Middle",
("W1", "W2"),
),
Principle(
"M-02",
"L2",
"部分可观测下策略为何退化",
"用 POMDP 信念更新解释观测缺失的代价",
"Kaelbling et al. 1998",
("W1", "W2", "W3"),
),
Principle(
"M-03",
"L3",
"崩溃后如何避免重复副作用",
"每个副作用有唯一幂等键,且状态转移可重放",
"本卷 3.2 的崩溃重试实验",
("W2", "W3"),
),
Principle(
"M-04",
"L4",
"多 Agent 的通信成本何时超过收益",
"给出拓扑、消息数与协调开销的判据",
"本卷 9.2 的拓扑实验",
("W2",),
),
)
if __name__ == "__main__":
errors = validate_map(DEMO)
if errors:
raise SystemExit("\n".join(errors))
print(format_coverage(DEMO))
运行:
cd private/labs/agp-lab
python3 -m agp_lab.stack_map
输出:
层\负载 W1 W2 W3
L1 1 1 0
L2 1 1 1
L3 0 1 1
L4 0 1 0
这张覆盖矩阵只包含演示用的四条原理,不是全书的完整清单。它想说明的是读法:L1 在 W1/W2 上各有一条能力判据,在 W3 上没有——这不是说模型层对运维处置不重要,而是说“模型能力”在 W3 里通常不是首要矛盾,首要矛盾是执行语义和审批。L4 在 W1 上没有覆盖,因为单租户、只读的检索问答通常不需要复杂的系统层组合;如果哪天它需要多租户配额,这一格就应该补上。
用这张图定位失败
地图最直接的用途是定位故障。下面三个症状看起来都像“Agent 不稳定”,但根因在不同层,第一检查项和常见误修也不同。
| 症状 | 最可能的层 | 第一检查项 | 常见误修 |
|---|---|---|---|
| 引用了不存在的文档 | L1 或 L2 | 能力卡是否包含“材料不足时拒答”;检索轨迹是否记录了引用来源 | 换更大的模型、加“不要编造”提示 |
| 同一个退款执行了两次 | L3 | 副作用是否有唯一幂等键;状态转移是否原子 | 加重试、加日志 |
| 两个 Agent 互相等待 | L4 | 委派链是否有终止条件;消息是否有超时与死锁检测 | 换更强的模型、加更多 Agent |
这张表不是诊断算法,而是一个起点。它的作用是阻止“所有问题都归因于模型”这个默认反应。只要你能说出症状落在哪一层,下一步就有可检查的对象;否则只能不断换模型、加提示词、加重试,把系统推向更大的复杂度。
本书的阅读路径
三卷的分工对应三条主线:
- 卷一《模型、推理与能力边界》:能力线。解释模型为什么能当策略、工具调用和推理能力从哪来、上下文和采样如何变成架构约束。
- 卷二《决策、记忆与学习》:决策线。解释 Agent 如何在部分可观测下选择动作、如何规划与反思、如何记忆与学习。
- 卷三《运行时、协议与系统架构》:执行线。解释状态机、事件溯源、持久化执行、协议、多 Agent 与安全架构。
不同背景的读者可以走不同路径:模型/算法背景从卷一读到卷三;工程背景从卷三读到卷二;产品与架构背景先读本节和卷三的收口章,再回到卷二的形式模型。B0 阶段只有三篇试点,完整目录会在全书落盘后给出。
小结
- Agent 的技术栈分四层:模型、决策、运行时、系统;每层都有必须回答的问题和可评审的产物。
- 失败会向上传播,修复要向下找;把所有故障归因于模型,是最常见的误诊。
- 三条主线是能力线、决策线、执行线;每条结论必须挂在一条主线上,并有证据。
- 三条工作负载 W1/W2/W3 压的是时间跨度、可逆性、可验证性、延迟成本与失败影响五个轴。
- 原理条目必须写成“层 + 问题 + 判据 + 证据 + 负载”;缺一个字段,就还不能叫原理。
- 覆盖矩阵里的空单元格不是错误,但必须被解释:补判据,或写明不适用。
- 这张地图的用途是定位故障和安排阅读顺序,不是组织架构图,也不是成熟度评分。
下一节会把三条主线展开:能力线、决策线、执行线分别由哪些问题构成,以及它们在三卷中如何交接。
阅读导航:上一节:目录与学习路径 · 下一节:1.2 三条主线:能力线、决策线、执行线 。
常见错误与边界
- 把四层当组织架构。 四层是故障归因的坐标,不是团队分工表;一个团队可以负责多层,一个服务也可以跨层。
- 把模型能力当成系统能力。 模型能生成一段代码,不等于系统能安全地执行、回滚和审计这段代码。
- 用日志代替判据。 “记录了调用成功”不能证明动作做对了;判据必须能回答“在什么条件下成立、失败长什么样”。
- 用一个案例证明通用结论。 在 W1 上有效的上下文策略,可能在 W3 的延迟预算下直接不可用;结论必须标负载。
- 把覆盖矩阵当成熟度评分。 矩阵统计的是“有没有判据”,不是“系统有多成熟”;格子多不代表质量高。
- 在地图层级上过度设计。 不是每个 Agent 都需要四层齐全;W1 的单租户检索问答可能只需要 L1–L3,硬加 L4 只会增加故障面。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。