可观测与协议 on 扎塔-Zata

Agent 决策审计落地：写入点、复核器与门禁降级判据

Thu, 24 Sep 2026 14:15:00 +0800

一份能用的决策审计，第一版可以只有六行 JSONL。还是上一篇里那个改数据库连接配置的例子——Agent 选中了单元测试和真实数据库冒烟，这次把事件流补全：

{"seq":1,"decision_id":"dec-42","event_type":"plan_created","actor":"planner",
 "source_revision":"a1b2c3","detail":{"checks":[
 {"check_id":"unit-tests","disposition":"selected"},
 {"check_id":"real-db-smoke","disposition":"selected"}]}}
{"seq":2,"decision_id":"dec-42","event_type":"check_started","actor":"executor",
 "detail":{"check_id":"unit-tests"}}
{"seq":3,"decision_id":"dec-42","event_type":"check_finished","actor":"executor",
 "detail":{"check_id":"unit-tests","result":"passed","exit_code":0,
 "evidence_ref":"runs/17/logs/pytest-1"}}
{"seq":4,"decision_id":"dec-42","event_type":"check_started","actor":"executor",
 "detail":{"check_id":"real-db-smoke"}}
{"seq":5,"decision_id":"dec-42","event_type":"check_finished","actor":"executor",
 "detail":{"check_id":"real-db-smoke","result":"unavailable","reason":"无预发凭据"}}
{"seq":6,"decision_id":"dec-42","event_type":"verdict_issued","actor":"verifier",
 "detail":{"verdict":"escalate","missing_boundaries":["连接池真实行为"]}}

字段比设计篇的记录少一些——run_id、attempt_id、occurred_at、trace_id 都还在，这里略去不展。第六行就是这套东西的价值：冒烟拿不到凭据时，裁决不是"通过"，是升级。事后任何人拿着 dec-42 都能回答：当时计划跑什么、实际跑到哪、缺了什么、为什么没放行。

设计篇把"该记什么"讲清了：身份模型、计划/执行/裁决分离、history_complete。这篇接着回答落地时真正卡住的三件事——**写入点挂在哪、复核器怎么不变成第二个 Agent、什么条件下才允许它影响放行。**我的判断放在前面：存储本身一晚上就能写完，卡人的从来是这三件。

一、先说不建什么

动手前先划掉三个"看起来该做"的东西。审计的第一死因不是记得不准，是被绕过——系统一重，团队总有办法绕过它。

做重了的信号	v1 的做法
起一个独立的审计服务	一张追加式表，执行进程内直接写
把原文（prompt、源码、终端输出）存进审计	只存引用与摘要，原文走受控存储
上线即接管放行、替换现有门禁	先与固定门禁并行，只记录分歧

第三条是全文最重要的边界。设计篇说决策审计让"自选验证深度"的自由度可复核，但可复核不等于可放行——从"并行记录"走到"参与放行"，中间隔着第五节那套判据，判据没满足之前，记录再完整也不构成授权。

二、最小数据契约：一张只允许 INSERT 的表

DDL 以 SQLite 3 为准，换 PostgreSQL 只需要改触发器写法：

CREATE TABLE decision_events (
 seq INTEGER PRIMARY KEY AUTOINCREMENT,
 event_id TEXT NOT NULL UNIQUE, -- 幂等键，由业务身份拼出
 decision_id TEXT NOT NULL,
 run_id TEXT NOT NULL,
 attempt_id TEXT,
 event_type TEXT NOT NULL CHECK (event_type IN
 ('plan_created','check_started','check_finished',
 'verdict_issued','decision_invalidated')),
 actor TEXT NOT NULL,
 source_revision TEXT NOT NULL,
 policy_version TEXT NOT NULL,
 trace_id TEXT,
 occurred_at TEXT NOT NULL,
 detail TEXT NOT NULL -- JSON，自带 detail_schema_version
);
CREATE INDEX idx_events_decision ON decision_events(decision_id);

CREATE TRIGGER no_update BEFORE UPDATE ON decision_events
BEGIN SELECT RAISE(ABORT, 'append-only'); END;
CREATE TRIGGER no_delete BEFORE DELETE ON decision_events
BEGIN SELECT RAISE(ABORT, 'append-only'); END;

追加式不是审美偏好，它换来两个便宜：没有 UPDATE，历史就不可改；完整性验证退化为检查"存在且有序"（第六节展开）。触发器挡的是自己人手滑，真正的防线在读取端。

五个事件类型各自的写入责任：

event_type	谁写	必填 detail	记录的事实
plan_created	planner	checks（每项含 disposition 与 reason）	决策的存在起点
check_started	executor	check_id	某项检查开始执行
check_finished	executor	check_id、result、evidence_ref	执行器观察到的结果
verdict_issued	verifier / 放行器	verdict、依据摘要	对计划与证据的裁决
decision_invalidated	平台	失效原因、新 revision	旧裁决作废

两个容易写错的字段。occurred_at 用写入方本地时钟就行，排序靠 seq，时钟只负责展示——分布式环境里别指望时钟可排序。detail 里必须带 detail_schema_version：追加式意味着旧记录永远不会迁移，演进只能靠新版本号，读取端按版本解释。

事件不是随便堆的，读取端会按一个状态机校验它们：

▲ 图：自绘

三、写入点：审计不改变控制流，只挂在三个钩子上

决策审计在 Runtime 里没有自己的环节。它不参与循环，不加延迟，只挂在三个既有节点的出口上：

▲ 图：自绘

写入点	挂在哪	actor	写什么	不写什么
计划成立时	planner 的结构化输出通过 schema 校验之后	planner	plan_created	模型原始 token 流
检查起止时	执行器进程内，每项检查的前后	executor	check_started / check_finished	Agent 对结果的转述
裁决签发时	verifier 出结论、放行器动动作	verifier	verdict_issued	覆盖 planner 的记录

三个坑都在挂的位置上。

**计划写入要在 schema 校验之后。**校验之前写，Agent 输出里每段格式垃圾都进审计表。审计表被噪声淹没后没人再信它——这比没有审计更糟。

**check_finished 只能由执行器写。**这是设计篇"Agent 承诺和执行器事实分开"的实现面：Agent 在上下文里说"测试通过了"不算数，执行器进程里那行代码写下的才算。执行器与 Agent 同进程时，至少保证写入点在执行函数内部，而不是在 Agent 转述的文本后面。

**审计写不进去时，决策还能不能继续？**按阶段分两说。v1 的并行阶段，写入失败只把该 attempt 计为"审计缺失"，让缺失率本身成为统计指标；到了将来接管的阶段，写不进审计的 attempt 一律不允许自动放行。哪种都可以，唯独不能静默吞掉失败。

写入器是全文最简单的代码，唯一值得注意的是幂等键——由业务身份拼出来，重试同一个动作不会写进两条：

def append_event(conn, decision_id, run_id, event_type, actor,
 source_revision, policy_version, detail,
 attempt_id=None, trace_id=None, key_suffix=""):
 event_id = f"{decision_id}:{event_type}:{key_suffix}" # 确定性幂等键
 conn.execute(
 "INSERT OR IGNORE INTO decision_events "
 "(event_id, decision_id, run_id, attempt_id, event_type, actor,"
 " source_revision, policy_version, trace_id, occurred_at, detail)"
 " VALUES (?,?,?,?,?,?,?,?,?,?,?)",
 (event_id, decision_id, run_id, attempt_id, event_type, actor,
 source_revision, policy_version, trace_id,
 datetime.now(timezone.utc).isoformat(),
 json.dumps(detail, ensure_ascii=False)),
 )
 conn.commit()

幂等键的取法和全景手册对工具调用的要求同源：按业务身份（decision_id + event_type + key_suffix）去重，不按请求 ID。检查类事件里 key_suffix 就是 check_id，同一项检查反复重试，check_started 只落一条。

四、复核器：规则在前，模型在后

复核器最大的落地风险，是写成"再跑一个 Agent 看一遍"——那就成了第二个 planner，共享同样的盲点，还多付一遍模型钱。把复核拆成两层，规则层不花钱，不过就升级：

def verify_decision(events, pending_revision):
 plan = first_of(events, "plan_created") # 缺它，整份记录无效
 checks = {e["detail"]["check_id"]: e["detail"]
 for e in events if e["event_type"] == "check_finished"}

 missing = [c["check_id"] for c in plan["detail"]["checks"] # 规则一
 if c["disposition"] == "selected" and c["check_id"] not in checks]
 not_passed = [cid for cid, d in checks.items() # 规则二
 if d["result"] != "passed"]
 stale = plan["source_revision"] != pending_revision # 规则三
 unexplained = [c["check_id"] for c in plan["detail"]["checks"] # 规则四
 if c["disposition"] == "skipped" and not c.get("reason")]

 if missing or not_passed or stale or unexplained:
 return escalate(missing, not_passed, stale, unexplained)
 return model_coverage_review(plan, events) # 规则全过，才问模型覆盖面

四条规则各自挡一种"结果是绿的、判断仍然错"：规则一挡"计划写了但没跑完"；规则二挡 unavailable、failed 被当通过——开场例子里冒烟拿不到凭据，裁决只能 escalate，就是这条在起作用；规则三挡"检查的是 A、要合并的是 B"；规则四挡跳过不留理由。规则四其实应该在 plan_created 写入时就被 schema 拦下，复核器再查一遍，是因为写入端校验会随时间漂移，读取端要有独立的防线。

规则层全过，才进第二层。模型复核只回答规则回答不了的问题：计划对风险事实的覆盖面。“改了连接池配置，计划里却没有真实数据库冒烟"这类漏边界，规则查不出来，模型或人可以。第二层的产出同样是一条 verdict_issued，actor=verifier，引用同一个 decision_id，不覆盖任何旧记录。verdict 只需要两个值：支持放行、升级人工——“拦截"不是它的职责，规则层已经拦了。

防共享盲点的最低成本做法：verifier 的提示词版本、甚至模型路由，都和 planner 不同，且两者的 policy_version 都写进了记录。事后能看出"同一个模型自己复核自己"这种结构缺陷。

五、降级判据比记录格式更重要

并行阶段的目标不是"验证审计好用”，是把固定门禁和决策审计放在同一批任务上，量化它们在哪儿不一致。每个 attempt 两边各有结论，落在四个象限：

	固定门禁拦下	固定门禁放行
决策审计放行	漏报候选——最危险的象限，逐条人工复检	一致放行，正常交付，抽样复核
决策审计拦截	一致拦截，抽查确认拦截理由	误报候选——计入审计的误拦成本

分歧统计一条 SQL 就够：gate_outcomes 记固定门禁结果，audit_outcomes 从 verdict_issued 聚合出 passed（verdict 为"支持放行”）：

SELECT g.gate_name,
 COUNT(*) AS attempts,
 SUM(g.blocked AND a.passed) AS audit_missed,
 SUM(NOT g.blocked AND NOT a.passed) AS audit_false_block
FROM gate_outcomes g
JOIN audit_outcomes a USING (attempt_id)
GROUP BY g.gate_name;

（SQLite 3 的布尔求和写法；PostgreSQL 换成 COUNT(*) FILTER (WHERE …)。）

什么时候允许决策审计接管某个固定门禁？三个条件必须同时满足，并且要写进试点协议、带上样本量下限：

漏报候选归零。人工逐条复检这个象限，没有一条真实漏网。样本量下限按该门禁的历史拦截率反推——拦得越少的门禁，需要越长的并行期。
误报候选率不高于固定门禁自己的误拦率。否则不是升级，只是把可见的脚本误报换成不易发现的判断误报。
分歧可归因。每条分歧都能落到具体原因：策略版本差、检查覆盖差、环境不可用。归因不出的分歧占比高，说明记录本身还不可复核——先修记录，别谈接管。

三个条件连续 N 轮（N 写进协议）同时满足，才把这一项门禁从阻断降为提示，逐项降、不打包。迁移链完整性这种失误代价极高的规则，可能永远不该降。

并行期里 decision_invalidated 同样要写：待合并分支更新导致 source_revision 变化、policy_version 升级，都追加一条失效事件。放行器只认"verdict 绑定的 revision 等于当前待放行的 revision"。

判据比记录格式重要，这句话值得单独一段：没有判据的并行记录，只是一份更贵的日志。

六、审计存储自身会坏：读取端怎么认账

设计篇提过 history_complete，落到读取端是一个便宜的校验函数：拿一个 decision_id 的事件序列，检查它以 plan_created 开头、以 verdict_issued 结尾、每个 check_started 都有配对的 check_finished：

def history_complete(events): # events 已按 seq 排序、按 decision_id 过滤
 types = [e["event_type"] for e in events]
 if not types or types[0] != "plan_created":
 return False
 if "verdict_issued" not in types or "decision_invalidated" in types:
 return False
 started = {e["detail"]["check_id"] for e in events
 if e["event_type"] == "check_started"}
 finished = {e["detail"]["check_id"] for e in events
 if e["event_type"] == "check_finished"}
 return started <= finished

注意校验按 decision_id 分组做，不按全局 seq——并发之下全局 seq 本来就有空洞，完整性是每个决策自己的性质。

校验不过，这个 decision 的证据就当不存在：放行器走"无审计"路径（人工或固定门禁），并把"无审计放行"本身记下来。沉默缺失被误读成通过，是审计存储最坏的失败方式，宁可显式降级。

