H1 · 如何观察、追踪和诊断系统运行？ - Observability
所属知识库：Agent 全栈技术地图
所属领域：03 · Agent System
所属章节：03 · 如何让 Agent System 稳定、安全、可控地运行？ - Engineering & Governance
文档类型：工程技术专题研究、架构设计与验证指南
版本：v1.1
更新日期：2026 年 10 月 28 日
核心问题：如何建立贯穿 Agent 任务、模型调用、工具执行、跨 Agent 协作、人工审批与产物交付的可观测性体系，准确关联系统行为与业务结果，定位故障和质量退化，同时控制遥测开销、敏感数据暴露和证据失真风险？
专题导读
本篇属 Engineering & Governance。Agent System 的故障不总是表现为进程崩溃。系统可能返回 HTTP 200，却给出错误结论；某个 Agent 可能持续调用工具却没有推进任务；一次重试可能导致重复发布；多 Agent 协作可能在交接后丢失证据；用户看到“生成中”，而后端任务早已等待人工审批。传统基础设施监控能够揭示资源消耗和服务故障，但不足以解释这些行为。
Observability（可观测性）是通过系统产生的遥测数据及其关联关系，推断内部运行状态、解释行为、发现异常并辅助诊断的工程能力。 对 Agent System 而言，关键不在于“记录尽可能多的模型思考内容”，而在于构建可靠的任务 - 运行 - 步骤 - 模型 - 工具 - 协作 - 产物因果链，明确每个动作的主体、输入边界、执行结果、成本、耗时和状态变化。
本文承接 Technical Architecture 的 L1 - L6，并以“技术研究报告 Studio”为持续案例。重点研究日志、指标、分布式追踪、业务事件、语义约定、关联标识、采样与隐私、故障诊断和验收方法。H1 负责提供可解释的运行证据；H3 负责评价质量，H7 负责恢复可靠性，H9 负责数据治理，H11 负责运行响应，H12 负责制定治理规则。看得见不等于评得准，也不等于控制得住。
一、定义、目标与边界
1.1 可观测性究竟要回答什么
在真实任务中，工程师至少需要回答六组问题。
- 任务在哪里：任务处于 queued、running、waiting_approval、completed、failed 还是 canceled？最后一次状态转移发生在何时？
- 发生了什么：哪个 Agent 执行了哪个 Step，使用了哪个模型，提出了什么工具动作，执行层是否真的完成了动作？
- 为什么变慢：等待队列、模型推理、工具响应、人工审批、数据库锁或外部服务重试各占多少时间？
- 为什么失败：是供应商限流、模型结构化输出不合法、工具权限不足、状态版本冲突、超时，还是任务逻辑本身没有收敛？
- 结果是否可信：报告由哪些来源和中间产物构成，审查结论关联哪一次运行和哪个版本？这需要结合 H3 的质量评估和 H9 的来源治理。
- 代价与影响：单任务 Token、费用、调用次数、重试次数、错误率、队列积压，以及影响哪些用户和工作流？
1.2 可观测性与相邻概念
| 概念 | 主要目的 | 不能替代什么 |
|---|---|---|
| Monitoring 监控 | 发现已定义的异常 | 未知故障探索 |
| Logging 日志 | 记录离散事件与上下文 | 完整因果关系 |
| Metrics 指标 | 聚合趋势、阈值与 SLO | 单次任务细节 |
| Tracing 追踪 | 关联跨组件执行路径 | 业务事实账本 |
| Audit 审计 | 记录责任与受控操作 | 任意调试日志 |
| Evaluation 评估 | 判断结果质量与合规 | 基础运行追踪 |
| Observability 可观测性 | 综合解释内部行为 | 自动修复与授权 |
可观测性是利用多类信号完成诊断的能力，不等于购买一套 APM 产品。日志和 Trace 可能被采样、延迟写入、丢弃或脱敏，因此不能默认其具有完整的审计证明力。关键授权和外部副作用应由业务事务、审计账本或权威状态记录承载，遥测负责辅助解释。
1.3 六层技术架构中的观测点
| 技术层 | 应观测的关键对象 |
|---|---|
| L1 Infrastructure | CPU、内存、容器、网络、磁盘 |
| L2 Platform Services | 队列、数据库、缓存、对象存储 |
| L3 Model Services | 模型请求、限流、Token、费用 |
| L4 Agent Engine | Run、Step、工具决策与执行 |
| L5 Orchestration | 任务图、依赖、交接、协作 |
| L6 Application | 用户请求、审批、状态、交付 |
H1 贯穿上述各层，但不要求每层部署独立的可观测性平台。小型系统可以采用统一采集器与少量后端；规模增长后再按成本、权限和数据保留要求拆分。
二、观测对象：建立统一的运行语义
2.1 区分 Task、Run、Step、Attempt、Action
建议首先定义业务实体，而不是直接从某个 SDK 的 Span 名称开始。
- Task：用户或系统提交的业务目标，例如“研究某个行业并生成报告”。一个 Task 可有多个 Run。
- Run：某次具体执行实例，具有独立生命周期、配置快照和终态。
- Step：Run 内具有可识别输入、输出和状态的逻辑工作单元，例如检索、分析或审查。
- Attempt：对同一逻辑 Step 或外部操作的一次具体尝试；重试必须产生新的 attempt_id。
- Action：工具调用、发布、写库、发送通知等实际动作；模型生成的工具调用建议与真实执行结果是两个事件。
- Artifact：报告、表格、证据集合等有版本的交付对象。
这些名称属于本文推荐的系统级概念模型，不是所有框架都采用的统一术语。框架内部的 run、span 或 thread 不应未经映射直接当作业务主键。
2.2 推荐关联标识
| 标识 | 作用 | 注意事项 |
|---|---|---|
| task_id | 关联业务目标 | 不应包含用户个人信息 |
| run_id | 标识一次运行 | 恢复时明确是否沿用 |
| step_id | 标识逻辑步骤 | 与 attempt_id 区分 |
| attempt_id | 区分重试尝试 | 避免重试覆盖原记录 |
| trace_id | 关联分布式 Trace | 不替代业务主键 |
| span_id | 标识单个追踪片段 | 具有父子或链接关系 |
| agent_id | 标识 Agent 角色或实例 | 另记版本和配置 |
| tool_call_id | 关联工具提议与执行 | 不等于幂等键 |
| artifact_id | 关联产物及版本 | 保留来源和校验摘要 |
| tenant_id | 隔离租户与聚合指标 | 避免高基数指标标签 |
关键原则：业务 ID 贯穿持久化记录，Trace ID 贯穿遥测上下文。 Trace 可能过期或被采样，业务 ID 不应依赖 Trace 后端才能查询。对外展示的 Task ID 也不应被当作访问授权凭据。
2.3 统一事件信封
为状态变更与关键动作设计稳定的事件信封，可避免不同组件各自拼接自由文本。一个参考结构如下（示例 JSON，不代表某项标准）：
{
"schema_version": "1.0",
"event_id": "evt_01",
"event_type": "agent.step.completed",
"occurred_at": "2026-10-28T12:00:00Z",
"emitted_at": "2026-10-28T12:00:01Z",
"task_id": "task_01",
"run_id": "run_02",
"step_id": "step_review",
"attempt_id": "attempt_01",
"trace_id": "00000000000000000000000000000001",
"agent_id": "reviewer",
"tenant_id": "tenant_01",
"status": "succeeded",
"duration_ms": 824,
"artifact_refs": ["artifact_04:v2"],
"error_code": null
}occurred_at 与 emitted_at 分开有助于识别异步上报延迟；若需要严格的因果或顺序判断，应补充单一实体内的单调序列号或状态版本，不能仅凭不同主机的时间戳排序。event_id 可辅助去重，但不意味着消息只投递一次。
2.4 事件分类与生命周期
推荐事件至少覆盖 task.accepted、run.started、step.started、model.request.started、model.request.completed、tool.proposed、tool.authorized、tool.execution.started、tool.execution.completed、handoff.created、approval.requested、approval.resolved、artifact.published、run.completed、run.failed。事件类型需要有稳定定义、版本策略与字段字典，避免同一个 completed 同时表示“模型返回”“工具执行完毕”和“业务验收通过”。
一个重要区别是：事件流用于解释过程，权威状态用于判断现在是什么。 当事件到达顺序颠倒、丢失或重放时，应通过权威状态表及版本号核对，不要仅凭最新收到的事件更新业务终态。
三、四类核心信号及其协同
3.1 结构化日志：记录可定位的离散事实
日志适合描述异常、策略决策、状态转移和边界检查。建议采用 JSON 等结构化格式，至少包含时间、严重级别、服务、环境、部署版本、关联 ID、事件名、结果码、错误分类和安全的数据摘要。错误日志应记录可行动的信息，例如 provider_rate_limited、tool_permission_denied、checkpoint_conflict，而不是只有“Agent failed”。
日志不应默认记录完整 Prompt、模型输出、工具响应、网页内容、访问令牌、Cookie 或个人数据。诊断需要内容时，优先记录大小、哈希、版本、受控引用及经过批准的短摘要；原文进入单独的受控证据存储，并设置访问、保留与删除策略。
3.2 指标：判断趋势与服务目标
建议从用户可感知的业务指标出发，再下钻到组件指标。
| 指标类别 | 示例 | 诊断用途 |
|---|---|---|
| 任务结果 | 成功率、失败率、取消率 | 观察总体可用性 |
| 时延 | 端到端 P50/P95/P99 | 判断用户等待 |
| 排队 | 队列深度、等待时间 | 识别容量瓶颈 |
| 模型 | 请求延迟、错误率、Token | 识别供应商与成本问题 |
| 工具 | 调用延迟、超时、拒绝率 | 识别外部依赖问题 |
| 编排 | 阻塞节点、返工次数 | 识别协作低效 |
| 审批 | 待审数量、等待时长 | 识别人工瓶颈 |
| 质量 | 评估通过率、证据覆盖率 | 需结合 H3 解释 |
成功率的分母必须定义清楚：是否排除用户主动取消、仍在执行的长任务、因审批而等待的任务？对于异步任务，按“提交时段”与“完成时段”统计可能得出不同结果。P95 延迟也应区分总历时、机器执行时长、队列等待、人工等待，否则会错误归因。
指标标签应限制基数。model_name、service、status、environment 可以作为候选标签；task_id、user_id、prompt、trace_id 通常不应直接进入时序指标标签，否则存储成本和查询性能会迅速恶化。单任务定位应通过 Trace、日志或事件索引完成。
3.3 分布式 Trace：重建执行路径
Trace 由多个 Span 构成，Span 记录操作名称、开始与结束时间、属性、状态和上下文关系。典型路径为：
HTTP POST /tasks
└── task.accept
└── run.execute
├── agent.research
│ ├── model.generate
│ ├── tool.search
│ └── tool.fetch
├── agent.analyze
│ └── model.generate
├── agent.review
│ └── model.generate
└── artifact.publish这是示意逻辑路径。跨队列和长时间暂停的工作流不一定适合维持一个持续数小时的父 Span；可将每次 Worker 执行作为独立 Trace，利用 task_id、run_id、Span Links 或业务事件建立关联。对跨 Agent Handoff，必须明确是同步调用、异步委派还是仅传递数据，不能把所有协作都画成严格的父子调用链。
Span 应包含可诊断的低敏属性，例如 agent.role、step.kind、model.provider、model.name、tool.name、retry.attempt、operation.outcome。字段命名应尽量遵循所选遥测标准的当前版本，并将业务自定义字段放在清晰的命名空间，避免与标准语义冲突。
3.4 业务事件与审计记录：补足 Trace 的盲区
Trace 是诊断工具，不宜作为审批和副作用的唯一事实来源。关键审批决策、权限检查、外部发布、资金或权限变更等，应有不可随意篡改、具备访问控制与保留策略的业务/审计记录。这里的“不可随意篡改”需通过存储权限、追加写入、签名或哈希链等机制实现，不能因为采用了日志服务就自动宣称满足审计要求。
例如工具执行流程至少区分 tool.proposed、tool.authorized、tool.execution.started、tool.execution.succeeded / failed。只有最终确认的执行记录可以支持“已执行”的判断；模型生成一个函数调用 JSON 不能证明真实外部副作用发生。
四、模型、工具与 Agent 的专属可观测性
4.1 模型调用需要记录哪些事实
推荐记录供应商、模型标识与版本、路由策略版本、请求类型、响应状态、供应商请求 ID（若可用）、首 Token 延迟、总耗时、输入与输出 Token、缓存 Token（若供应商提供）、重试次数、估算成本与结算成本的区别。流式调用应区分连接建立、首事件、首可见内容、完整响应结束，否则“首 Token 延迟”定义会随实现变化。
Token 使用量可能在流式响应结束后才返回，供应商口径也可能不同；对未返回用量的失败请求，标记为 unknown 或 estimated，不要把零误当作未计费。模型价格、缓存折扣和货币汇率应保留计算时所用的价格版本。
不建议默认存储模型隐藏推理内容或完整对话原文。 一方面部分接口并不提供此类内容；另一方面存在隐私、合同、成本和安全风险。可以记录输入输出的结构化摘要、大小、内容哈希、工具调用类型及受控引用，必要时采用严格授权的短期采样。
4.2 工具执行的双重边界
工具链需要分别观察“模型提出调用”与“可信执行层实际执行”。建议记录工具名称、参数模式版本、参数校验结果、授权策略版本、审批引用、幂等键、外部请求 ID、耗时、重试和副作用确认状态。工具失败应分类为：参数错误、授权拒绝、超时、依赖失败、冲突、结果校验失败和未知结果。
特别注意超时后的未知结果：客户端没有收到响应，不代表外部服务没有完成操作。诊断界面应显示 outcome_unknown 并引导按幂等键或外部交易 ID 查询，而不是直接提示“安全重试”。
4.3 Agent 决策与进展
Agent Engine 可报告每个 Step 的目标、工具调用次数、上下文大小、执行预算消耗、终止原因与状态版本。循环检测不应只依赖“调用次数大于阈值”，还可观测连续相同工具参数、没有新增证据、产物版本未变化、重复审查意见等信号。这些属于启发式异常检测，不能未经验证就当作任务无进展的确定性证明。
4.4 多 Agent 协作
跨 Agent 任务应保留委派关系：delegator_agent_id、delegate_agent_id、handoff_id、parent_task_id、dependency_ids、输入产物版本和返回产物版本。对 Fan-out/Fan-in，要能回答哪些分支已完成、哪些仍等待、聚合节点使用了哪些版本，以及返工后是否混用了旧结果。对异步消息，传播 W3C Trace Context 等上下文时仍应保留业务相关 ID；跨不可信边界时不得盲目信任外部传入的 trace 属性或租户标识。
五、端到端架构：从产生遥测到定位问题
5.1 推荐参考架构
用户 / 外部 API
│
Application ── Agent Engine ── Orchestrator ── Workers
│ │ │ │
└─────────── Instrumentation / SDK ─────────┘
│
OTel Collector / Gateway
┌──────┼───────────┐
│ │ │
Traces Metrics Logs
│ │ │
└──────┼───────────┘
│
诊断查询 / Dashboard / Alert
│
task_id / run_id 关联
│
权威任务状态库 + 业务事件 + 审计记录OpenTelemetry 可作为遥测数据的采集与语义标准化基础，但它不负责定义全部业务事件、存储权威任务状态或执行授权。Collector 的处理器可进行批处理、过滤、属性删除与导出，但采集器本身也可能过载或丢失数据，因此必须监测 Collector 的队列、丢弃和导出错误。
5.2 上下文传播
同步 HTTP/gRPC 调用可传播标准 Trace Context；异步队列需将传播上下文写入消息元数据，Worker 读取后创建新 Span 或 Trace，并结合业务关联键。跨服务应统一采样策略、时钟同步、服务名和环境标识。对长时间等待人工审批的任务，建议在暂停与恢复两段执行之间建立业务关联，而非人为维持超长 Span。
5.3 采样策略
全量记录所有模型输入输出通常成本高且风险大。可组合：低成本指标全量聚合、常规 Trace 头部采样、错误与高延迟请求优先保留、关键业务事件持久化、少量经过授权的内容样本。尾部采样能依据执行结果选择 Trace，但需要额外的缓存和资源；跨多个采集器的尾部采样还涉及路由一致性。采样后的“未发现异常”不等于异常不存在。
5.4 存储、访问与保留
建议将指标、Trace、普通日志、业务事件、审计记录和敏感证据存储区分管理：它们具有不同的查询模式、保留周期、权限与删除义务。不要将日志脱敏作为唯一保护措施；还需要传输加密、静态加密、租户隔离、角色授权、查询审计和密钥轮换。具体保留时长应由法律、合同、风险与成本共同确定，而不是套用统一天数。
六、可操作的诊断方法
6.1 先定位业务症状，再定位技术瓶颈
推荐诊断顺序为：用户症状 → Task/Run → 最后权威状态 → 关键事件时间线 → Trace/日志 → 依赖指标 → 复现与修复验证。先确认用户所说的“卡住”究竟是队列等待、工具超时、人工审批、任务失败还是前端事件订阅断线，再检查底层 CPU 或数据库。
6.2 案例 A：任务一直显示“生成中”
假设用户提交研究任务后界面 20 分钟没有更新。应用层 Task 状态为 running，但事件库最后一条为 approval.requested；Run 实际处于 waiting_approval。这说明主要问题可能是应用状态投影或事件消费，而不是模型推理速度。应核对审批记录、事件消费游标、状态投影版本与前端断线重连逻辑。修复后需通过集成测试验证“审批等待”能正确显示，并保证权限校验不被前端状态绕过。
6.3 案例 B：工具重复执行
某工具 Span 出现三次调用，不能直接推断发生三次外部副作用。首先检查 tool_call_id、attempt_id、幂等键、外部请求 ID 和服务端确认结果。若第一轮超时但外部成功，第二轮再次执行且未使用幂等保护，则可能出现重复发布。遥测负责还原事实；防重复必须在 L4 工具执行、L2 持久化及 H7 可靠性机制中实现。
6.4 案例 C：多 Agent 报告质量下降
总延迟和错误率正常，但用户反馈报告引用错误。H1 可以定位审查 Agent 使用了哪个证据版本、引用链接是否来自哪次检索、最终报告是否混入过期产物；但“引用是否真实支持结论”需要 H3 的评估标准和人工复核。技术成功率与内容质量必须分开测量。
6.5 案例 D：成本突然升高
按模型、任务类型、部署版本聚合 Token 与重试次数，定位成本上升是请求量增加、路由变化、上下文膨胀、重复工具循环，还是价格表更新。估算账单与供应商最终结算可能存在差异，必须明确计量口径。对于单个高成本任务，再使用 task_id 下钻到模型请求和 Agent Step。
七、指标体系、SLO 与告警设计
7.1 从用户体验反推 SLI
可考虑定义任务可用性、完成时延、关键状态更新延迟、工具成功率、审批可达性和产物可获取性。示例：任务成功率 = 指定时间窗口内满足终态定义的成功任务数 / 符合统计条件的已结束任务数。这是候选定义，实际需要明确用户取消、外部依赖不可用、等待人工审批和超时任务的处理规则。
质量类指标（事实准确性、引用有效性、审查一致性）应与 H3 的评估集、标注规则和统计方法结合，不能仅依靠遥测事件中的 success=true。
7.2 告警优先级
高优先级告警应指向明确的用户影响或风险，例如任务完成率持续下降、关键工具副作用状态未知、跨租户授权异常、队列积压导致服务目标失效。中优先级包括模型供应商错误率上升、某版本成本显著偏离、Collector 丢弃遥测。单次模型请求失败通常不应直接触发值班告警；可先通过重试与聚合阈值判断。
7.3 避免无效告警
告警必须写清：症状、影响范围、关联 Dashboard、最近部署变更、诊断步骤、处理责任和恢复判定。不要把每条异常日志都配置成独立告警；也不要仅依靠平均延迟掩盖尾部请求的严重退化。对低样本量指标应考虑统计波动和窗口大小。
八、实现路径：从最小可用到生产级
8.1 阶段一：最小可用观测
对单体或小型 Studio，先建立稳定的 task_id/run_id/step_id，实现结构化日志、Run 状态表、关键业务事件、模型/工具耗时与 Token 记录、基础 Dashboard。确保能根据一个 Task ID 重建关键时间线。此阶段不必急于引入复杂的多后端链路追踪平台。
8.2 阶段二：跨服务关联
当系统引入队列、独立 Worker、多模型供应商和多个 Agent 时，加入 OpenTelemetry Trace、跨进程上下文传播、标准错误分类、统一模型与工具埋点、采样和 Collector 监控。将每次部署的代码版本、Prompt 版本、Agent 配置版本与路由策略版本关联到 Run。
8.3 阶段三：治理与持续优化
引入基于用户体验的 SLO、成本归因、审计与遥测隔离、敏感字段策略、异常模式分析、发布前回归观测、事故复盘和容量规划。将 H3 评估结果、H7 故障恢复、H9 数据治理、H11 运维流程与 H12 策略执行接入同一诊断工作流，但保持各自的权威数据来源。
九、参考数据契约与实现示例
以下 Python 片段展示一个不依赖第三方库的结构化事件封装示例。它不是完整的遥测 SDK，也不提供持久化、跨进程传播、授权、审计不可篡改或 OpenTelemetry 协议兼容。示例不记录 Prompt 或工具参数原文。配套文件 H1-Agent-System-Observability-v1.1-demo.py，Python 3 标准库（含 3.9）。运行：python3 H1-Agent-System-Observability-v1.1-demo.py。
from __future__ import annotations
from dataclasses import dataclass, asdict
from datetime import datetime, timezone
import json
import uuid
@dataclass(frozen=True)
class Event:
event_id: str
event_type: str
occurred_at: str
task_id: str
run_id: str
step_id: str | None
attempt_id: str | None
status: str
def emit_event(event_type, task_id, run_id, status,
step_id=None, attempt_id=None):
event = Event(
event_id=str(uuid.uuid4()),
event_type=event_type,
occurred_at=datetime.now(timezone.utc).isoformat(),
task_id=task_id,
run_id=run_id,
step_id=step_id,
attempt_id=attempt_id,
status=status,
)
print(json.dumps(asdict(event), ensure_ascii=False))
return event
if __name__ == "__main__":
result = emit_event(
"agent.step.completed", "task_1", "run_1",
"succeeded", "step_review", "attempt_1"
)
assert result.task_id == "task_1"
assert result.event_type == "agent.step.completed"本地执行通过：两条断言成立（task_id 为 task_1，event_type 为 agent.step.completed），并打印一条不含 Prompt 的 JSON 事件。event_id 与 UTC 时间每次运行不同。
在生产环境中，事件写入应使用可靠传输与持久化策略。对于必须与业务状态同时提交的关键事件，可考虑数据库事务 Outbox；日志输出成功不意味着事件已被下游消费。上述代码是教学参考，具体运行验证情况见附录 B。
十、测试、验收与反例
10.1 最小验收矩阵
| 测试情境 | 预期可观测证据 |
|---|---|
| 正常任务完成 | 完整任务时间线与产物引用 |
| 模型限流重试 | 错误分类、尝试次数与最终状态 |
| 工具超时 | 未知结果与外部请求关联 |
| Agent 交接 | 委派双方与输入输出版本 |
| Worker 崩溃恢复 | 旧尝试、新尝试与状态版本 |
| 审批等待 | 等待原因与审批关联 ID |
| 前端断线重连 | 状态与事件游标恢复记录 |
| 采集器不可用 | 遥测丢失指标与降级策略 |
| 敏感输入 | 日志不包含原文或密钥 |
| 跨租户查询 | 无权读取被拒绝并可审计 |
10.2 验收标准
建议要求：给定 task_id 能查到权威终态、关键事件、相关 Trace 与产物版本；能够将重试与实际副作用区分；能解释一次失败任务的主要耗时与错误类别；能在采样或遥测丢失时明确显示证据不完整；敏感字段与跨租户访问测试通过。具体数值目标（例如 P95、数据保留天数和采样率）应由系统负载、风险与业务要求确定，不应在研究阶段虚构统一行业阈值。
10.3 常见反模式
只记录 Prompt 和模型输出：信息量大但缺少执行关系，且增加隐私风险。只有 HTTP 成功率：无法反映 Agent 任务质量和异步任务状态。把 Trace 当数据库：采样和保留策略可能导致关键事实丢失。用用户 ID 做指标标签：产生高基数和隐私问题。所有异常都报警：噪声淹没真实事故。日志显示“执行成功”就认定副作用成功：忽略外部服务确认与幂等核对。在前端拼接完整时间线：容易因断线、乱序与事件丢失形成错误状态。
十一、研究结论
- Agent System 的观测单位应从服务请求扩展为业务 Task、Run、Step、Attempt、Action 与 Artifact。 只有业务语义与基础遥测关联，才能解释复杂任务为什么失败或停滞。
- 日志、指标、Trace、业务事件与审计记录各有职责。 Trace 提供诊断路径，权威状态和关键业务记录负责确认事实；任何单一信号都不应承担全部责任。
- 跨 Agent、跨队列、跨审批的任务需要持久化关联 ID 和版本关系。 分布式 Trace 不能替代长期任务标识，超长等待也不必维持单个持续 Span。
- 模型与工具必须区分“提出动作”“授权动作”“执行动作”“确认副作用”。 这是正确定位故障、避免误报和处理未知结果的基础。
- 可观测性必须具备数据最小化、租户隔离、采样透明性和成本约束。 更完整的原始内容采集并不必然提高诊断质量。
- 从用户可感知的任务成功、时延与产物质量出发定义 SLI。 模型 API 成功、Agent Run 结束和业务目标达成是不同层面的成功。
- H1 是其他治理能力的证据基础，但不代替它们。 质量判断交给 H3，恢复策略交给 H7，数据生命周期交给 H9，运行响应交给 H11，政策执行交给 H12。
附录 A：参考文献与原始资料
以下为可供后续核验的官方一手资料。标准、SDK 与语义约定可能持续变化；本篇的业务事件模型、字段名称和验收建议属于研究性设计，不应误认为这些资料规定的统一接口。
- [R1] OpenTelemetry Documentation - Concepts / Signals：opentelemetry.io/docs/concepts/signals 。用于区分 Traces、Metrics、Logs 等遥测信号。
- [R2] OpenTelemetry - Semantic Conventions for Generative AI：opentelemetry.io/docs/specs/semconv/gen-ai 。用于理解 GenAI 操作、模型和相关遥测语义；采用时应核对当前稳定性与版本。
- [R3] OpenTelemetry - Context Propagation：opentelemetry.io/docs/concepts/context-propagation 。用于理解跨服务上下文关联。
- [R4] OpenTelemetry Collector Documentation：opentelemetry.io/docs/collector 。用于研究接收、处理和导出遥测的架构。
- [R5] W3C Trace Context Recommendation：www.w3.org/TR/trace-context 。用于跨服务 Trace Context 标准。
- [R6] OpenTelemetry - Sampling：opentelemetry.io/docs/concepts/sampling 。用于研究头部采样与采样边界。
- [R7] Google SRE Book - Service Level Objectives：sre.google/sre-book/service-level-objectives 。用于研究 SLI、SLO 与用户体验的关系。
- [R8] Google SRE Workbook - Alerting on SLOs：sre.google/workbook/alerting-on-slos 。用于研究告警与服务目标的关系。
- [R9] OpenTelemetry - Baggage：opentelemetry.io/docs/concepts/signals/baggage 。用于理解跨进程传播业务上下文时的安全与数据泄露风险。
- [R10] OpenTelemetry - Trace API Specification：opentelemetry.io/docs/specs/otel/trace/api 。用于研究 Span、上下文与关联机制。
附录 B：研究证据、验证声明与适用边界
B.1 证据分类
- 标准与官方文档支持的通用机制：Trace、Span、Context Propagation、Collector、遥测信号、采样、SLI/SLO 等，参见 [R1] - [R10]。
- 本篇综合提出的工程设计建议：Task/Run/Step/Attempt/Action 统一语义、事件信封、业务事件命名、最小验收矩阵、三阶段建设路线。它们是可实施的参考设计，不是某个框架或标准的强制规范。
- 案例推演：技术研究报告 Studio 的故障案例属于假设性诊断情境，不代表已观测到真实生产事故。
B.2 验证声明
本文提供静态结构、参考代码和可执行的测试思路；未搭建实际 OpenTelemetry Collector、Trace 后端、模型供应商、分布式 Worker 或生产级 Agent Studio 进行端到端验证。参考代码仅说明结构化事件封装，不验证持久化可靠性、跨服务传播、审计完整性或数据脱敏策略。具体代码是否执行，以交付说明中的实际执行记录为准。
B.3 适用范围与限制
本文适用于包含模型调用、工具执行、任务状态或多 Agent 协作的 Agent System；小型原型可按风险与规模裁剪。不同厂商的 GenAI 遥测字段、Token 计量、缓存口径、模型响应内容和数据保留规则存在差异，实际接入必须逐一验证。安全敏感、高监管或高风险场景还需额外的合规、隐私与审计评审，不能仅凭可观测性建设宣布满足要求。
B.4 与后续专题的衔接
下一篇 「H2 · 如何保障 Agent System 的安全？ - Security」 将在本篇信任边界与证据模型基础上，系统研究威胁建模、身份认证、最小权限、提示注入、工具执行隔离、凭据管理、供应链风险和跨租户安全。