单机 SQLite 的丢失风险要诚实写进 v1 的边界：它没解决多副本，靠的是这张表很小（一次决策几 KB）、全量备份便宜、备份脚本可以拿校验函数自检。真正占空间的是 evidence 原文，那是另一套保留策略——审计表只存 evidence_ref 和摘要，本来就不该跟着膨胀。

七、我的判断

v1 的合理成本上限是一两周。做的过程中一旦发现要起独立服务、要改现有 CI 的控制流，说明做重了，回第一节的表对照。
决策审计改变的不是风险本身，是漏报的可发现性：没有它，“Agent 跳过了该跑的检查"只能在事故后追查；有了并行期，漏报候选在统计表里按周可见。
反过来，如果 Agent 只提建议、放行始终由人或固定规则拍板，trace 加审批日志就够了。这套东西的成本，只在放行权真的开始转移时回本。

速查：落地顺序与每步的完成判据

步骤	交付物	完成判据
1. 建表	DDL + 追加式触发器	UPDATE / DELETE 被 ABORT
2. 写入点	三个钩子 + 幂等写入器	同一事件重试只落一条
3. 读取校验	按 decision_id 的完整性函数	缺头、缺尾、缺配对的序列被判无效
4. 规则复核器	四条确定性规则	任一不过即 escalate，不进模型层
5. 并行运行	分歧四象限统计	每个门禁的漏报/误报候选都有数
6. 判据与降级	写进试点协议的三个条件	逐项降级，永不打包

一句话收尾：先让它记录分歧，再让它参与放行——降级判据写清楚之前，决策审计只是一份更贵的日志。

Session、Thread、Run：一条消息为什么是一个 Run

Wed, 23 Sep 2026 23:11:14 +0800

把 Run 表定义摊开看，有个细节很别扭：

class AgentRunModel(Base):
 id: Mapped[str] # Run ID
 thread_id: Mapped[str] # 外键 -> conversation_thread，NOT NULL
 session_id: Mapped[str | None] # 外键 -> chat_session，允许为空
 agent_id: Mapped[str]
 status: Mapped[str]
 ...

一张表上挂了两个"会话类"外键，一个必填、一个可空。第一眼看上去像是设计没收敛——要么统一用 session，要么统一用 thread，为什么两个都要？

真正解释这件事的，是那个允许为空的字段。它存在的理由，不是一个空值占位，而是"一次执行可以不隶属于任何对话"。等子 Agent 出现时，这个空位会立刻被填满意义。

一、三个名字，三种事实

这三层不是同义词，也不是新旧替代关系，它们各自是一类问题的权威答案：

层	表	谁看得见	回答的问题	生命周期
Session	`chat_session`	用户	这是哪一段对话	长期，可继续
Thread	`conversation_thread`	只有后端	模型的连续记忆装在哪	与对话同寿
Run	`agent_run`	用户（状态/取消）、管理员（审计）	这是哪一次执行、用了什么、跑到哪	单次，有终态

Session 用户可见的一段对话：标题、owner、历史消息
 └─ Thread 模型的连续记忆（checkpointer 线程），前端不维护
 └─ Run 一次执行：快照 / 状态机 / 事件流 / 取消 / 计费

几处容易混的地方，一次说清：

Session 是产品概念。它管标题、归属、消息顺序；删掉一个 Session 意味着用户不再看到那段对话。
Thread 是实现细节。Session 到 Thread 的映射在后端完成，客户端不需要传也不需要存 thread_id。它存在的唯一理由是：模型需要一个连续的上下文容器。
Run 是事实源。它不属于"对话"这个层级，而属于"执行"这个层级：一次输入落进去，出来的是带序号的事件流和一个终态。

所以那条别扭的表定义翻译过来是：每次执行必须属于一个记忆线程，但不一定属于一段用户对话。

这里要跟另一套常见用法区分开：在审计与可观测性的语境里，run_id 有时指"跨暂停、重试仍稳定的业务任务身份"，再用 attempt_id、trace_id 区分每一次尝试（可参考本系列的《Agent 决策审计：它与 Tracing 的关系》）。本文说的 Run 是执行层的单位：单次、有终态、不可重开——想重跑，就是一次新的 Run。两套用法服务的问题不同，混用会在"重试算不算同一次"上直接打架。

二、一条消息，就是一个 Run

用户视角里，一次交互是"在对话里发了一句话"。到 API 这一层，它变成一次 Run 创建：

POST /sessions/{session_id}/messages
→ 202 { "message_id": "...", "run_id": "run_xxx", "events_url": "/api/agent-runs/run_xxx/events",
 "agent_id": "...", "agent_name": "..." }

返回体里同时出现 session_id（在 URL 上）和 run_id（在响应里），这不是冗余，而是两个层级各自交回自己的凭据：前者继续指向那段对话，后者指向刚刚开始的这次执行——订阅事件、取消、查状态，用的全是它。

历史消息也保留了这层关系：assistant 消息上挂一个唯一的 run_id 回指生成它的那次执行。这样当用户在同一个对话里换了 Agent，回看历史时依然能说出"这条回答当时是哪个 Agent 给的"，而不是拿当前绑定去反推过去。

而 Session 上的 agent_id 只是初始默认值：同一段对话的后续每条消息都可以逐次切换 Agent，切换只影响下一次发送。这一点是后面所有讨论的前提——如果 Session 就等于 Run，这条规则根本无法表达。

三、为什么不能"一个 Session 一个 Run ID"

合并成一层听起来更简洁，但会立刻遇到四个对不上的地方：

1. 快照必须逐次冻结。 每个 Run 在创建事务里固化两份不可变快照：Agent 执行快照和资料上下文快照。它们记录的是"这一次用的版本"，而不是"这段对话现在用什么"。会话级 ID 没有位置安放"逐次"这个语义。

2. 终态是执行的属性，不是对话的。 Run 的状态机有唯一终态且不可重开：succeeded、failed、cancelled、interrupted。一次执行失败，不应该把整段还能继续聊的对话标记为失败。

3. 幂等键挂在 Run 上。 创建 Run 必须带 Idempotency-Key，唯一约束是 (owner_id, idempotency_key_hash)。同一用户、同一个 key、同一份请求会重放原来那次 Run；同样的 key 配不同请求则稳定返回 idempotency_conflict。重放的单位是"那一次执行"，不是"那段对话"。

4. 取消、租约、事件游标都是 per-Run 的。 GET /api/agent-runs/{run_id}/events?after_seq=N 的游标是 Run 内的序号；执行租约（lease）也写在 Run 上。刷新续流用 Last-Event-ID 接上原来那条流——如果一段对话只有一条流，换 Agent、重试、取消全都会糊在同一根管道里。

换个角度看得更清楚。挂在 Run 上的这些字段，每一条都在说"这是单次执行的属性"：

事实	字段
用哪个 Agent、什么版本	`agent_id`、`agent_execution_snapshot`
看的哪些资料	`context_pack_snapshot`
跑到哪一步	`status`、`last_event_seq`
谁在跑	`executor_instance_id`、`lease_expires_at`
能不能重放	`idempotency_key_hash`、`request_checksum`
结果与失败	`final_message_id`、`error`
时间线	`created_at` / `started_at` / `finished_at`

四、Run 的状态机：把"事实"和"活性"分开

既然执行是单位，状态就必须说准。非终态有三个，终态有四个：

queued ─→ running ─→ succeeded
 │ │ └→ failed
 │ ├─────→ cancelled
 └─────────┴─────→ interrupted
 cancelling 是 running 到 cancelled 之间的过渡态

三条容易踩的语义：

租约不是历史事实。 lease_expires_at 只表示"执行者还活着"，它过期不代表这次执行失败了。失联的 Run 由 reconciliation 追加 run.interrupted 收口——而且不会自动重跑模型。想重跑，是人的决定，是一次新的 Run。
取消只追加一次终态。 用户取消先写 run.cancelling，运行中的执行器收到信号后回收当前图或模型流，恰好追加一次 run.cancelled（带 external_stop_confirmed: true）。确认取消之后，不会再出现 run.completed 或 run.failed。
终态不可重开。 一个 Run 进入终态，它的故事就结束了。任何"再来一次"都是新 Run、新快照、新的幂等键。

这套规则的价值不在单 Agent 场景——那里一条流从头读到尾就够了。它的价值在于：当你需要并行、需要重试、需要给一部分工作单独踩刹车时，你必须有一个不可重开的最小单位。

五、委派那天，这个空字段被填满了

现在回到开头那个可空的 session_id。

子 Agent 委派落地后，父 Run 在执行过程中会请求平台创建 child Run。child 是另一次真实执行：目标 Agent 不同、快照不同、独立线程、独立事件流、独立状态与独立取消入口。它满足"执行"的全部定义，但不隶属于用户的那段对话——用户没有在对话里发过那句话。

所以 child 的 session_id 就是 NULL：

root Run session_id = sess_xxx 用户可见，出现在会话历史
├─ child A session_id = NULL 内部执行，只有树里能看到
└─ child B session_id = NULL

父子关系不表达在 Session 上，而是靠 Run 表自己的两个自引用字段：root_run_id 指向所属的根执行，parent_run_id 指向直接父节点。运行树因此可以从持久化记录里重建：刷新页面后树还在，服务重启后未完成节点统一收敛为 interrupted。

对前端而言，这个分层直接决定了工作量：原来"发一次消息 = 拿到一个 run_id = 连一条 events_url“的假设，要变成"先读树，再按每个节点的 events_url 各自订阅”。一条流变多条流，正是因为一次对话里现在真的有了多次执行。

反过来验证一下：如果当初把 Run 合并进 Session，委派就得在 Session 上开洞——一段对话要同时容纳多个 Agent、多份快照、多个终态、多个取消目标。这个洞会一直开到把 Session 拆回去为止。

几点收获

ID 的层级应该跟生命周期对齐，而不是跟界面层级对齐。 用户看到的是对话，系统需要的是执行；把两者合成一个 ID，短期少一个字段，长期处处要打补丁。
允许为空的外键往往在讲一个未来的故事。 session_id 可空不是随手留的，它提前承认了"执行可以不属于任何对话"这类存在。
状态机要区分事实与活性。 心跳、租约、连接状态说明的是"谁还在跑"；状态、事件流说明的是"发生了什么"。把两者混在一起，就会出现"进程没了所以这次执行失败了"这种错误结论。
幂等、取消、游标、计费都需要一个不可重开的最小单位。 它们四个的需求指向同一个答案：Run。先把这层定清楚，后面加并行、加委派、加预算，都是在这个单位上做加法。

回到最开始那张表：两个外键不是没收敛的设计，而是两层身份各自在场的证据。一个必填，因为执行总需要记忆；一个可空，因为执行不一定需要观众。

Agent 决策审计：它与 Tracing 的关系

Tue, 22 Sep 2026 11:30:00 +0800

假设一个代码 Agent 改了数据库连接配置。它跑过单元测试，然后决定跳过真实数据库验证，给出“可以合并”的结论。几天后线上出现连接池故障。此时仅看到一条 tool.pytest succeeded 的 trace，并不能回答关键问题：它当时看到了哪些改动，为什么认为真实数据库验证可以跳过？

这正是决策审计（decision audit）要解决的问题。它与 Agent tracing 可以出现在同一条运行时间线上，但两者回答的问题不同：tracing 还原执行过程；决策审计保存判断依据与责任边界。 当 Agent 的判断会影响放行、权限或资源使用时，后者就不能只是几行自由文本日志。

一、先把四种记录分清

记录	核心问题	典型内容	常见用途
Trace	经过了哪些步骤，耗时和错误在哪里？	Agent、模型、工具、命令的 span 与父子关系	排障、性能分析
Log	某一刻发生了什么？	命令退出码、异常、状态变化的文本或结构化事件	定位具体故障
Decision record	基于哪些输入作了什么判断？	风险、候选项、选择/跳过及理由、决策版本	复核判断
Evidence	判断是否得到事实支持？	命令结果、测试报告、截图、审查报告及其摘要	验收与复验

一份 trace 完全可以包含 validation.plan、validation.execute 之类的 span，也可以链接决策记录。但把 span 存下来，不等于完成审计：span 常为排障服务，可能被采样、截断或按较短期限清理；审计记录则要明确必填字段、留存策略、版本关联与完整性状态。反过来，只有决策表而没有 trace，也很难诊断工具超时、重试和上下文断裂。

这里的“审计”不是声称记录模型的全部内心推理。我们能记录和复核的是可观察的输入、显式给出的理由、执行器实际取得的结果，以及最终授权动作。自由文本解释可以帮助人理解，但不能替代结果和证据。

二、决策审计是 tracing 的一部分吗？

从用户界面看，可以是一部分：点开一次 Agent run，沿着时间线看到“分析改动 → 制订验证计划 → 执行 → verifier 复核 → 放行”。从数据责任看，最好是独立记录，再通过标识关联。它们可以共用一次任务的 run_id，而 trace_id 指向这一轮执行的诊断轨迹。

需要特别区分 run_id 与 trace_id。一次长期任务可能暂停、恢复或重试，仍属于同一个业务 run，却产生多个 trace；一次 trace 也可能只覆盖其中一段执行。因此审计主键应围绕业务对象与代码版本设计，不能把“当前 trace 恰好存在”当作放行条件。

PRD / Issue / change
 └─ run_id：业务任务身份
 ├─ decision_id：一次验证计划或放行判断
 ├─ attempt_id：一次执行尝试
 └─ trace_id：该次尝试的诊断轨迹

一种实用做法是：审计记录保留最小且稳定的事实，trace 保留丰富的执行细节。审计记录可以引用 trace；trace 丢失或过期后，仍能知道当时基于哪个代码版本、采用了哪些检查、结果如何。若审计存储本身也可能故障，必须显式标记 history_complete=false，不能默默显示“通过”。

三、一条可复核的决策记录长什么样

以“Agent 自主选择验证项”为例，至少要分开记录计划、执行与裁决。这是本文最重要的边界：Agent 写下“我将运行测试”，不代表测试真的运行过。

{
 "schema_version": 1,
 "decision_id": "dec-42",
 "run_id": "run-17",
 "attempt_id": "attempt-2",
 "source_revision": "git-tree-sha-or-worktree-fingerprint",
 "policy_version": "validation-policy-v3",
 "actor": "validation-planner",
 "risk_facts": ["changed: database pool configuration"],
 "checks": [
 {
 "check_id": "unit-tests",
 "disposition": "selected",
 "reason": "配置解析路径已变更"
 },
 {
 "check_id": "real-db-smoke",
 "disposition": "selected",
 "reason": "连接池行为依赖真实数据库"
 }
 ],
 "created_at": "2026-09-22T03:30:00Z"
}

这条记录只是计划。执行器随后追加每项检查的 started、passed、failed、timed_out 或 unavailable 结果，并附命令摘要、退出码、环境说明、产物引用和摘要值。verifier 再引用同一个 decision_id，说明它是否认可计划覆盖面和实际证据。最终放行记录引用 verifier 结论及代码版本，避免“检查的是 A，合并的是 B”。

字段	为什么需要
`source_revision`	防止旧证据给新代码放行；未提交改动也需要工作区指纹
`policy_version`	以后规则变化时，还能解释当时采用哪套标准
`disposition` 与 `reason`	把跳过项显式化，便于统计误判与复核
`result` 与 `evidence_ref`	区分 Agent 承诺和执行器观察到的事实
`actor`	区分 planner、执行器、verifier 和人工签核
`history_complete`	告诉读者记录缺失，避免把沉默误读为成功

原始 prompt、源码、密钥和完整终端输出不应默认写进长期审计表。可以将原始产物放入受控存储，审计表只保留路径、摘要、脱敏摘要和访问范围。**哈希能证明后来查看的是同一份产物，但不能证明产物当初真实或结论正确。**真实性仍需靠可信执行器、环境记录和必要时的复跑。

四、它怎样帮助替代固定门禁

固定门禁适合确定、便宜、误报低且失误代价高的规则，比如迁移链完整性或禁止提交密钥。Agent 适合根据改动上下文决定验证深度，例如是否需要浏览器真实入口、真实数据库或特定回归场景。决策审计让后者的自由度能够被复核。

可落地的执行顺序是：

识别风险：从 diff、任务要求、依赖边界和历史故障提取具体事实，而不是只给“高/中/低”标签。
列出候选检查：同时记录选择与跳过；跳过需说明前提，例如“仅改文案，没有可执行行为变化”。
执行并留证：由执行器记录实际命令、环境、退出状态和产物；失败、超时、无凭据分别处理。
独立复核：verifier 检查计划是否漏掉关键边界，以及证据是否对应当前版本。它的意见也应作为一条新记录，而不是覆盖原计划。
形成最终裁决：只有与当前代码版本匹配、记录完整且满足必要硬约束的结果，才能支持自动放行；其余情况升级给人。

这不是要求每次都运行最昂贵的验证。它要求验证深度的取舍有可见依据。例如前端仅调整按钮文案，可以跳过端到端流程，但要说明未改交互或请求结果；修改 Dialog、Portal 或跨页流程时，单独的组件截图就不足以证明真实入口可用。

一个常见失败：结果是绿的，判断仍然错

症状	原因	修复
单元测试通过，线上连接池仍故障	计划漏了真实数据库边界	verifier 审查“覆盖了哪些风险”，而不只看退出码
证据文件存在，实际测试没跑完	Agent 把计划或旧文件当结果	执行器写入退出码、时间与产物摘要；绑定代码版本
verifier 判绿，但新提交改变了代码	裁决没有绑定修订版本	代码版本变化时使旧裁决失效并重新评估

五、从最小实现开始，不必先建平台

已有 runner、日志文件和生命周期账本的项目，可以先增加一张追加式 decision_events 表或等价的 JSONL 存储：decision_id、run_id、attempt_id、event_type、actor、source_revision、occurred_at、detail。事件类型先控制在 plan_created、check_started、check_finished、verdict_issued、decision_invalidated。原始输出继续落文件，通过 evidence_ref 关联。

第一阶段让 Agent 决策与现有门禁并行运行，只记录分歧，不自动改变放行。挑选常误拦、执行成本高的门禁，统计它拦住过哪些真实问题、Agent 漏掉了哪些检查、verifier 能否识别。只有在这些反例上表现稳定，才逐项把固定门禁降为提示。否则只是把可见的脚本误报，换成不易发现的判断漏报。

这个方案也有边界。独立 verifier 可能与 planner 共享同一种盲点；本机 SQLite 可能丢失；外部服务验证可能受凭据和环境限制。审计不能神奇地消除这些风险，它的价值是把依据、缺口与责任留在可复核的位置，让后续改进有真实样本。

速查：遇到一个问题该看哪里

你要问的问题	先看
为什么这次 run 很慢？	Trace 的 span 树与耗时
命令究竟报了什么错？	关联 `trace_id` 的日志及原始产物
为什么跳过真实入口验证？	决策记录中的候选项、理由和政策版本
跳过是否合理？	风险事实、任务要求、verifier 结论
测试通过是否能支持当前合并？	执行结果、证据引用、代码版本与最终裁决

我的判断是：决策审计可以嵌进 Agent tracing 的浏览体验，但应有独立的数据契约和留存责任。 当 Agent 只是辅助写代码，trace 通常足以排障；当 Agent 开始决定“哪些门禁可以不跑、这次是否放行”，决策记录就成为运行时的必要组成部分。

继续阅读：Agent 决策审计落地：写入点、复核器与门禁降级判据——本文的落地实现篇；Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点；Agent Runtime 详解。

Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点

Tue, 22 Sep 2026 09:51:00 +0800

用户说：这个 Agent 回答一个问题要 40 秒。

我去 grep 日志，符合条件的只有一行：

2026-09-20 14:02:11 INFO run finished run_id=run-7f3a elapsed=41.3s

41.3 秒，和用户说的对得上。然后呢？没有然后了——日志告诉你"慢"，但告诉不了"慢在哪一步"。

于是我加 print：在每轮 LLM 调用前后打一行，在每次工具调用前后打一行。半小时后日志变成这样：

14:01:30 LLM #1 start
14:01:37 LLM #1 done
14:01:37 tool web_search start
14:02:01 tool web_search done
14:02:01 LLM #2 start
14:02:16 LLM #2 done

能看了，但问题也很明显：这些行彼此之间没有关系。换个用户并发进来，两组行就交织成一片；想知道"哪一步占了这 41 秒"，还得靠人肉减时间戳。更别说线上没有 print，只有一条 run finished。

这篇文章要解决的，就是把这个"人肉减时间戳"的过程，换成一套有结构、能自动关联的数据。这正是 Tracing 干的事。

一、Trace 与 Span：一次 Agent Run 就是一棵树

先建立两个最基础的概念，用上面那个 run 当例子。

Trace（链路）：一次完整请求的全过程，有一个全局唯一的 trace_id。上面这次调用对应一条 trace。

Span（跨度）：trace 里的一段工作，有名字、有开始时间、有结束时间，可以有属性和事件。上面每一行 print，本质上都是一个 span。

Span 之间靠 父子关系 组织成树。上面那次 run 画成 span 树是这样的：

agent.run run.id=run-7f3a session.id=s-12 [t=0.0 → 41.3s]
├─ gen_ai.chat 第 1 轮 gen_ai.request.model=某模型 [t=0.2 → 6.8s]
├─ tool.web_search tool.name=web_search [t=7.0 → 24.1s] ← 元凶
├─ gen_ai.chat 第 2 轮 gen_ai.usage.input_tokens=4821 [t=24.3 → 39.6s]
└─ agent.finalize [t=39.7 → 41.2s]

树的形状一出来，答案就自己浮上来了：24.1 秒花在 web_search 上，占掉一半以上。不需要减时间戳，不需要猜。

这里有三点值得单独说清楚，因为后面所有的坑都出在这三件事上。

第一，父子关系是"包含"关系，不是"先后"关系。 子 span 的时间区间落在父 span 区间内。父 span 的耗时不是子 span 的加总——agent.run 是 41.3 秒，四个子项加起来也差不多，但如果两个子 span 时间重叠，说明它们在并行，加总就会超过父 span。时间重叠 = 并发，这是 span 树比日志强的最直观的一点。

第二，根 span 只有一个。 一次 run 对应一个 agent.run span（root span），其余都是它的后代。trace_id 相同、parent_span_id 串起来，就构成了这次 run 的完整路径。排查时从 root 往下看，就是一条推理链。

第三，span 可以跨进程。 一次 Agent Run 里，tool.web_search 很可能不是本地函数，而是打到一个远程服务甚至别人的 MCP Server 上。只要上下文传得过去（第五节讲），那边产生的 span 会挂到你这棵树上，变成你 trace 的一部分。

二、属性与事件：span 上该记什么

有了 tree 骨架，还得有内容。span 上能挂两类东西：属性（Attributes） 和 事件（Events）。这两个词经常被混用，但分工很清楚。

	属性 Attributes	事件 Events
形态	键值对，附着在 span 上	带时间戳的独立记录
回答的问题	这个 span 是什么	这个 span 过程中发生了什么
典型时机	span 存续期间的任何时刻	某个确定的时间点
主要用途	筛选、分组、聚合	还原时间线、记录离散动作
Agent 里的例子	`gen_ai.request.model`、`gen_ai.usage.output_tokens`、`tool.name`	重试一次、首个 token 到达、工具返回、抛异常

一个够用的判断口诀：能被拿来当筛选条件的，放属性；只在某一刻发生、要看"什么时候"的，放事件。

“所有用了 A 模型的 run 平均耗时多少” → 模型名必须是属性（要聚合)。
“这次 run 重试了 3 次，每次间隔多久” → 重试是事件（要看时刻）。

在 Agent 语境里，属性这块已经有一份现成的答案：OpenTelemetry 的 GenAI 语义约定（gen_ai.*）。模型名、token 用量、工具名、会话 id 该叫什么，规范里都钉死了，照着填就能被各种观测后端正确解析。这份约定的字段清单和几个已知的坑，我在 Agent 埋点接 ARMS 里已经逐条整理过，这里只补一条最容易踩的边界：

属性会被当成聚合维度，所以基数要有意识。 run.id、session.id 这种每次都不一样的值，挂在 span 上当属性没问题（trace 是按 trace_id 检索的，不存在"按属性建索引"的压力）；但如果这些属性被顺手套进了 Metrics 的维度里，一张指标卡片就会被炸成几万条时间线。分界线不是"能不能当属性"，而是"这个字段会不会流进指标聚合"。同样地，gen_ai.input.messages 这类可能含用户隐私的字段，规范明确标成了 Opt-In，不该默认记录。

事件这块有一件新变化，值得单独提醒。 OTel 在 2026 年 3 月宣布弃用 Span Event API（也就是 Span.AddEvent / Span.RecordException），原因是"span 事件"和"日志事件"两套并行的机制造成了重复和困惑。新的事件应该走 Logs API，通过上下文与当前 span 关联。需要注意边界：

这是弃用 API，不是删除能力。add_event() 现在还能用，存量数据和在 trace 视图里看事件也照常工作。
建议是：新写的埋点别再加对 add_event() 的新依赖；自己封装的异常上报，优先走日志库 + OTel 日志桥接，它会自动带上 trace_id / span_id。

如果你现在就在写埋点，实操上可以这么记：属性照旧填在 span 上；“某一刻发生了什么"优先记一条结构化日志——既符合新方向，也天然可搜索。

三、Traces、Metrics、Logs：三根柱子各自回答一个问题

到这可能会有一个误解：既然 tracing 这么好，是不是日志和指标就不需要了？

不是。它们是三种不同粒度的问题，互相不能替代：

信号	回答	Agent 里的典型用法
Metrics	“多少 / 趋势”	成功率、P95 延迟、token 消耗与成本、工具错误率
Traces	“哪里 / 路径”	单次 run 的完整执行路径、哪一步慢、哪一步失败
Logs	“具体是什么”	prompt/response 全文、工具入参出参、异常堆栈

换个说法：指标告诉你"出问题了”，trace 告诉你"出在哪个环节"，日志告诉你"那个环节具体发生了什么"。

三者真正的威力在关联。Agent 场景里最常见的一条排查路径长这样：

① 指标：今天 token 消耗比昨天涨了 40% ← Metrics 发现异常
② 点开这张图的某个时间点 ← 靠 exemplar 带出 trace_id
③ 落到那一次 run 的 span 树 ← 看到工具被循环调用了 12 次
④ 跳到对应 span 的日志 ← 看到检索关键词空字符串，导致反复搜

这条链要成立，靠的是一个共同的锚点：

trace_id 是把三根柱子缝在一起的线。 指标里带 exemplar 引用 trace，日志记录里带 trace_id/span_id，trace 上挂结构化的 usage 属性——三条路径都指向同一根线，你才能从"指标异常"一路点到"具体那次请求的日志"。

反过来说，如果日志里没有 trace_id，这套关联就断了，你又要回到"人肉 grep + 减时间戳"。

四、OpenTelemetry 埋点：从 API 到 span 树

OTel 的埋点 API 其实只有三层，理解了这个层次就不会写乱：

TracerProvider 一个进程一个，负责"把 span 送去哪里"（exporter / processor）
 └─ Tracer 按模块命名，比如 "agent.runtime"、"agent.tools"
 └─ Span 一次具体操作，就是树上的一个节点

最小可运行的接线（opentelemetry-sdk 1.44.0，2026-09 的版本）：

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
 BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("agent.runtime")

埋点本身，推荐用上下文管理器——它保证异常也会结束 span：

with tracer.start_as_current_span("agent.run") as span:
 span.set_attribute("run.id", run_id)
 span.set_attribute("gen_ai.conversation.id", session_id)

 with tracer.start_as_current_span("gen_ai.chat") as chat:
 chat.set_attribute("gen_ai.request.model", model)
 chat.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens)

注意 start_as_current_span 里的 current 两个字——它做的事情是"把新 span 设为当前 span 并放进上下文"，下一个 span 创建时就会自动认它当爹。父子关系不是手写的，是从上下文里自动读出来的。这也解释了为什么上下文一丢，span 树就会散成一片（下一节）。

如果用现成的框架，通常不需要手写这些。LangChain / LangGraph 走 callback，OTel 有 instrumentation 包能自动建 span；纯手写的 Agent Runtime 才需要自己决定"哪些动作值得单独一个 span"。我的经验是：

值得建 span：一次 LLM 调用、一次工具调用、一次检索、一次子 Agent 委派、一次 run 的起止。
不值得建 span：纯粹的参数拼装、字符串裁剪。这类动作建 span 只会让树变胖，真要记录就记事件/日志。

五、上下文传递：让父子关系不断链

这是入门到能用之间最容易被绊倒的一节。OTel 的上下文（Context）在 Python 里建立在 contextvars 之上，含义是"当前执行流里，此刻的当前 span 是谁"。它有两个天然的断裂点。

5.1 进程内：异步任务与线程池

asyncio 里 await 前后的上下文是连续的，一般不会丢。但下面这些会丢：

# 断链：新线程不会继承父线程的上下文
executor.submit(do_work) # do_work 里 get_current_span() 拿到的是 INVALID_SPAN（不记录的占位）

# 补救：显式把上下文复制过去
import contextvars
ctx = contextvars.copy_context()
executor.submit(ctx.run, do_work)

同理，process 池、Celery 之类的任务队列，都必须显式把上下文当参数传过去，再在另一端 attach。这类 bug 的表现很有辨识度：span 数量是对的，但全是平铺的——每个都是 root，没有父子关系。

5.2 跨进程：W3C Trace Context

跨服务传递靠的是 W3C 标准的 traceparent 头：

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
 │ └── trace_id (32 hex) ─────────┘ └─ parent ──┘ └flags
 └ version

注入和提取都是现成的：

from opentelemetry import propagate

# 发送方：把当前上下文写进 HTTP header
headers = {}
propagate.inject(headers) # -> {'traceparent': '00-...'}

# 接收方：从 header 还原上下文，再建 span 就会挂上去
ctx = propagate.extract(received_headers)
with tracer.start_as_current_span("remote.tool", context=ctx):
 ...

只要用了带自动埋点的 HTTP/gRPC 客户端，这一步通常是零成本的。但 Agent 场景有几个地方容易漏：

自己实现的流式接口（SSE 推 run 事件给前端）：手写的 fetch 或自定义协议不会自动带头，得手动 inject。
调用远程 MCP Server：这是最常漏的一处。MCP 的请求里如果没带 traceparent，那边的 span 就是一棵独立的树，你的 trace 到工具调用这一步就断了。
后台任务：异步评估、异步摘要、定时任务，这些不在请求链路里，需要显式把发起时的上下文带过去，否则它们永远是孤儿 span。

一个自查方法：跑一次完整 run，数一下 trace 里 root span 有几个。健康的 trace 只有一个 root；出现多个 root，说明某处上下文断了，去上面三个地方找。

六、三个最常见的坑

按"症状 → 原因 → 修复"记，方便回头查。

症状一：树是平的，所有 span 都是 root。 原因是上下文在异步/线程边界断了。修复：线程池用 contextvars.copy_context() 包一层；跨进程检查 traceparent 是否真的发出去了（抓一次包最快）。

症状二：某个 span 永远不结束，trace 一直在长。 原因是走了 start_span() 手动模式却忘了 end()，或者异常路径上没走到 end()。修复：默认用 start_as_current_span() 上下文管理器；确需手动模式就套 try/finally。

症状三：属性没上去，或者上报报类型错误。 原因是 OTel 的属性只接受基本类型（字符串、数字、布尔和它们的数组），结构化对象塞不进去。修复：结构化内容先 json.dumps() 成字符串；同时想清楚这个字段是不是该进指标维度。

七、速查表

概念	一句话	Agent 里对应什么
Trace	一次完整请求的全过程，有唯一 `trace_id`	一次 Agent Run
Span	一段有起止时间的工作，树上的一个节点	一次 LLM 调用 / 工具调用
父子关系	子 span 时间落在父 span 内，靠上下文自动建立	`agent.run` → `tool.web_search`
属性	键值对，描述 span"是什么"	`gen_ai.request.model`、`tool.name`
事件	带时间戳，记录"某一刻发生了什么"	重试、首个 token 到达、异常
Metrics	回答"多少 / 趋势"	成本、成功率、P95 延迟
Logs	回答"具体是什么"	prompt/response、工具入参出参
上下文传递	`contextvars`（进程内）+ `traceparent`（跨进程）	MCP 调用、SSE 流式、后台任务

几点收获

先问"我要回答什么问题"，再决定用什么信号。 “慢在哪一步"是 trace 的问题，“涨了多少"是指标的问题，硬用日志去回答前两个，就会退化成打印追踪。
属性填得对不对，看它能不能被拿来筛。 能筛的放属性，只能看时刻的放事件，这个口诀能解掉八成的纠结。
上下文是隐式的全局状态，隐式的东西最容易断。 凡是跨了线程、跨了进程、跨了任务队列的边界，都要问一句"当前 span 传过去了吗”。
trace_id 是整个可观测性的粘合剂。 日志里印上它、指标 exemplar 里带上它，三根柱子才真正连成一张网。
规范在变，别把 add_event() 写进新代码。 Span Event API 已经在 2026 年 3 月弃用，新的事件走 Logs API，能力不减，方向更统一。

基础篇到此，概念就这些。下一步是把它接到具体的观测后端上——gen_ai.* 字段怎么填、上报成功但看不到数据怎么办，这些实战里的坑见下一篇 Agent 埋点接 ARMS。

Agent 埋点接 ARMS：上报返回 success，控制台却是空的

Fri, 18 Sep 2026 18:05:00 +0800

上报接口返回 200，响应体是两个引号包着的 "success"。控制台刷新了五遍，调用链分析里 Span 数量: 0。

第一反应当然是上报没成功。于是回头去查 payload、查鉴权、查代理——查了小半个小时，最后发现数据一直都在，是我看的地方不对。

这篇文章把这个过程完整记下来。前面是排查（含三个可以复用的判别实验），后面是这次顺带做的一个具体问题：对话里带附件时，span 应该怎么记。

前置概念（Trace 与 Span、父子关系、属性与事件的边界、上下文传递）见同系列 Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点。本篇不重复讲基础，直接从"接进 ARMS 之后为什么看不到"讲起。

一、`gen_ai.*` 到底是什么

动手之前先明确一件事：埋点里那一堆 gen_ai.xxx 不是我起的名字，是 OpenTelemetry 的 GenAI 语义约定（Generative AI semantic conventions）——社区为"生成式 AI / LLM 应用"单独定义的一套属性规范。

它解决的问题很朴素。没有规范时，同一个"模型名"会被写成 model、model_name、llm.model；“输入 token"叫 prompt_tokens、input_tokens、usage.prompt。结果就是换个观测后端，埋点得重写一遍。

约定把名字、类型、取值都钉死了，所以一份埋点能同时被 Langfuse、Phoenix、ARMS 正确解析。它大致覆盖五类：

类别	属性	说明
操作身份	`gen_ai.operation.name`	`chat` / `embeddings` / `invoke_agent`
厂商与模型	`gen_ai.provider.name`、`gen_ai.request.model`、`gen_ai.response.model`	provider 是判别字段
对话内容	`gen_ai.input.messages`、`gen_ai.output.messages`、`gen_ai.system_instructions`	结构化消息，见下文
用量与结果	`gen_ai.usage.input_tokens`、`output_tokens`、`gen_ai.response.finish_reasons`	成本核算靠这组
工具与会话	`gen_ai.tool.name`、`gen_ai.tool.call.id`、`gen_ai.conversation.id`	关联工具调用与多轮会话

其中 input.messages / output.messages 是结构化的，不是一段纯文本。每条消息是 {role, parts[]}，part 有这些类型：

part 类型	必填字段	用在哪
`text`	`content`	普通文本
`uri`	`uri`、`modality`	文件已在对象存储里，span 只记引用
`file`	`file_id`、`modality`	用厂商预上传能力（如 OpenAI Files API）
`blob`	`content`、`modality`	只有必须内联时才用，base64 进 span 有成本也有合规风险
`tool_call` / `tool_call_response`	`name` / `response`	工具调用与结果

三个必须知道的坑：这些属性绝大部分还是 Development 状态，会改名——gen_ai.system 就被重命名成了 gen_ai.provider.name，gen_ai.prompt.* 也被 input.messages 取代；结构化属性落不到 span 上，OTel 的 Python SDK 只接受基本类型，所以得 json.dumps 成字符串再塞；input/output.messages 是 Opt-In 属性，规范明确说不该默认记录，因为可能含用户隐私。

二、span 树怎么设计

目标形态是一次 Agent Run 对应一棵 span 树，业务库的 Run 记录里存 trace_id 作为关联键：

agent.run [run.id=run-xxx, user.id=demo-user-1, session.id=demo-session-1]
├─ agent.attach_document file.uri / file.mime_type / file.size_bytes
├─ gen_ai chat gen_ai.input.messages / usage.* / latency_ms
├─ tool get_freight_quote gen_ai.tool.name / gen_ai.tool.call.id / tool.result
└─ gen_ai chat 基于工具结果的第二轮作答

写属性的部分收敛成几个 helper，别散在业务代码里——改名时只改一处：

def set_llm_request(span, *, provider, model, messages, conversation_id=None):
 span.set_attribute("gen_ai.operation.name", "chat")
 span.set_attribute("gen_ai.provider.name", provider)
 span.set_attribute("gen_ai.request.model", model)
 if conversation_id:
 span.set_attribute("gen_ai.conversation.id", conversation_id)
 # system 消息按约定不进 input messages，单独走 system_instructions
 span.set_attribute(
 "gen_ai.input.messages",
 json.dumps(to_input_messages(messages), ensure_ascii=False),
 )

to_input_messages 里做两件事：把 system 消息摘出去、把文本统一截断。截断不是可选项——input.messages 里塞进一个 8000 字的 prompt，span 会大得没法用。

三、一个 200 success 的假象

配置填完，跑起来，日志里看到这一行：

POST http://tracing-analysis-dc-sg.aliyuncs.com/adapt_<xx>_<xx>/api/otlp/traces HTTP/1.1" 200 9

200、响应体 9 字节（就是 "success" 加引号）。这种时候人很容易直接跳到"好，通了”，然后去控制台发现什么都没有，再回头怀疑人生。

我做了三个实验来定位问题到底在链路哪一段。这三个实验本身挺通用，值得记：

实验	操作	结果	排除了什么
绕过本地代理	`--noproxy '*'` 直连重发	同样 `200 "success"`	不是代理伪造的响应
发垃圾 payload	`head -c 300 /dev/urandom` 当 body 发过去	`400 Bad Request`	网关真的在解析 protobuf，不是无脑返回成功
伪造 license key	把 `/adapt_.../` 换成随机串	`403 Forbidden`	key 是有效的，且服务端会校验 workspace

三个实验做完，结论就很硬了：数据确实被服务端收下了，而且收进了一个合法的 workspace。既然服务端没问题，那"看不到"就只剩一种可能——去看的那个地方，不是数据所在的地方。

事实也确实如此。

四、三个坑

坑一：地域

接入点是 tracing-analysis-dc-sg.aliyuncs.com，dc-sg 就是新加坡。而控制台默认停在别的地域，调用链分析自然是空的。


症状	上报 `200 success`，控制台调用链分析 `Span 数量: 0`，左侧所有维度显示"没有匹配的值"
原因	控制台地域与接入点地域不一致。数据在 `ap-southeast-1`，眼睛在别处
修复	控制台切到与接入点同地域；`应用列表` 也要在同地域看

这类问题最坑的地方在于：它不报错。上报端一切正常，服务端一切正常，只有"人对不上"。

坑二：入口

地域切对之后，还有第二层错位。控制台里同一个应用有不止一个入口：

应用列表 分 OpenTelemetry 和 ARMS 两个页签。通过 OTel SDK 上报的应用只出现在前者；后者是 ARMS 探针接入的应用列表。看错页签 = 看到空列表。
应用维度的调用链分析 是带过滤的。我一度搜索框里直接粘 trace_id，仍然是 0 —— 因为页面作用域被钉死在某个应用上，搜索条件没换掉"应用"这个更大的前提。页面里搜出来的搜索框内容长这样：

serviceName:"agentrun-agent-quick-oUpbu" and resources.acs.arms.service_id : "azmulz8rp8..."

第三段 resources.acs.arms.service_id 是 ARMS 探针注入的资源属性。OTel 自己上报的 span 根本没有这个属性，所以这个条件永远匹配不上。


症状	搜 trace_id 也搜不到；应用列表某个页签永远是空的
原因	页面作用域（应用 / 页签）与数据的归属不匹配
修复	换到不绑定单个应用的入口，或把搜索条件改成 `serviceName:"<你的服务名>"`

坑三：配置写法

第三个坑不致命，但错误信息很难自查，因为不报错：

# 错的：ARMS 的 header 不是 Authorization: Bearer
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>

# 对的：HTTP 接入点鉴权编码在 /adapt_<xx>_<xx>/ 路径里，headers 留空
OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-analysis-dc-sg.aliyuncs.com/adapt_<xx>_<xx>/api/otlp/traces
OTEL_EXPORTER_OTLP_HEADERS=

# 只有 gRPC 才需要 header，格式是 Authentication=<token>
OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-analysis-dc-sg.aliyuncs.com:8090
OTEL_EXPORTER_OTLP_HEADERS=Authentication=<token>

还有一条同类的：HTTP 接入点自带 /api/otlp/traces，不要再拼 /v1/traces——那是本地 Jaeger 的写法，拼上去就是 404。

五、对话里带附件怎么记

这是这次真正想解决的问题：Agent 的对话里带了文件，trace 上该怎么表达。

关键决定是文件不进 span 的字节流。做法是三处落点：

位置	记什么
`agent.attach_document` span	`file.uri` / `file.mime_type` / `file.size_bytes` / `file.doc_id`
`gen_ai chat` 的 `gen_ai.input.messages`	该条 user 消息的 `parts` 里一个 `uri` part + 一个 `text` part
业务库	文件归属业务层（doc_id ↔ Run），trace 里只留引用

实测落进 ARMS 的属性长这样：

[{"role": "user", "parts": [
 {"type": "text", "content": "按附件里的信息报价"},
 {"type": "uri", "uri": "oss://bucket/uploads/doc-adcc4d1f/booking-note.txt",
 "modality": "document", "mime_type": "text/plain"},
 {"type": "text", "content": "订舱委托书 / BOOKING NOTE\n委托编号：BN-2026-0918-075…"}
]}]

三个设计取舍值得说一下：

第一，uri part 和 text part 成对出现。 uri 是溯源（文件从哪来），text 是模型真正读到的内容（服务端预抽取的结果）。只记 uri，排查时无法回答"模型到底看没看到附件"；只记 text，又丢了文件来源。两个都记才查得动。

第二，modality 是必填。 uri 和 file part 都要求这个字段，取值 image / video / audio / document。容易漏，漏了后端可能直接忽略这个 part。

第三，模型调用侧和 trace 侧要分开构造。 应用侧消息保留结构化内容（{type: "text"} / {type: "document"}），发给 OpenAI 兼容端点时拍平成纯文本；转成 gen_ai.input.messages 时才展开成 uri + text。这样两边各取所需，不会为了迁就某一方而变形：

# 模型侧：附件以抽取文本注入
def to_openai_content(content):
 if isinstance(content, str):
 return content
 chunks = []
 for item in content:
 if item["type"] == "text":
 chunks.append(item["text"])
 elif item["type"] == "document":
 chunks.append(f"[[附件 {item['uri']}]]\n{item['extracted_text']}")
 return "\n\n".join(chunks)

验证方式是让模型复述附件里的独有信息——它在回答里用上了委托书的 ETD 2026-09-25、截关时间和"14 天免箱期"。这说明附件确实进了模型上下文，不只是进了 span。

顺手补的一个洞：BatchSpanProcessor 默认靠 atexit 冲刷，进程被强杀（Ctrl-C、沙箱超时）时最后一批 span 会丢。Run 结束处显式 force_flush() 更稳。

六、数据怎么拿出来给 AI 看

控制台是给人看的，AI 想自己查得走另外三条路：

1. OpenAPI（免费，最直接）。xtrace 产品两个接口就能拼出一个导出脚本：

接口	作用	关键参数
`SearchTraces`	按条件列出调用链，返回 TraceID 列表	`RegionId`、`StartTime`/`EndTime`（毫秒）、`ServiceName`、`OperationName`、`MinDuration`、`Tag`、`PageNumber`/`PageSize`
`GetTrace`	按 TraceID 取完整 span 明细	`TraceID`、`RegionId`

翻页拿 ID，再逐条取详情，落地成 JSON 就完了。

2. 可观测 MCP Server（aliyun/alibabacloud-observability-mcp-server）。Go 单二进制，里面正好有对应的工具：

{
 "mcpServers": {
 "alibaba_cloud_observability": {
 "command": "./bin/alibabacloud-observability-mcp-server",
 "args": ["start", "--stdio"],
 "env": {
 "ALIBABA_CLOUD_ACCESS_KEY_ID": "<AK>",
 "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<SK>",
 "ALIBABA_CLOUD_REGION": "cn-singapore"
 }
 }
 }
}

接上之后可以直接问"昨天耗时最长的几条 Run 是什么，gen_ai.input.messages 里带没带附件"，由 umodel_search_traces / umodel_get_traces 去取。两个注意点：用只读 RAM 用户（AliyunARMSReadOnlyAccess），别用主账号 AK；sls_text_to_sql、sls_sop 这类 AI 工具走 STAROps 单独计费，不需要就在 config.yaml 的 enabled_tools 里关掉。

3. Collector 双写。反正上报端在自己手里，OTel Collector 同一份数据同时投 ARMS 和本地存储（ClickHouse / 文件 / 对象存储）。本地那份没有 AK、没有分页、随便 SQL——AI 分析用它比用控制台 API 舒服得多。ARMS 负责看瀑布图和告警，本地那份负责喂给 Agent。

总结

几个收获，都是这次真金白银换来的：

1. 200 不等于数据可用。 "success" 只说明网关收了，说明不了数据落到了你正在看的那个地方。判断"到底通没通"要有独立证据——我这次用的是"发垃圾字节看它报不报错"和"伪造 key 看它拦不拦"，两个实验各一次请求，就能把链路切段定位。

2. 可观测性接入的坑，多半在"人对不上"而不是"数据不通"。 地域、页签、页面作用域、filter 条件，这四样任何一个不对，现象都是同一个：空列表。而且全都不报错。排查时优先怀疑这个，比怀疑 SDK 划算。

3. 约定比实现重要。 用 gen_ai.* 的收益在这次很直观：同一份埋点，改个 endpoint 就从本地控制台切到了 ARMS，一行代码没动。代价是要接受它还在 Development、会改名——所以属性写入必须收敛到 helper 里。

4. 文件类数据，“引用 + 摘要"比"内容"有用。 把 pdf 塞进 span 不会让排查更容易，只会让它更贵更难搜。uri part 记来源、text part 记模型看到的内容、业务库存文件本身，三层各司其职。

5. 顺手能修的洞就别留着。 force_flush() 这种一行的事，不补就是"偶发丢 trace”，而偶发丢 trace 是最难查的那类问题——它会让上面所有的排查经验都建立在错误的观察上。

AG-UI：当 Agent 学会了和前端说话

Thu, 10 Sep 2026 14:30:00 +0800

最近在给自己的 Agent Runtime 设计输入输出契约时，我在 README 里画了一张三方对照表：我定义的事件类型一列、Runtime 原生事件一列，第三列空着——那是留给 AG-UI 的。填完这张表之后我发现，AG-UI 值得不只是一列，它值得被完整讲一遍。为了写这篇文章，我把官方仓库、Python SDK 源码和 PyPI/npm 的发布记录都翻了一遍，下面带着版本号讲。

先看仓库现状（2026-09-10）

先把事实钉住，本文所有描述都对应这个版本：

项	值
仓库	`github.com/ag-ui-protocol/ag-ui`，创建于 2025-05-07
文档	docs.ag-ui.com（draft spec + SDK 参考）
热度	15.8k stars / 1.4k forks，MIT License
本文对应 commit	`main@5f32a64ee999`（2026-09-09）
Python SDK	`ag-ui-protocol` 0.1.22（PyPI，2026-08-31 发布，首版 0.1.4 于 2025-04-30）
TypeScript SDK	`@ag-ui/core` 及 client/encoder/proto 系列 0.0.59（npm latest，另有 canary/alpha 通道）
发布节奏	几乎每日切一次 release（2026-08-20 到 09-09 切了 5 个），协议仍处 draft 阶段

Python 包只依赖 pydantic>=2.11.2，一个依赖，克制得不像一个协议实现。

三层协议的最后一块

把 2024-2026 这两年 agent 协议的版图摊开，会发现一个很规整的分层：

MCP（Anthropic）：agent ↔ 工具。让模型能标准地"伸手拿东西"。
A2A（Google）：agent ↔ agent。让多个 agent 标准地互相委派任务。
AG-UI（CopilotKit）：agent ↔ 前端。让 agent 的运行过程标准地"演给用户看"。

前两层这几年讨论得足够多了，第三层却长期处于"每家自己造"的状态：LangGraph 自己定义 stream mode，OpenAI Assistants 自己定义 run steps，各家 ChatUI 各自解析各家的事件格式。你写一个 agent 后端，想换个前端，事件层的适配就得重写一遍；你写一个聊天前端，想接不同的 agent，每种 agent 的 SSE 格式都得单独处理。

AG-UI 的野心就是把这层标准化掉。它不是委员会里设计出来的协议——它是从 CopilotKit 这个产品里长出来的：CopilotKit 做了几年"把 agent 嵌进 React 应用"这件事，攒够了事件类型的实战样本，回头把内部格式提炼成了开放协议，初始合作伙伴是 LangChain（LangGraph）和 CrewAI。这一点从仓库结构里看得见：integrations/ 目录下有 21 个条目——18 个框架适配层、2 个 server starter 模板加一个 community 目录；apps/ 里挂着 dojo（官方演示站）和一个 CLI 示例应用。

仓库解剖：一个协议 monorepo 长什么样

官方仓库是一个 pnpm + nx 的 monorepo，顶层结构本身就是协议生态的切片：

ag-ui/
├── sdks/
│ ├── python/ # ag-ui-protocol 0.1.22 (core + encoder)
│ ├── typescript/ # @ag-ui/core|client|encoder|proto 0.0.59 + cli
│ ├── dotnet/ # 官方 .NET SDK
│ └── community/ # dart / rust / ruby / c++ / kotlin / go / java ...
├── integrations/ # 20 个框架适配层(见后文生态一节)
├── middlewares/ # a2a / a2ui / mcp / mcp-apps / event-throttle
├── apps/ # dojo(官方演示) + client-cli-example
└── docs/ # 文档源

两个细节值得注意：middlewares 是独立一层——A2A 桥接、MCP 桥接、MCP Apps、A2UI、事件节流各占一个包，说明协议把"和别的协议对接"也当成了标准件而不是用户自理；protocol 有 TypeScript 和 Python 两套官方实现，且明确以 TypeScript 为参考实现（源码注释里直接写着 TS 的行为是其他 SDK 对齐的基准）。

事件流是唯一事实源

AG-UI 的核心设计只有一句话：agent 的一次运行 = 一条有序事件流，前端状态完全由事件序列归约得到。

没有独立的 REST 查询接口，没有"拉取当前状态"的端点。前端想知道 agent 在干什么？订阅事件流，逐条归约。想在断线后恢复？重新拿一遍事件（或快照），重放。这个思想和事件溯源（Event Sourcing）一脉相承，也和我自己的 Canonical Run 契约不谋而合——事件即事实，投影即状态。

协议在 0.1.22 的定义里共有 36 个事件枚举成员——31 个在用，加上 5 个已废弃的 THINKING_*（1.0.0 移除）。全部继承自一个四字段信封：

{
 "type": "TEXT_MESSAGE_CONTENT",
 "timestamp": 1730000000,
 "rawEvent": null,
 "metadata": {}
}

按功能分组看一眼全集，就能感受到协议想覆盖的交互光谱：

生命周期（5 种）——RUN_STARTED、RUN_FINISHED、RUN_ERROR 管起止，STEP_STARTED/STEP_FINISHED 标记过程里的小步。注意 run 的两个标识 threadId 和 runId 都是客户端生成的，服务端在 RUN_STARTED 里回显——这和 OpenAI 式"服务端生成 ID 返回给你"正好相反。

文本消息（4 种）——经典三段式 TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT（带 delta）→ TEXT_MESSAGE_END，外加一个 TEXT_MESSAGE_CHUNK 快捷形式：省掉配对开销，客户端自己展开。消息靠 messageId 关联。

工具调用（5 种）——TOOL_CALL_START（带 toolCallId 和 toolCallName）→ TOOL_CALL_ARGS（参数 JSON 增量下发，支持流式渲染参数）→ TOOL_CALL_END，加上 TOOL_CALL_RESULT 和 TOOL_CALL_CHUNK。

共享状态（3 种）——这是 AG-UI 最有辨识度的部分。STATE_SNAPSHOT 全量下发一份 typed state，之后 STATE_DELTA 用 RFC 6902 JSON Patch 增量同步。这意味着前端不只是"看"agent 生成文本，而是和 agent 共享一份可编辑的应用状态——agent 改了表单、改了画布、改了文档大纲，前端实时跟着变。CopilotKit 的生成式 UI 就建立在这上面。

活动消息（2 种）——ACTIVITY_SNAPSHOT/ACTIVITY_DELTA，聊天消息之间的结构化进度材料，为 generative UI 准备的通道。

推理（7 种）——REASONING_* 一族把思维链流式透出（REASONING_MESSAGE_CONTENT 的 delta），甚至有 REASONING_ENCRYPTED_VALUE 用于加密透传私有推理。另有 5 个旧的 THINKING_* 事件已废弃、1.0.0 移除。

子代理（3 种）——SUBAGENT_STARTED/FINISHED/ERROR，用 subagentRunId + parentSubagentRunId 构成树。有个字段很说明问题：SUBAGENT_STARTED 带可选的 parentToolCallId，直接支持"agent-as-tool"模式——子代理是父代理调用的一个工具（deep agents 的 task 就是这个模式），事件树和工具调用树是同一棵。

特殊（2 种）——RAW（底层框架事件透传）和 CUSTOM（自定义事件通道）。

能力声明：协议里藏着一份"agent 名片"

读 Python SDK 源码时的一个意外发现：除了事件和输入类型，ag_ui/core/ 下还有一个 capabilities.py（415 行），定义了一整套 AgentCapabilities 能力声明体系，十个分类：

分类	回答的问题	典型字段
`identity`	你是谁	name / type(框架标识) / version / provider / documentation_url
`transport`	怎么连你	streaming / websocket / http_binary / push_notifications / resumable
`tools`	你能调什么	supported / 自带工具清单(完整 JSON Schema) / parallel_calls / client_provided
`output`	你产出什么	structured_output / supported_mime_types
`state`	你的状态怎么管	snapshots / deltas / memory(跨会话记忆) / persistent_state
`multi_agent`	你和谁协作	delegation / handoffs / sub_agents 清单
`reasoning`	你的思考可见吗	supported / streaming / encrypted(零数据保留模式)
`multimodal`	什么模态进、什么出	input: image/audio/video/pdf/file; output: image/audio
`execution`	你的执行边界	code_execution / sandboxed / max_iterations / max_execution_time
`human_in_the_loop`	人在哪介入	approvals / interventions / feedback / interrupts / approve_with_edits

关键语义写在 docstring 里：“所有字段可选，缺省意味着未声明（unknown），不等于不支持”——典型的开放协议渐进声明风格；外加 custom 逃生舱给集成特有能力。这份能力体系和我之前给自己协议设计 discovery 契约（RuntimeDescriptor）时想解决的问题一模一样：让调用方在运行前就知道对端有什么。AG-UI 的答案粒度更细——它同时服务于"agent 市场、发现 UI、调试"三类消费场景，甚至 sub_agents 清单的注释都写着"帮助客户端构建 agent 选择界面"。

输入：全量历史的无状态哲学

事件流往回走，输入往前送。AG-UI 的请求体 RunAgentInput 长这样：

class RunAgentInput(BaseModel):
 thread_id: str # 会话标识
 run_id: str # 本次运行,客户端生成
 parent_run_id: str | None # agent-started-agent 场景的父 run
 state: Any # 起始共享状态
 messages: list[Message] # 全量对话历史,按序
 tools: list[Tool] # 前端工具定义
 context: list[Context] # 注入上下文
 forwarded_props: Any # 透传段,中间层不得改动
 resume: list[ResumeEntry] | None # 中断应答

最有态度的是 messages：全量历史回传，按序，无旁路通道。服务器不存对话记忆，每一轮前端把完整历史发过来。这是刻意的——无状态服务器好扩展、好重放、好调试，代价是每轮请求变大、长对话依赖客户端裁剪。

消息定义了七种角色：developer、system、assistant（可带 OpenAI 风格的 tool_calls）、user（支持多模态：text/image/audio/video/document，URL 或 base64 inline）、tool（工具结果）、activity（渲染材料，发送前必须剥离，不作为恢复历史）、reasoning。

人在回路是一个完整闭环：RUN_FINISHED 的 outcome 可以是 {type: "interrupt", interrupts: [...]}——agent 停下来等输入，且源码里有校验：interrupt outcome 至少携带一个 interrupt，空的直接构造失败。每个 interrupt 带 id、reason、可选的 response_schema 和 expires_at；客户端下一轮在 resume 数组里逐条应答（resolved 或 cancelled，可带 payload）——审批、确认、澄清问题，都是这个机制的产品化。能力声明里的 approve_with_edits 说明连"批准前修改参数"都在协议考虑内。

从 SDK 源码里读出的工程细节

我读了 Python SDK（ag-ui-protocol 0.1.22）的几个核心模块，这几处注释值得单独说：

序列化的血泪史。基类 ConfiguredBaseModel 自定义了 serializer：可选字段为 None 时，整个键从线上 JSON 省略，而不是写 null。注释里明说了缘由——Python SDK 曾是唯一把 null 写上线的 producer，为此协议吃了三个兼容补丁（TOOL_CALL_START.parentMessageId、TOOL_CALL_CHUNK.parentMessageId、RUN_FINISHED.outcome）。类型注释里那句"在基类上统一省略，才能保证每一条序列化路径都生效"是一位工程师被 null 坑过之后的防御性姿势。字段 camelCase 上线（alias_generator=to_camel），extra="allow" 放行未知字段——协议演进不锁死旧 producer。

token 计数的跨语言红线。token_usage.py 里有一个细节：所有计数上限被钳在 2⁵³−1——不是 int64 的上限，而是因为"TypeScript 的 protobuf 解码器停在 Number.MAX_SAFE_INTEGER，这才是各语言绑定之间的真实天花板"。而且注释明确写了这个结构会喂给匿名遥测，不允许携带任何内容字段（无 prompt、无补全、无 thread/run/user ID），只有 provider/model 标签和纯数字。跨语言兼容和隐私边界都焊死在类型定义里。

metadata 的克制。每个事件都带可选 metadata，开放键值空间，但保留 "ag-ui" 键给协议自己用——而且是纯约定，不做运行时强制。注释的原话：验证它的 shape 会"contradict that"（与开放性矛盾）。

双编码传输。encoder.py 不只是 SSE——协议定义了二进制编码，媒体类型 application/vnd.ag-ui.event+proto（protobuf over HTTP），TypeScript 侧有独立的 @ag-ui/proto 包维护 .proto 定义。文本 SSE 用于开发调试，二进制用于生产，同一套事件类型两种编码。

运行时管线：一次 run 的完整解剖

前面讲的是协议的"静态"部分（类型和字段）。协议真正的工程含量在客户端 SDK 的运行时管线里——一次 runAgent() 调用背后是一条精心编排的 RxJS 管道。以 TypeScript @ag-ui/client 0.0.59 的 AbstractAgent.runAgent()（src/agent/agent.ts）为例，事件从网络到你的回调要穿过这条流水线：

run()（子类实现,发 HTTP/SSE 请求）
 ↓ pipe 依次串接:
① middleware 链 ← reduceRight 组装成洋葱模型
② transformChunks ← CHUNK 快捷事件展开成三段式
③ verifyEvents ← 事件文法状态机校验
④ takeUntil(detach$) ← 单次运行的中止信号
⑤ apply ← 把事件归约进 messages/state
⑥ processApplyEvents ← 分发到 subscriber 回调
⑦ catchError / finalize ← 错误与收尾

每一层都可以单独讲。这正是"看哪些文件"的答案：读懂这七个环节，你就读懂了 AG-UI 客户端的全部。

① Middleware：洋葱模型的拦截器

中间件机制定义在 src/middleware/middleware.ts。核心接口只有一个方法：

abstract class Middleware {
 abstract run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;

 // 调下一个 agent,附带 chunk 展开
 protected runNext(input, next) {
 return next.run(input).pipe(transformChunks(false));
 }

 // 调下一个,且把每一步之后的 messages/state 一起带出来
 protected runNextWithState(input, next): Observable<EventWithState> { ... }
}

组装方式是 agent.ts 里的 reduceRight——数组里后注册的中间件先执行，next 指向链上更内层的 agent（最内层是真正 agent 的 run()）。这就是经典的洋葱模型，和 Koa/Express 中间件一个思想。

有意思的是 runNextWithState 的实现：它用一个 ReplaySubject 把事件喂给 defaultApplyEvents（事件归约器），让中间件在每个事件后都能拿到"应用了这个事件之后"的 messages 和 state——中间件因此能基于语义状态做决策，而不只是看原始事件。实现里那句 await new Promise(resolve => setTimeout(resolve, 0)) 是给归约器留一个微任务窗口同步状态，朴素但有效。

官方仓库 middlewares/ 目录下有 6 个可参考的成品：event-throttle（按帧率节流 + 合并 delta）、mcp（把 MCP 工具桥接进事件流）、a2a（A2A 协议互转）、a2ui、mcp-apps，外加一个 middleware-starter 脚手架。

② 三个值得抄的中间件设计

EventThrottleMiddleware（middlewares/event-throttle-middleware/src/index.ts）——把高频 delta 按时间窗（默认 16ms ≈ 60fps）和最小字符数节流并合并，防止前端被打爆。它的三个设计决策都写满了"为什么"：

其一，只对白名单事件做缓冲。BUFFERABLE_EVENT_TYPES 是显式白名单（各种 *_CHUNK、*_CONTENT、STATE_*、ACTIVITY_*），不在表内的事件一律立即透传。注释原话：“这是白名单而非黑名单，这样协议将来新增的事件类型默认走立即透传——对生命周期/边界事件来说，这是更安全的失败模式。“新事件宁可多一次渲染，也不能被错误地延迟。

其二，合并只在同一 subagent lane 内进行。chunk 的合并键是 JSON.stringify([kind, owner, entityId])——用 JSON 编码而不是分隔符拼接，因为 owner/id 是任意字符串，“任何分隔符都可能出现在某个分量里，把两个不同的 (owner, id) 别名到同一个键上”。这个注释值得所有写缓存键的人读一遍。

其三，metadata 反向合并。合并两个 chunk 时，role/name 取第一个（它们只出现在首 chunk），但 metadata 取最后一个并按 key 逐项合并——因为 metadata 是设计成"最后到达"的，携带 usage 和 finish reason。“在这里丢掉它会吞掉一个纯 usage 的尾 chunk。”

FilterToolCallsMiddleware（src/middleware/filter-tool-calls.ts）——按工具名拦截工具调用事件。看起来平平无奇，但注释记了一个真实并发 bug：中间件实例是跨 run 复用的，如果被拦截的 toolCallId 集合放在实例上，“一个卡住的 run 的订阅还开着时，下一个 run 启动会抹掉那些还在过滤这个卡住的 run 的 id，于是它被禁的工具的 TOOL_CALL_ARGS/END/RESULT 就开始漏出来了”。解法是用 defer 给每个订阅一份独立集合，并在 RUN_STARTED 时重置。并发场景下"状态放实例还是放订阅"这个坑，这是教科书级的案例。

四个 BackwardCompatibility 中间件（src/middleware/backward-compatibility-0-0-*.ts）——这是我见过最优雅的协议演进手法。agent 构造时读对端声明的 maxVersion，按版本号自动插到中间件链最前面：

if (compareVersions(this.maxVersion, "0.0.39") <= 0) {
 this.middlewares.unshift(new BackwardCompatibility_0_0_39());
}
if (compareVersions(this.maxVersion, "0.0.57") <= 0) {
 // 0.0.57 之前的 agent 不认识 subagent:剥掉 subagentRunId、丢弃 SUBAGENT_* 事件
 this.middlewares.unshift(new BackwardCompatibility_0_0_57());
}

0.0.45 中间件把废弃的 THINKING_* 事件翻译成新的 REASONING_*，0.0.47 把老的 BinaryInputContent 映射成新的分模态输入类型，0.0.57 给不认识 subagent 的老客户端剥掉归属字段。每个协议破坏性变更都固化为一个可测试、可移除的适配中间件，而不是散落在业务代码里的 if-else。协议处于日更的 draft 阶段还能保持向后兼容，靠的就是这套机制。

③ verifyEvents：1052 行的事件文法状态机

src/verify/verify.ts 是整个客户端最硬核的文件——它把"合法的 AG-UI 事件流"编码成了一个状态机，逐事件校验。维护四组"哪些实体还开着"的集合（文本消息、工具调用、推理、活动），外加每个实体类型的归属映射（哪个 subagent 开的）。

这个文件的注释本身就是一部协议演进史，每条规则背后都是真实 bug：

为什么 owners 按实体类别分桶：一个 message 和一个 tool call 可以都叫 “x” 而不冲突。早期单个桶时，“tool call 的写入会覆盖 message 的 owner，导致后续一个加密值拿了错误的 owner 做校验而被接受”。
为什么 owners 关闭后不清除：REASONING_ENCRYPTED_VALUE(subtype="tool-call") 合法地要在 TOOL_CALL_END 之后到达，“清掉 owner 会让这个不匹配变得无法匹配从而接受一个错误的”。
为什么 step 要按 (owner, name) 嵌套 Map 而不是拼字符串：曾经用分隔符拼接 owner 和 name，结果"没有 owner 的父级会和 subagent id 是空字符串的实体撞键”——而空字符串是合法的 opaque id。注释直言：“有个设计伙伴从真实的 deepagents run 里报回了这个 bug：合法的嵌套 step 被拒，而非法的跨 owner 关闭却被接受。”
为什么 STEP_STARTED 判重按 owner 分：父 agent 和子 agent 常常跑同一个图，两边同时有一个叫 “tools” 的 step 是合法的（父的包着委派，子的是自己的内部工作）——按名字单独判重会把合法嵌套当成错误拒绝。

这些不是设计文档里能写出来的东西，全是生产流量打磨出来的。想理解 AG-UI 的边界条件，verify.ts 比 spec 更有信息量。

④ transformChunks：快捷事件的双向门

src/chunks/transform.ts（564 行）负责 *_CHUNK 快捷事件和 *_START/CONTENT/END 三段式之间的转换。核心概念是 lane（通道）：每个 subagent 一条，“一条 lane 上最多有一路正在组装的流，因为 chunk 的简写只靠’和之前一样’来标识延续”。这里也有个精妙的元数据规则——chunk 的 metadata 会扩散到由它合成的每个事件上，但绝不施加于关闭前一条消息的合成 *_END，“这就是防止某个 chunk 的 metadata 泄漏到它正在关闭的那条消息上的原因”。

⑤ apply 与 subscribers：归约器和观察者

src/apply/default.ts（约 1500 行）是事件归约器——一个巨型 switch(event.type)，把每一种事件映射成 messages/state 的变更（AgentStateMutation）。这是"事件即事实、状态即投影"落地的地方。它对 *_CHUNK 事件直接抛错（TEXT_MESSAGE_CHUNK must be transformed before being applied）——这是管线的纪律：chunk 必须先过 transformChunks 这道门，归约器只认展开后的三段式。

src/agent/subscriber.ts（408 行）则是应用层的观察者接口，钩子分三类：生命周期（onRunInitialized/onRunFailed/onRunFinalized）、按事件类型（onTextMessageContentEvent 连 textMessageBuffer 都给你拼好了、onToolCallArgsEvent 带 toolCallBuffer 和 toolCallName）、变更通知（onMessagesChanged/onStateChanged）。

这里有个订阅者协议的关键设计：订阅者不直接改状态，而是返回一个 AgentStateMutation，由 runSubscribersWithMutation 统一应用。多个订阅者的 mutation 可以 stopPropagation 拦截后续订阅者——订阅者之间也是中间件式的。实现里还有一段性能注释：dev 环境会对输入做 structuredClone + deepFreeze 来抓"原地修改"的 bug，但这个守卫是"每个事件最大的一笔分配”，流式大参数时会把 V8 堆打爆，所以它在生产环境关闭、dev 环境下 payload 过大时也跳过——“常见的不改状态的事件cost 零次克隆”。

怎么读 AG-UI 的源码：一份导航

如果你要接 AG-UI 或者只是想学它的设计，按这个顺序读最省时间：

第一梯队——协议本身（先读，两小时）

文件	读什么
`sdks/python/ag_ui/core/events.py`	全部事件类型（555 行，每个类型的字段和约束都在）
`sdks/python/ag_ui/core/types.py`	`RunAgentInput`、七种消息、多模态、中断类型（416 行）
`sdks/python/ag_ui/core/capabilities.py`	能力声明体系（415 行，看注释里的"为什么这样设计"）
`sdks/python/ag_ui/encoder/encoder.py`	SSE 与二进制编码（很短，看序列化约定）

第二梯队——客户端运行时（TypeScript packages/client/src/，深读）

文件	读什么
`agent/agent.ts`	运行管线七环节 + middleware 链组装 + 生命周期（看 `runAgent`）
`middleware/middleware.ts`	洋葱模型基类 + `runNextWithState` 的状态追踪
`middleware/backward-compatibility-0-0-*.ts`	协议演进如何固化成中间件（四份文件一起看）
`verify/verify.ts`	事件文法状态机（注释里的 bug 案例最值钱）
`apply/default.ts`	事件归约器（看状态怎么从事件投影出来）
`chunks/transform.ts` + `agent/subscriber.ts`	chunk 双向门 + 订阅者协议

第三梯队——生态接线

目录	读什么
`integrations/langgraph/{python,typescript}/`	一个真实框架适配层的全貌（含中断处理、SSE 断线恢复测试）
`middlewares/event-throttle-middleware/`	生产级中间件的最完整示例（含性能和不变量注释）
`apps/dojo/`	官方演示站，交互式体验所有事件类型

一个实用建议：读 TS 客户端时先读注释再读代码——这个仓库的注释密度和坦诚度罕见，“我们当初这么写、后来发现 X 有问题、现在的写法是 Y、原因是 Z"的叙事随处可见。很多边界条件 spec 里没有，但注释里有。

生态：谁在用它

AG-UI 的知名产品就是创造它的 CopilotKit（React 前端 agent 框架，useCopilotAction 的 human-in-the-loop 模式就是协议里前端工具机制的产品化），加上官方 demo 站 Dojo（apps/dojo，仓库内）。

但真正的覆盖面在 integrations/ 目录里，18 个框架适配层的原文清单：LangGraph、LangChain、CrewAI、Microsoft Agent Framework、Google ADK、AWS Strands、Agno、Mastra、Pydantic AI、LlamaIndex、AG2、Vercel AI SDK、watsonx、Langroid、Claude Agent SDK、Claude Managed Agents、A2A、Agent Spec，另有两个 server starter 模板。社区 SDK 覆盖 Dart、Rust、Ruby、C++、Kotlin、Go、Java。客户端不止浏览器——终端、React Native、Slack、Teams 都能当 AG-UI client。

不过要校准一下预期：AG-UI 的"知名"集中在框架生态，不是终端产品。和 MCP 一样，它是管道协议，终端用户永远看不到它——人们用的是接了它的 CopilotKit 应用和 LangGraph agent。

和有状态 Runtime 的张力

最后说一个我实际设计契约时撞上的问题。AG-UI 的无状态模型很优雅，但我的 Runtime 是有状态的：对话记忆按 session_id 存在服务端（SQLite checkpointer），每次 Run 只需要送最新的问题。

两套范式接在一起时的正确姿势是：AG-UI 前端发全量 messages，adapter 只取最后一条 user 消息作为 Runtime 的输入，历史由服务端记忆提供；事件流方向则反过来，把 Runtime 的事件投影成 AG-UI 事件喂给前端。适配层的本质是两种会话范式之间的翻译。

还有几块 AG-UI 有、多数自研契约没有的东西，值得列为后续演进的清单：interrupt/resume 的人在回路（自研契约通常只有"取消”，没有"挂起等输入"）、共享状态的 StateSnapshot/StateDelta、子代理事件树、前端工具的反向执行回路，以及那份克制的能力声明体系。

三层协议凑齐之后的图景其实很清晰：MCP 让 agent 拿到工具，A2A 让 agent 找到同伴，AG-UI 让用户看见过程。你的 agent 用哪套实现无所谓——只要它在这三个边界上说标准语言，就同时获得了被所有前端渲染、被所有 agent 编排、被所有工具增强的资格。

本文基于 ag-ui-protocol/ag-ui main@5f32a64ee999（2026-09-09）、Python SDK ag-ui-protocol 0.1.22、TypeScript SDK @ag-ui/client 0.0.59 写成，源码研读覆盖 sdks/python/ag_ui/core/（events / types / capabilities / token_usage / encoder）与 sdks/typescript/packages/client/src/（agent / middleware / verify / apply / chunks / interrupts）、middlewares/event-throttle-middleware/。协议处于 draft 阶段、日更演进，引用前请核对最新版本。

Agent Run 流式协议：事件溯源、SSE 投影与断线恢复

Mon, 07 Sep 2026 10:30:00 +0800

很多 Agent 系统的流式输出，本质上是把模型服务的 chunk 直接转发给浏览器。这样做上线很快，但一旦遇到刷新页面、断线重连、审计和取消，就会立刻发现：前端消费的不是一个可恢复的事件流，而是一条一次性管道。

我现在的做法是把协议拆成三层：Runtime 先产出领域事件，Adapter 统一映射成 canonical 事件并落库，最后由 SSE 端点从事件库里做投影。这篇文章记录这套协议的实际形态，以及它为什么这样设计。

一、三层结构

整条链路可以这样理解：

Runtime / Runner
 └─ AgentEvent 执行器内部事件
 └─ Adapter 映射
 └─ AgentRunEvent canonical 事实，落库并分配 seq
 └─ SSE 端点 committed event 的投影
 └─ 前端

Runner 端口层

AgentEvent 是 Runtime 对外的最小事件模型，目前有 7 种类型：

类型	专用字段	含义
`state_change`	`state`	Runtime 内部状态迁移
`delta`	`content`	模型文本增量
`tool_call`	`tool_name` / `tool_call_id` / `tool_args`	工具调用开始
`tool_result`	`tool_name` / `tool_call_id` / `tool_result`	工具结果摘要
`artifact`	`artifact`	结构化产物元数据
`done`	`answer`	最终答案全文
`error`	`error_code` / `error_message`	失败

这一层有意做薄。不管 Runtime 是 LangGraph、DeepAgents，还是新接的沙箱执行器，只要转换成这 7 类事件，后端后面的所有逻辑都不用重复实现。

Canonical 层

Adapter 把 Runtime 事件映射成 canonical 事件。canonical 层不是照抄 Runtime 词汇，而是补齐运行生命周期：

Canonical 事件	来源	payload 要点
`run.started`	Adapter 生成	`started_at`
`message.started`	Adapter 生成	`message_id`、`role`
`message.delta`	`delta`	`message_id`、`content_index`、`delta`
`tool.call.started`	`tool_call`	`tool_call_id`、`tool_name`、`arguments`
`tool.call.completed`	`tool_result`	`result`、`result_checksum`
`artifact.created`	`artifact`	产物 metadata
`message.completed`	`done`	`content`、`content_checksum`
`run.completed`	`done` 后置	`message_id`
`run.failed`	`error`	`error.code`、`error.message`、`error.retryable`
`run.cancelled`	取消路径	`external_stop_confirmed`

落库后的 envelope 长这样：

{
 "run_id": "run_xxx",
 "seq": 4,
 "event_type": "message.delta",
 "occurred_at": "2026-09-07T10:30:00.123456",
 "recorded_at": "2026-09-07T10:30:00.126000",
 "agent_id": "freight_agent",
 "agent_snapshot_checksum": "...",
 "payload": { "message_id": "message_xxx", "delta": "..." },
 "payload_checksum": "...",
 "schema_version": 1,
 "trace_id": "...",
 "span_id": "..."
}

这里最重要的是 seq。Runtime 事件本身不携带权威序号；Adapter 只提交 candidate，repository 落库时按 last_event_seq + 1 分配。事件一旦提交，顺序就是系统事实。

二、SSE wire format

对外入口是：

GET /api/agent-runs/{run_id}/events

SSE 使用命名帧：

id: 4
event: message.delta
data: {"run_id":"run_xxx","seq":4,"event_type":"message.delta",...}

几个关键语义：

重放优先。 客户端可以用 ?after_seq= 查询参数，也可以用标准 SSE 的 Last-Event-ID 请求头；服务端取较大值，然后从事件库里回放。
游标安全。 游标为负，或大于当前 last_event_seq，返回 422，避免客户端拿着错误游标等一个永远不会来的事件。
实时推送。 端点每 250ms 从 committed repository 拉取新事件；发现序号 gap 就断流，不静默跳过。
keep-alive。 空闲 15 秒发送 SSE 注释帧 : keep-alive。
自然终止。 Run 进入终态且事件全部送完，连接主动关闭。

一次成功 Run 的典型序列：

id: 1 event: run.started
id: 2 event: message.started
id: 3 event: message.delta
id: 4 event: tool.call.started
id: 5 event: tool.call.completed
id: 6 event: message.delta
id: 7 event: artifact.created
id: 8 event: message.completed
id: 9 event: run.completed

失败或取消时，终态分别是 run.failed 或 run.cancelled。Adapter 用一个终态闸保证三者最多出现一个。

三、为什么先落库，再投影

这是整套协议的核心取舍。

断线恢复变成查询问题

客户端刷新页面后，不需要 Runtime 重跑一遍，也不需要服务端缓存整个连接状态。只要带上 Last-Event-ID: 5，服务端就查询 seq > 5 的事件继续发。断线恢复从连接层问题退化成数据库查询问题。

Runtime 崩溃不丢执行事实

事件写入 committed store 之后，Runtime 进程是否还活着，不影响前端重放历史。审计、排障和 UI 恢复消费的是同一份数据。

多 Runtime 共享同一套前端协议

不同执行器的事件风格可能差异很大。Adapter 负责把差异吸收在入口处，前端只认识 canonical 词汇。新增 Runtime 时，可以避免出现“沙箱一套流、业务 Agent 一套流”的分裂。

工具调用能稳定配对

tool_call_id 优先使用底层模型下发的 id。如果 Runtime 丢了开始事件，Adapter 会补发一个 tool.call.started，让 UI 仍然成对渲染。这个“配对自愈”很小心地只影响展示完整性，不把 Run 打成失败。

四、当前边界和改进方向

这套协议也有几个明显的边界。

SSE 出口是客户端胖投影。 目前 data 帧直接序列化完整 envelope，agent_snapshot_checksum、provenance、payload_checksum 等审计字段也被发给前端。短期省事，长期更适合收敛成只包含 seq、event_type、occurred_at、payload 的客户端投影。

实时性靠 250ms 轮询。 对文本流足够，但并发观看的连接多了，数据库查询会线性放大。合理演进是加一个进程内或跨实例 pub/sub，只负责“唤醒”轮询，不负责权威事件投递；事件仍然以数据库为准。

内容模型只有文本增量。 message.delta 目前只有 content_index 和文本，没有结构化 content block。未来要支持图片、图表卡片或分块富文本，应增量引入 block 类型，而不是扩出新的顶层事件。

state_change 是死词汇。 Runtime 端口定义了它，但 canonical Adapter 不会映射。后续应该删除或明确语义，避免接入方误以为它会被消费。

协议演进规则需要写死。 客户端对未知事件类型必须忽略，而不是报错。schema_version 目前存在，但配套演进策略还要补文档。

总结

这套协议不是行业标准，传输层用的也不是什么新东西，但它把几件事做对了：事件先成为带序号的事实，SSE 只是投影；Runtime 词汇保持最小，canonical 词汇保持稳定；断线恢复用标准 SSE 游标；工具调用、产物、失败、取消全部事件化。

如果要从这套设计里抽象一条通用经验，那就是：Agent 的远程流式接口不应该让客户端订阅“模型的输出过程”，而应该让客户端订阅“系统已经发生并且可恢复的执行事实”。管道可以丢，事实不应该丢。

全量解码与增量解码：原理、区别以及应用

Fri, 14 Mar 2025 17:49:58 +0800

引言

在自然语言处理（NLP）领域，尤其是大语言模型（LLM）中，解码（decoding）是模型生成输出的核心步骤。你可能好奇：为什么模型接收到完整输入后，生成回复时却不是一次性吐出整个句子？答案在于解码方式的不同。本教程将详细讲解两种主要解码方式——全量解码和增量解码，包括它们的定义、原理、优缺点、区别，以及在大语言模型中的应用。

第一部分：什么是解码？

解码的定义

解码是大语言模型根据输入生成输出的过程。简单来说：

输入：用户给模型一个问题或句子（比如“请解释一下AI”）。
解码：模型根据内部表示（概率分布或隐藏状态），逐步或一次性生成回答（比如“AI是一种技术”）。

输入与解码的区别

输入阶段：
- 用户通常是一次性把完整输入（比如“我不太懂，模型输入不是一次性就输入进去了吗”）交给模型。
- 模型会通过编码器（如果是Encoder-Decoder架构，如T5）或直接通过自回归方式（像GPT）处理整个输入，生成某种内部表示（比如隐藏状态或上下文向量）。
解码阶段：
- 解码是模型根据输入生成输出的过程，也就是从内部表示逐步生成文本的过程。
- 即使输入是一次性给的，模型生成输出时并不一定一次性吐出整个答案，而是需要一步步决定每个词（或标记），这就是解码方式的重点。

换句话说，输入是一次性给模型的，但输出（解码）可以是逐步生成的。全量解码和增量解码的区别在于：模型是如何基于输入一步步生成输出的。

为什么解码不是一次性完成？

大语言模型（尤其是基于Transformer的模型）通常是自回归的，意味着它们生成输出的方式是序列化的：每生成一个词，模型会把这个词加入上下文，再预测下一个词。这种设计有以下原因：

1. 语言的序列性质： 自然语言是有序的，比如“我喜欢你”和“你喜欢我”意思完全不同。模型需要逐词生成，才能保证语法和语义的连贯性。如果一次性生成整个句子，模型需要同时决定所有词，这在计算上非常复杂，且难以保证一致性。

2. 模型架构限制： GPT这类模型是自回归的，当前词的预测依赖于之前生成的词。它们没有能力一次性输出整个序列，而是必须逐步构建。即使是Encoder-Decoder模型（如T5），解码器在生成时也是逐步进行的。

3. 概率分布： 模型每一步会输出一个概率分布（比如下一个词可能是“我”0.7、“你”0.2、“他”0.1），然后根据解码策略（贪心、采样等）选择一个词。这个过程天然是增量的，因为每一步的选择会影响下一步的概率。

第二部分：全量解码 (Full Decoding)

定义

全量解码是指模型一次性生成或评估整个输出序列，试图找到全局最优解。它强调对所有可能输出的全面考虑。

工作原理

接收完整输入（比如“你好”）。
计算所有可能的输出序列及其概率：
- “Hello” (0.9)
- “Hi there” (0.7)
- “Greetings” (0.5)
选择得分最高的序列（比如“Hello”）作为输出。

典型算法

束搜索 (Beam Search)：维护一组候选序列（束），每步保留得分最高的前k个，最终选最佳序列。
维特比算法 (Viterbi Algorithm)：在隐马尔可夫模型中寻找全局最优路径。
（注：真正的全量解码需要遍历所有可能性，但在实践中因计算量太大，通常用近似方法。）

优点

全局最优：考虑整个序列的上下文，结果更连贯。
高质量：适合需要精确输出的任务。

缺点

计算复杂度高：可能的序列组合随长度指数增长。
实时性差：需要等待完整计算，无法边生成边输出。

应用场景

机器翻译（追求高质量翻译）。
文本摘要（需要全局一致性）。

第三部分：增量解码 (Incremental Decoding)

定义

增量解码是指模型逐步生成输出序列，每一步只基于当前信息预测下一个词，而不依赖未来全局信息。它是一种“边解码边生成”的方式。

工作原理

接收输入（比如“你好”）。
逐步生成输出：
- 第一步：输出“Hello”。
- 第二步：根据“Hello”决定是否继续（如停止或加词）。
重复直到生成完整序列或达到终止条件。

典型算法

贪心解码 (Greedy Decoding)：每步选择概率最高的词。
采样解码 (Sampling)：根据概率分布随机选择词（如Top-k或Top-p采样）。

优点

高效：每步计算量小，适合快速响应。
实时性强：边输入边输出，用户体验好。
资源占用低：无需存储所有可能性。

缺点

局部最优风险：每步只看当前，可能偏离全局最优。
上下文不足：无法利用序列后部的完整信息。

应用场景

实时对话（聊天机器人）。
流式语音转文字（边说边转录）。

第四部分：全量解码与增量解码的对比

特性	全量解码	增量解码
生成方式	一次性生成整个序列	逐步生成序列
优化目标	全局最优	局部最优
计算复杂度	高（指数级）	低（线性或接近线性）
实时性	差（需完整输入和计算）	强（边输入边输出）
上下文依赖	依赖整个序列	只依赖当前和之前
典型算法	束搜索、维特比算法	贪心解码、采样解码

举例说明

输入：“I love you”。
全量解码：
- 计算所有可能翻译：
  - “我爱你” (0.9)
  - “我喜欢你” (0.6)
  - “我爱你们” (0.3)
- 输出：“我爱你”。
增量解码：
- 逐步生成：
  - “我” → “爱” → “你”。
- 输出：“我爱你”。

举例说明2

假设你输入：“请解释一下AI”。

输入阶段：模型一次性接收“请解释一下AI”，并理解其含义（通过编码器或自回归上下文）。
解码阶段：
- 增量解码（实际常用）：
  - 模型先输出“AI”，然后根据“AI”预测“是”，再根据“AI是”预测“一种”，逐步生成“AI是一种技术”。
  - 你可能会看到我逐词回复，像这样：AI→是→一种→技术。
- 全量解码（理论上）：
  - 模型计算所有可能的回答：
    - “AI是一种技术” (概率 0.9)
    - “AI是人工智能” (概率 0.85)
    - “AI很复杂” (概率 0.6)
  - 然后一次性输出“AI是一种技术”。
  - 但实际上，这需要巨大计算量，通常只用近似方法（如束搜索）。

第五部分：大语言模型中的解码方式

现状

现代大语言模型（如GPT、ChatGPT、Grok）主要基于自回归架构，天然倾向于增量解码，但会根据任务搭配不同策略。

常用解码策略

贪心解码：
- 每步选概率最高的词。
- 简单高效，但输出单一。
束搜索：
- 近似全量解码，保留多个候选序列。
- 用于高质量生成（如翻译）。
采样解码：
- Top-k采样：从前k个高概率词中随机选。
- Top-p采样：从累计概率达p的词中选。
- 增强多样性，常见于对话模型。
自回归生成：
- 逐步生成，每步依赖前文。
- 是增量解码的基础框架。

为什么偏向增量解码？

实时性：对话中需快速响应。
效率：避免指数级计算。
架构：自回归模型逐词生成。

全量解码的应用

在翻译、摘要等任务中，束搜索常用于追求高质量输出。
但真正的全量解码（遍历所有序列）因计算成本过高，几乎不用。

实际例子

ChatGPT：用Top-p采样+自回归，生成自然多样的回复。
Grok：类似增量解码，逐词输出，追求实时性。

第六部分：常见疑问解答

Q1：输入不是一次性给的吗？为什么解码不是一次性完成？

答：
- 输入确实是一次性给模型的，模型会理解完整上下文。
- 但解码是生成输出的过程，自回归模型需要逐词预测，因为：
  1. 语言的序列性要求逐步构建。
  2. 每步预测依赖前文输出。
  3. 一次性生成所有词的组合计算量太大。

Q2：大语言模型用哪种解码？

答：
- 主要用增量解码（自回归+采样），适合实时对话。
- 全量解码（如束搜索）用于特定任务，但多为近似形式。

第七部分：总结

全量解码：追求全局最优，计算成本高，适合高质量任务。
增量解码：高效实时，适合对话和流式应用。
大语言模型：以增量解码为主（如采样），灵活搭配策略，平衡质量与效率。

通过理解这两种解码方式，你可以更好地把握大语言模型的工作机制，并根据需求选择合适的策略。

可观测与协议 on 扎塔-Zata

Agent 决策审计落地：写入点、复核器与门禁降级判据

一、先说不建什么

二、最小数据契约：一张只允许 INSERT 的表

三、写入点：审计不改变控制流，只挂在三个钩子上

四、复核器：规则在前，模型在后

五、降级判据比记录格式更重要

六、审计存储自身会坏：读取端怎么认账

七、我的判断

速查：落地顺序与每步的完成判据

延伸阅读

Session、Thread、Run：一条消息为什么是一个 Run

一、三个名字，三种事实

二、一条消息，就是一个 Run

三、为什么不能"一个 Session 一个 Run ID"

四、Run 的状态机：把"事实"和"活性"分开

五、委派那天，这个空字段被填满了

几点收获

Agent 决策审计：它与 Tracing 的关系

一、先把四种记录分清

二、决策审计是 tracing 的一部分吗？

三、一条可复核的决策记录长什么样

四、它怎样帮助替代固定门禁

一个常见失败：结果是绿的，判断仍然错

五、从最小实现开始，不必先建平台

速查：遇到一个问题该看哪里

Agent Tracing 基础：Trace、Span 与 OpenTelemetry 埋点

一、Trace 与 Span：一次 Agent Run 就是一棵树

二、属性与事件：span 上该记什么

三、Traces、Metrics、Logs：三根柱子各自回答一个问题

四、OpenTelemetry 埋点：从 API 到 span 树

五、上下文传递：让父子关系不断链

5.1 进程内：异步任务与线程池

5.2 跨进程：W3C Trace Context

六、三个最常见的坑

七、速查表

几点收获

Agent 埋点接 ARMS：上报返回 success，控制台却是空的

一、gen_ai.* 到底是什么

二、span 树怎么设计

三、一个 200 success 的假象

四、三个坑

坑一：地域

坑二：入口

坑三：配置写法

五、对话里带附件怎么记

六、数据怎么拿出来给 AI 看

总结

AG-UI：当 Agent 学会了和前端说话

先看仓库现状（2026-09-10）

三层协议的最后一块

仓库解剖：一个协议 monorepo 长什么样

事件流是唯一事实源

能力声明：协议里藏着一份"agent 名片"

输入：全量历史的无状态哲学

从 SDK 源码里读出的工程细节

运行时管线：一次 run 的完整解剖

① Middleware：洋葱模型的拦截器

② 三个值得抄的中间件设计

③ verifyEvents：1052 行的事件文法状态机

④ transformChunks：快捷事件的双向门

⑤ apply 与 subscribers：归约器和观察者

怎么读 AG-UI 的源码：一份导航

生态：谁在用它

和有状态 Runtime 的张力

Agent Run 流式协议：事件溯源、SSE 投影与断线恢复

一、三层结构

Runner 端口层

Canonical 层

二、SSE wire format

三、为什么先落库，再投影

断线恢复变成查询问题

Runtime 崩溃不丢执行事实

多 Runtime 共享同一套前端协议

工具调用能稳定配对

四、当前边界和改进方向

总结

全量解码与增量解码：原理、区别以及应用

引言

第一部分：什么是解码？

一、`gen_ai.*` 到底是什么