F8 · 用户如何查看 Agent 的运行状态与结果？ - Agent Monitoring
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 可观测性与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何向业务用户、构建者、开发者和管理员提供可理解、可追溯、可诊断的运行状态、结果质量、资源消耗和异常反馈，并支持基于证据的干预与持续改进？
专题导读
本篇属 Product Architecture。F6 研究用户如何启动与控制单次 Run，F7 研究多 Agent 团队的协作操作。F8 将视角扩展为跨 Agent、跨工作流、跨项目、跨时间的运行可见性与诊断体验。本篇的 Monitoring 是产品能力，底层依赖 P1 Control Plane、P2 Execution Plane、P6 Workflow Management、P10 Data & Assets、P11 Multi-tenancy、P12 Governance，以及 Agent System 工程可观测性能力。
本文严格区分三类信息：执行状态（任务是否推进）、运行健康（系统是否正常）、结果质量（业务结果是否可信）。三者有关联但不等价。以下信息架构、API、数据表和阈值均为参考设计，未进行真实用户验证或生产测试。
研究结论
- 监控产品至少应提供总览、运行列表、Run 详情、Trace 诊断、质量结果、成本用量、告警事件七类视图，并按角色逐步披露。
Run.status=SUCCEEDED仅表示执行契约完成，不表示事实正确、审核通过或交付成功；应分别呈现执行状态、评估状态、审核状态和交付状态。- 事件、日志、指标、追踪和审计是不同的数据产品：事件用于还原业务状态，Trace 用于关联执行路径，Metrics 用于聚合趋势，Logs 用于诊断，Audit 用于责任证据。
- 用户应从异常概览逐层下钻至 Workflow Run、Step Run、Attempt、模型/工具调用与关联产物，同时始终保留租户和项目权限边界。
- 成本和 Token 数量是估计或结算数据，应显示口径、币种、价格版本和数据新鲜度；模型使用量并不自动等于账单金额。
- 告警必须有明确的责任人、阈值口径、抑制策略和恢复条件；避免对每个 Agent 自然语言错误都触发噪声告警。
- Studio MVP 应先完成运行列表、阶段状态、失败定位、Trace 摘要、产物链接、基础成本和人工待办，再扩展统计分析、复杂告警与跨项目质量趋势。
01 · 定义、边界与核心术语
1.1 Agent Monitoring 的产品定义
Agent Monitoring 指用户通过平台持续查看 Agent 与 Workflow 的运行过程、状态、资源消耗、异常、质量评估和历史结果，并能定位问题、获得操作建议和执行权限内的下一步动作。它不是单纯展示服务器 CPU 或一条聊天记录。
| 概念 | 核心问题 | 产品示例 |
|---|---|---|
| Monitoring | 现在发生了什么？ | 运行列表、阶段进度、告警 |
| Observability | 为什么发生？ | Trace、Logs、Metrics 关联诊断 |
| Evaluation | 结果是否满足标准？ | 引用有效性、结构化输出通过率 |
| Audit | 谁在何时做了什么？ | 版本变更、审批、权限决策 |
| Analytics | 长期趋势如何？ | 成功率、成本趋势、瓶颈分析 |
1.2 与相邻产品功能的职责划分
- F6 Agent Execution：聚焦当前 Run 的操作和控制；F8 提供跨运行的发现、追踪与诊断。F8 可以深链到 F6 的运行工作台，但不重复实现运行控制。
- F7 Agent Collaboration：聚焦团队、分工、交接与协作操作；F8 聚焦这些行为的可观察证据和跨团队分析。
- F3 Development & Testing：聚焦开发预览、测试集与回归评估；F8 聚焦正式运行期间的观测及线上质量信号，必要时将失败样本送回 F3。
- F10 Artifact & Delivery：负责成果管理与交付；F8 展示产物引用、审核与交付状态。
- P12 Platform Governance：负责策略与配额执行；F8 展示配额占用、拒绝原因和审计可见结果。
1.3 必须分离的四种状态
execution_status（QUEUED/RUNNING/WAITING/SUCCEEDED/FAILED/CANCELLED）、evaluation_status（NOT_EVALUATED/PASSED/FAILED/INCONCLUSIVE）、review_status（NOT_REQUIRED/PENDING/APPROVED/REJECTED）、delivery_status（NOT_READY/READY/DELIVERED/FAILED）分别来自不同的状态源。不能用一个绿色对勾替代全部。状态名称为本篇建议，具体系统应定义权威枚举和合法转换。
02 · 用户角色与任务场景
| 用户角色 | 主要任务 | 默认视图 | 允许的深入操作 |
|---|---|---|---|
| 业务用户 | 了解进度、确认成果 | 我的运行、待办、结果 | 查看可公开的阶段摘要与产物 |
| 项目负责人 | 识别延期、质量风险 | 项目看板、工作流运行 | 查看项目内错误、成本与审核记录 |
| Agent 构建者 | 定位提示词和工具问题 | Agent 版本表现、Trace | 查看经脱敏的模型/工具调用 |
| 平台运维 | 保障服务健康 | 队列、Worker、延迟、告警 | 查看基础设施指标和运行诊断 |
| 安全与审计人员 | 核查越权和高风险调用 | 安全事件、授权决策 | 按授权检索审计证据 |
用户故事应以任务而不是图表为中心。例如：项目负责人需要回答“哪些报告超过预计完成时间、卡在哪个审批节点、下一步由谁处理”；开发者需要回答“某次失败发生在模型响应、工具超时还是输出校验阶段”；业务用户只需回答“任务还在进行吗、何时需要我介入、产物在哪里”。
默认最小披露原则：普通用户不直接看到完整系统 Prompt、密钥、跨租户 Trace 或未授权的原始检索内容。
03 · 产品信息架构与导航
flowchart TB
A[Monitoring 运行监控] --> B[Overview 总览]
A --> C[Runs 运行列表]
A --> D[Alerts 告警与待办]
A --> E[Analytics 质量与用量]
C --> F[Run Detail]
F --> G[Timeline / Step Runs]
F --> H[Trace Explorer]
F --> I[Artifacts / Reviews]
H --> J[Model & Tool Spans]
E --> K[Cost / Latency / Quality]建议导航结构：工作空间侧边栏包含「运行」「告警」「分析」，项目内包含「运行」「成果」「审核」，Agent 详情包含「运行记录」「质量趋势」。相同数据由统一运行查询服务提供，避免多个页面各自定义成功率。
总览卡片：活跃 Run、等待人工处理、最近失败、运行完成量、延迟分位数、成本估计、异常趋势；必须显示时间范围、筛选范围、采样/延迟说明。运行列表：状态、任务名称、Agent/Workflow 版本、项目、发起者、开始时间、耗时、最近阶段、待办人、成本。Run 详情：状态摘要、阶段时间轴、调用链、结果和产物、错误、审批、成本与可执行操作。
移动端优先呈现状态、待办、结果；深度 Trace 适合桌面端。
04 · 核心对象与关联模型
erDiagram
TENANT ||--o{ PROJECT : owns
PROJECT ||--o{ RUN : contains
RUN ||--o{ STEP_RUN : includes
STEP_RUN ||--o{ ATTEMPT : retries
RUN ||--o{ RUN_EVENT : emits
RUN ||--o{ TRACE_SPAN : correlates
RUN ||--o{ EVALUATION_RESULT : assessed_by
RUN ||--o{ USAGE_RECORD : consumes
RUN ||--o{ ARTIFACT_REF : produces
RUN ||--o{ ALERT_INSTANCE : triggers
ALERT_RULE ||--o{ ALERT_INSTANCE : evaluates| 对象 | 最小字段 | 一致性与用途 |
|---|---|---|
| Run | id, tenant_id, project_id, definition_version_id, status, started_at, ended_at | 一次逻辑执行的权威身份 |
| Step Run | id, run_id, step_key, status | 工作流节点执行 |
| Attempt | id, step_run_id, attempt_no, status, error_code | 单次尝试，不与 Step Run 混淆 |
| Run Event | event_id, run_id, seq, type, occurred_at, payload_ref | 运行事实和状态重建依据 |
| Trace Span | trace_id, span_id, parent_span_id, run_id, attributes | 诊断调用链；可能采样 |
| Usage Record | provider, model, units, rate_version, estimated_cost | 成本归因；可能晚到 |
| Evaluation Result | criterion, score, verdict, evaluator_version, evidence_ref | 质量信号与证据 |
| Alert Instance | rule_id, dedup_key, severity, status, assignee | 异常处理生命周期 |
Run ID 是跨界面关联主键；Trace ID 可跨进程传播，但不保证每个业务事件都具备完整 Span。Run Event 负责业务事实，不能将采样 Trace 作为唯一状态数据库。
05 · 运行列表、筛选与状态语义
运行列表必须支持租户/工作空间/项目、Agent/Workflow、版本、发起者、时间范围、状态、错误类别、人工待办、成本区间筛选；默认按最新活动排序，支持游标分页与可分享的过滤条件（分享链接仍须鉴权）。
状态显示建议：QUEUED 排队中；RUNNING 运行中；WAITING_INPUT 等待用户输入；WAITING_APPROVAL 等待审批；RETRYING 重试中；SUCCEEDED 执行完成；FAILED 失败；CANCELLING 取消中；CANCELLED 已取消。若底层 Run 枚举不同，可通过只读 UI 状态映射层转换，避免为展示方便改写持久化状态。
进度条限制：LLM 推理与动态工作流的剩余工作量通常未知。除非存在确定节点总数或可信历史模型，不应展示虚假的“83%”。可显示已完成节点/已知节点、当前步骤、排队时间、最近活动、估计区间及其不确定性。
列表空状态需区分：没有运行、筛选无结果、权限不足、数据延迟、查询失败。对长时间没有心跳的 Run 显示“状态待确认”，不能直接标为失败。
06 · Run 详情与执行时间轴
Run 详情推荐分为六个区域：①执行摘要；②阶段时间轴；③任务输入与版本；④事件/调用诊断；⑤质量与产物；⑥成本、审批和审计链接。
sequenceDiagram
participant U as 用户
participant UI as Monitoring UI
participant Q as Run Query API
participant E as Event Store
participant T as Trace Store
participant A as Asset Service
U->>UI: 打开 Run 详情
UI->>Q: GET /runs/{id}
Q-->>UI: 状态、版本、权限过滤后的摘要
UI->>Q: GET /runs/{id}/events?cursor=...
Q->>E: 读取事件
E-->>UI: 事件页
UI->>Q: GET /runs/{id}/trace-summary
Q->>T: 查询关联 Span
T-->>UI: 追踪摘要/采样说明
UI->>A: 查询可访问的产物
A-->>UI: 授权资产元数据时间轴事件示例：任务创建、进入队列、Agent 启动、模型请求、工具调用、节点完成、审批请求、审批完成、重试、执行完成、评估完成、交付完成。每条事件应显示发生时间与接收时间（必要时），并允许按步骤和事件类型过滤。对于事件乱序，使用同一 Run 内的权威序列号；跨系统全序通常不可保证。
失败摘要应包含“发生阶段、错误类别、可重试性、影响范围、下一步操作”，而不是把原始堆栈直接展示给普通用户。
07 · Trace Explorer 与根因诊断
7.1 追踪树与 Span 类型
推荐 Span 类型：workflow.step、agent.invoke、llm.request、tool.call、retrieval.query、approval.wait、artifact.write。记录开始/结束时间、父子关系、状态、错误码、模型与工具标识、重试关联、消耗量。名称仅为建议，实施时与 OpenTelemetry Semantic Conventions 版本保持一致并自定义命名空间。
7.2 根因定位路径
从 Run 失败进入 Step Run，再进入 Attempt，再到具体模型/工具 Span；优先显示最早具有因果意义的失败，而不是简单取最后一条错误。常见分类包括模型超时、限流、上下文长度、工具鉴权、工具参数校验、知识资源不可用、输出 Schema 不匹配、预算不足、人工审批超时和执行器丢失租约。
7.3 内容隐私与脱敏
默认不存储完整 Prompt、模型回复、检索原文或工具响应。若业务确需采集，采用显式采集策略、数据分类、字段级脱敏、加密与保留期限；权限校验必须在查询与下载时执行。敏感字段包括 API Key、OAuth Token、个人数据、受保护文档片段及用户输入。Trace 中的内容应视为不可信数据，禁止在管理界面中未经转义渲染 HTML/Markdown。
7.4 Trace 不完整的情况
异步消息未正确传播上下文、Span 采样、外部供应商不返回细粒度事件、Worker 崩溃都可能造成缺口。UI 应显示“追踪不完整/采样”并允许从 Run Event 继续调查；不应把“无 Span”解释为“未执行”。
08 · Metrics、指标口径与统计方法
| 指标 | 参考定义 | 常见误区 |
|---|---|---|
| Run 完成率 | 指定时间窗口内 SUCCEEDED / 已终结 Run | 排除进行中 Run 后可能产生选择偏差 |
| 失败率 | FAILED / 已终结 Run | 取消、审批拒绝是否计入须说明 |
| 端到端延迟 | ended_at - created_at | 混合排队、审批等待与执行时间 |
| 纯执行耗时 | 有效运行时间之和 | 重试和并行节点不可简单相加 |
| 队列等待 | first_started_at - queued_at | 多次重排队需另计 |
| 人工等待 | 审批等待区间的并集 | 多个并行审批可能重叠 |
| 重试率 | 发生 attempt_no > 1 的 Step Run 占比 | 与重试次数均值不同 |
| 工具失败率 | 失败工具调用数 / 有结果的调用数 | 供应商限流与参数错误应分组 |
| 质量通过率 | 满足定义明确评估标准的结果占比 | 评估覆盖率不足时不可外推全部任务 |
| 单 Run 成本 | 归集的估计/已结算费用 | 价格表、缓存、批处理、货币汇率差异 |
聚合分析应按 Agent Version、Workflow Version、模型、工具、租户、项目、时间范围切分；显示样本量与时间窗口。建议展示 p50/p95/p99 延迟，而不只展示平均值。低样本量时避免夸大趋势；对比版本需控制任务类型、输入难度和流量分配差异。
指标时间基准：可按任务创建时间、终结时间或事件发生时间聚合，但同一图表必须固定口径。仪表板显示数据刷新时间、延迟与可能回填。
09 · 质量评估与业务结果
质量看板应与 F3 的评估体系共享定义，但区分离线测试结果与线上样本评估。研究报告 Studio 可设置：结构化输出合规率、引用链接可解析率、引用与论断匹配率、事实核验通过率、审核返工次数、用户采纳率、交付完整率。
其中“链接可解析”不等于“来源权威”，“引用存在”不等于“论断被支持”，“审核 Agent 通过”不等于“事实正确”。事实性判断需具备可检查证据和人工抽检机制。LLM-as-a-judge 结果应记录评估器版本、提示词、评分准则、置信信息与样本范围，避免与确定性 Schema 校验混为一谈。
建议展示 execution=SUCCEEDED, evaluation=FAILED, review=PENDING 的复合状态，允许业务用户查看“已生成草稿但尚未通过质量门禁”。对低覆盖率的自动评估，UI 必须展示覆盖率和未评估数量。
10 · Token、成本、资源用量与预算
成本计量需要将 UsageRecord 与 CostEstimate、CostSettlement 分开：供应商用量、平台内部计费和最终账单可能不同。字段包括 provider、model_id、input_tokens、output_tokens、cached_tokens、tool_calls、duration_ms、price_catalog_version、currency、estimated_cost、billed_cost、attribution_run_id。
对于一次 Workflow Run，成本应按 Agent、Step、模型、工具和共享基础设施分层归因。不要将一个跨节点复用的调用重复计费；重试产生的真实调用应计入实际消耗。价格缺失时显示“用量已知、成本待估”，不能默认零成本。
预算界面应呈现：当前已结算、估计未结算、预留额度、预算上限、预测超支风险。用户应能点击异常成本跳转到对应的模型/工具调用摘要。资源配额与成本预算由 P12 治理服务执行，Monitoring 只展示状态与可用的治理操作入口。
11 · 告警、通知与事件处理
11.1 告警对象与状态
告警规则包含：作用范围、指标/事件条件、观察窗口、阈值、严重级别、去重键、冷却时间、通知渠道、责任人和恢复条件。告警实例建议状态：OPEN → ACKNOWLEDGED → RESOLVED，支持 SUPPRESSED 与历史记录；确认不等于解决。
| 告警类型 | 触发依据 | 推荐处理 |
|---|---|---|
| 任务长时间无进展 | 最近权威活动时间超过 SLA | 检查队列/Worker/审批状态 |
| 同一 Agent 失败率升高 | 样本量与时间窗口满足规则 | 对比版本与错误分布 |
| 工具鉴权失效 | 明确授权错误事件 | 引导有权限人员重新连接 |
| 预算临界 | 已结算+预留达到阈值 | 提醒负责人调整任务或预算 |
| 质量回归 | 同口径评估显著下降 | 进入 F3 回归测试 |
| 人工审批超时 | 审批截止时间到达 | 通知审批人或升级处理 |
11.2 抑制与升级
同一 Run 的重复超时应合并；上游资源故障可能造成大量下游错误，应支持关联与抑制。对告警噪声设置冷却期和批量通知。通知渠道（站内、邮件、Webhook）应按用户偏好、授权和隐私级别选择。
11.3 用户可操作性
告警详情必须包含影响对象、证据链接、建议动作、负责人、时间和状态。任何“重试/取消/增加预算”按钮都应调用 F6/P12 的正式控制接口，并再次鉴权。
12 · 数据采集、事件管线与存储架构
flowchart LR
CP[Control Plane] --> EV[Run Event Bus]
EP[Execution Workers] --> EV
EP --> OT[OTel Collector]
EV --> ES[Durable Event Store]
EV --> AG[Aggregation Workers]
OT --> TS[Trace / Logs / Metrics Store]
AG --> MS[Metrics Read Model]
AG --> AL[Alert Evaluator]
ES --> Q[Monitoring Query API]
TS --> Q
MS --> Q
AL --> Q
Q --> UI[Monitoring UI]设计原则：业务状态事件可靠持久化；Telemetry 可以根据成本采样和分级保留；聚合视图允许最终一致性；原始事件和衍生指标必须可追溯。事件生产可采用事务 Outbox 避免数据库提交成功但事件未发送；消费者应具备幂等去重和乱序处理。
存储建议：PostgreSQL 保存 Run 权威状态、关键事件、告警与审计引用；对象存储保存受控的大型诊断附件；Trace/日志可根据规模选择专用后端；聚合指标可先在 PostgreSQL 实现，增长后再拆分时序/分析存储。
高基数警告：run_id、user_id、trace_id 不宜无节制作为时序指标标签，否则造成成本和性能问题；可将这些 ID 保留在 Trace、事件和日志中用于下钻。
13 · API、事件与查询契约
参考接口（不是既有产品的已验证 API）：
GET /v1/projects/{project_id}/runs?status=FAILED&limit=30&cursor=...
GET /v1/runs/{run_id}/monitoring-summary
GET /v1/runs/{run_id}/events?after_seq=102&limit=100
GET /v1/runs/{run_id}/trace?view=summary
GET /v1/analytics/runs?group_by=agent_version&from=...&to=...
GET /v1/alerts?status=OPEN&project_id=...
POST /v1/alerts/{alert_id}/acknowledge{
"run_id": "run_01JEXAMPLE",
"execution": {"status": "SUCCEEDED", "started_at": "2026-11-01T07:00:00Z", "ended_at": "2026-11-01T07:03:22Z"},
"evaluation": {"status": "FAILED", "criteria_version": "citation-check-v3", "score": 0.62},
"review": {"status": "PENDING", "assignee_ref": "user_123"},
"delivery": {"status": "NOT_READY"},
"usage": {"input_tokens": 18000, "output_tokens": 5200, "estimated_cost": "0.42", "currency": "USD", "price_version": "2026-11-example"},
"trace": {"trace_id": "tr_123", "completeness": "PARTIAL"},
"data_as_of": "2026-11-01T07:03:30Z"
}接口约束：查询必须在服务端执行租户与对象级授权；分页采用稳定游标；时间统一保存 UTC 并按用户时区显示；大范围聚合可异步生成；返回数据新鲜度与可能延迟；敏感诊断字段按权限裁剪。HTTP 错误使用统一错误结构，明确 403、404、429、503 的区别。
14 · 数据模型与查询实现参考
以下 DDL 为简化示意，缺少完整迁移、分区和索引策略，不能直接视为生产可部署版本。
CREATE TABLE run_events (
tenant_id uuid NOT NULL,
run_id uuid NOT NULL,
seq bigint NOT NULL,
event_id uuid NOT NULL,
event_type text NOT NULL,
occurred_at timestamptz NOT NULL,
ingested_at timestamptz NOT NULL DEFAULT now(),
payload jsonb NOT NULL DEFAULT '{}'::jsonb,
PRIMARY KEY (tenant_id, run_id, seq),
UNIQUE (tenant_id, event_id)
);
CREATE INDEX run_events_by_time ON run_events (tenant_id, occurred_at DESC);
CREATE TABLE run_usage (
tenant_id uuid NOT NULL,
usage_id uuid NOT NULL,
run_id uuid NOT NULL,
step_run_id uuid,
provider text NOT NULL,
model_id text,
input_tokens bigint NOT NULL DEFAULT 0,
output_tokens bigint NOT NULL DEFAULT 0,
estimated_cost numeric(18,8),
currency char(3),
price_version text,
observed_at timestamptz NOT NULL,
PRIMARY KEY (tenant_id, usage_id)
);
CREATE INDEX run_usage_by_run ON run_usage (tenant_id, run_id);
CREATE TABLE alert_instances (
tenant_id uuid NOT NULL,
alert_id uuid NOT NULL,
rule_id uuid NOT NULL,
run_id uuid,
dedup_key text NOT NULL,
severity text NOT NULL,
status text NOT NULL,
opened_at timestamptz NOT NULL,
acknowledged_at timestamptz,
resolved_at timestamptz,
PRIMARY KEY (tenant_id, alert_id)
);实际实现还需要外键、复合租户约束、RLS、授权查询视图、保留/删除策略和事件幂等处理。聚合查询应避免把单次 Run 的多条 Span 直接 JOIN 到多条 Usage 记录而产生笛卡尔倍增；先按 Run 聚合，再关联维度。
15 · Studio 贯穿案例：研究报告运行监控
15.1 业务流程
flowchart LR
T[选题 Agent] --> R1[选题审核]
R1 --> H[用户确认]
H --> D[深度调研]
D --> A[分析 Agent]
A --> R2[研究审核]
R2 --> W[写作与交付]Studio 项目首页显示「正在执行 4」「等待用户确认 2」「近期失败 1」「待交付 3」，点击每项可进入受限筛选后的 Run 列表。用户打开某份研究报告，看到当前阶段为“深度调研”，已完成选题与确认，最近工具调用成功，估计成本和下一步计划。若研究审核不通过，显示具体审核意见、返工节点、已尝试次数与关联证据，而非简单标红“任务失败”。
15.2 三个典型异常
场景 A：检索工具超时。 总览显示调研节点重试，Run 详情展示 TOOL_TIMEOUT、超时工具、重试次数和受影响阶段。用户可以继续等待或在权限允许时取消；开发者可进入 Trace 查看网络/供应商错误。
场景 B：报告已生成但引用不合格。 执行状态为 SUCCEEDED，评估状态 FAILED，审核状态 PENDING。成果仍可作为草稿查看，但不能自动标为正式交付；可将失败样本保存到 F3 测试集。
场景 C：预算耗尽。 P12 预算服务拒绝下一次高成本调用，Run 进入等待处理或失败（依策略）；监控展示已用金额、预留金额、拒绝决策和授权调整入口，不能由监控页面绕过预算检查。
15.3 Studio MVP 页面建议
运行列表：任务名、项目、阶段、状态、最近活动、待办人、估计成本。Run 详情：顶部状态卡、左侧阶段流程、中部事件流、右侧产物与审批；开发者可切换 Trace 面板。项目分析：最近 7/30 天任务完成情况、失败原因分布、返工次数和成本区间。优先保证事实正确、状态一致与可操作性，而非先实现复杂仪表板。
16 · 开发路线、验收标准与指标
| 阶段 | 交付范围 | 退出标准（参考） |
|---|---|---|
| M0 基础状态 | Run 列表、详情、阶段状态、产物链接 | 用户能找到并解释任意授权 Run 的当前状态 |
| M1 事件诊断 | 时间轴、错误分类、重试记录、Trace 摘要 | 能从失败 Run 定位到具体 Step/Attempt |
| M2 用量质量 | Token/成本、评估状态、审核待办 | 执行成功与质量通过不再混淆 |
| M3 告警运营 | 告警规则、责任人、通知、抑制 | 关键异常可被确认、处理、关闭 |
| M4 跨项目分析 | 趋势、版本比较、SLO、容量分析 | 统计口径与样本范围可复核 |
产品指标：任务定位时间、故障定位时间、人工待办响应时间、状态理解正确率、监控查询成功率、告警有效率、跨页面状态一致率、评估覆盖率、成本归因完整率。指标目标值需基于 Studio 实测基线制定，不预设通用阈值。
验收任务建议：给测试用户一个正在运行的报告任务，要求其找到当前阶段、最近活动、待办人和产物；给开发者一个工具超时案例，要求其定位失败 Step、Attempt 和错误码；给负责人一个预算异常案例，要求其解释金额口径和可采取的操作。记录完成率、耗时和误解类型。
17 · 工程验证矩阵（40 项待执行）
下表是待执行的测试设计，不表示已运行或通过。验收时需补充环境、数据集、预期断言、实际结果与缺陷编号。
| 编号 | 测试维度 | 测试场景 | 预期结果 |
|---|---|---|---|
| 01 | 权限隔离 | A 租户查询 B 租户 Run | 不得返回 B 的状态、Trace、产物或聚合数据 |
| 02 | 对象级授权 | 普通成员访问私有项目 | 403/404 策略一致且无信息泄露 |
| 03 | 运行状态 | Run 状态更新 | 列表与详情最终一致且显示更新时间 |
| 04 | 状态分离 | 执行成功但评估失败 | 分别显示 SUCCEEDED 与 FAILED |
| 05 | 审批分离 | 等待人工确认 | 标明待办责任人且不显示已交付 |
| 06 | 进度诚实 | 动态节点数未知 | 不展示无依据的精确百分比 |
| 07 | 游标分页 | 运行期间新增 Run | 翻页无重复与异常漏项 |
| 08 | 筛选组合 | 项目+版本+状态 | 返回结果全部符合条件 |
| 09 | 事件幂等 | 同一 event_id 重发 | 聚合不重复计数 |
| 10 | 事件乱序 | 事件按接收时间逆序 | 同 Run 依据 seq 还原 |
| 11 | 事件缺口 | seq 中间缺失 | 提示不完整并触发修复机制 |
| 12 | 跨服务时间 | 时钟有偏差 | 展示明确时间口径并避免负耗时 |
| 13 | Trace 缺失 | Worker 崩溃 | 状态仍可通过事件定位 |
| 14 | Trace 采样 | 仅部分 Span | 显式标注采样或不完整 |
| 15 | 敏感信息 | Prompt 含 API Key | 无权限视图不可见明文 |
| 16 | 富文本注入 | 工具响应含脚本 | UI 转义且不执行 |
| 17 | 错误分类 | 工具 401/429/timeout | 分类正确且建议动作不同 |
| 18 | 重试归因 | Step 三次 Attempt | 成功率和重试率不重复计算 |
| 19 | 成本延迟 | Usage 晚于 Run 完成 | 显示估计与结算状态 |
| 20 | 价格版本 | 模型价格更新 | 历史成本使用对应价格版本 |
| 21 | 预算归因 | 共享调用和重试 | 不重复归因且记录真实消耗 |
| 22 | 高基数指标 | 每 Run 一个 metric label | 系统拒绝/规避高基数标签 |
| 23 | 聚合时间窗 | 按创建/完成时间统计 | 界面明确采用何种口径 |
| 24 | 样本量 | 仅两个评估样本 | 展示样本数且避免确定性结论 |
| 25 | 评估覆盖率 | 部分 Run 未评估 | 同时显示通过率与覆盖率 |
| 26 | 告警去重 | 相同异常连续触发 | 合并告警并保留事件数 |
| 27 | 告警恢复 | 故障恢复 | 告警可按规则进入 RESOLVED |
| 28 | 告警权限 | 非负责人确认告警 | 拒绝并审计 |
| 29 | 通知隐私 | 跨租户邮件通知 | 不包含未授权内容 |
| 30 | 通知风暴 | 下游批量失败 | 执行抑制/限流 |
| 31 | 历史删除 | 超过保留期限 | 按策略删除且审计合规 |
| 32 | 导出权限 | 下载 Trace 附件 | 再次鉴权且有访问记录 |
| 33 | SSE 断线 | 事件流中断重连 | 通过游标补齐且去重 |
| 34 | 监控故障 | Trace 服务不可用 | Run 基础状态仍可查询 |
| 35 | 质量回归 | Agent 版本升级 | 同口径对比并显示样本范围 |
| 36 | 人工待办 | 审批到期 | 可发现并正确升级通知 |
| 37 | 多项目检索 | 项目成员权限不同 | 结果严格裁剪 |
| 38 | 指标精度 | 并行 Step 耗时 | 不直接求和当作端到端时长 |
| 39 | 无数据状态 | 筛选无结果 | 区别于查询失败 |
| 40 | 状态新鲜度 | 聚合滞后 | 显示 data_as_of |
18 · 风险、局限与研究反思
观测偏差：只有成功上报的事件可能进入统计，崩溃和网络中断导致的数据缺失会扭曲失败率；需结合权威 Run 状态与采集健康度判断。
因果与相关混淆：某 Agent 版本升级后成功率上升，不一定由版本本身造成，可能与输入难度、模型供应商、流量分配或审核策略变化有关。
隐私与可观测性冲突：记录完整上下文便于调试，却增加敏感信息暴露风险。应按最小必要原则分级采集和保留，并在需要时提供受控的临时调试会话。
质量指标的有效性：自动评分只能测量明确定义的代理指标。研究质量需要引用核验、任务语境与人工判断；不能把仪表板分数当作客观真理。
成本与延迟的准确性：供应商报告、缓存、异步账单、时钟偏差与采样均可能造成差异。界面应呈现数据口径和不确定性，而非假精确。
产品复杂度：高级追踪和分析可能压倒普通用户。应以角色、任务和渐进式披露控制复杂度。
19 · 总结与下一步
F8 的目标是让用户不仅知道“Agent 正在运行”，还能够回答运行到哪里、发生了什么、为什么失败、结果是否可信、花费多少、谁需要行动。产品应建立统一 Run 身份、独立的执行/评估/审核/交付状态、分层诊断与有口径的统计体系。
对 Studio，优先建设可靠的运行列表、阶段时间轴、错误摘要、产物与审批链接，再补充 Trace、质量和成本分析，最后根据真实运营需求引入告警与跨项目趋势。下一篇 F9 · 用户如何管理 Agent 的版本与生命周期？ - Agent Management 将研究 Agent 的日常维护、版本升级、状态迁移、停用、归档与治理操作。
跨章节契约修订说明（v1.3-r1，2026-11-01）
本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。
业务事件与遥测边界： [平台设计决策] Run 权威状态取自持久化业务记录和状态事件；Trace/Span/Metric 用于诊断，采样或丢失不能改变 Run 状态。通过 run_id、step_run_id、attempt_id 与 trace_id 关联。
OpenTelemetry 兼容性： [官方资料已核验，限定范围] GenAI semantic conventions 持续版本化；本文 workflow.step、agent.invoke、llm.request 等名称仅为自定义 Span 示例，不是已验证的 OTel 标准 Span 名称。上线前须固定具体 semconv 版本、字段映射、脱敏策略与升级回归测试。
附录 A：参考文献与原始资料
以下参考资料用于支撑可观测性、指标、API、安全及运行语义等基础概念。它们不直接规定本文的 F8 产品架构；具体 UI、对象字段和测试用例属于本篇工程推论。
- OpenTelemetry, Documentation / Concepts. opentelemetry.io/docs/concepts （Trace、Metrics、Logs 的基本概念。）
- OpenTelemetry, Specification. opentelemetry.io/docs/specs/otel （遥测数据模型、上下文传播和采样的规范依据。）
- OpenTelemetry, Semantic Conventions. opentelemetry.io/docs/specs/semconv （语义属性规范；实施前应核对版本。）
- CNCF, CloudEvents Specification. github.com/cloudevents/spec （事件元数据与互操作性参考；本文事件结构未声称完全兼容。）
- Google, Site Reliability Engineering: Monitoring Distributed Systems. sre.google/sre-book/monitoring-distributed-systems （监控目标、告警设计与有效信号。）
- Google, The Site Reliability Workbook: Alerting on SLOs. sre.google/workbook/alerting-on-slos （SLO 与告警策略。）
- Prometheus, Metric and Label Naming. prometheus.io/docs/practices/naming （指标标签与高基数治理背景。）
- W3C, Trace Context. www.w3.org/TR/trace-context （跨服务追踪上下文传播。）
- PostgreSQL, Documentation. www.postgresql.org/docs/current （数据库事务、索引与 RLS 参考。）
- OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html （HTTP API 契约。）
- OWASP, Top 10 for LLM Applications. genai.owasp.org/llm-top-10 （提示注入、敏感信息及工具调用风险背景。）
- NIST, AI Risk Management Framework 1.0. doi.org/10.6028/NIST.AI.100-1 （AI 风险评估和治理背景。）
- LangSmith, Observability Documentation. docs.smith.langchain.com/observability （Agent Trace 和评估产品案例；功能随版本变化。）
- OpenAI, Agents SDK Tracing. openai.github.io/openai-agents-python/tracing （Agent、模型和工具追踪的实现参考。）
- Temporal, Observability. docs.temporal.io （持久化工作流的可观察性与历史记录背景。）
附录 B：研究证据、验证声明与适用边界
B.1 证据分级
- 官方规范与资料支持：OpenTelemetry 的遥测概念、W3C Trace Context、Prometheus 标签实践、Google SRE 告警原则、OpenAPI 和 PostgreSQL 的基础能力。
- 工程综合推论：四种状态分离的 UI 模型、Monitoring Query API、Run 详情分层、Studio 监控布局、成本归因与质量看板设计。
- 待验证假设：七类视图是否最适合 Studio 用户、阶段进度是否足够可理解、告警阈值与质量评分是否产生实际决策价值。
B.2 验证声明
本文未执行真实 SDK 集成、Telemetry 采集、SQL 迁移、接口负载测试、安全渗透测试或用户访谈。40 项测试为参考验收设计，不代表实际测试结果。官方链接与产品功能应在实施或正式发表前复核最新版本。
B.3 适用范围
适用于需要长期运行、异步执行、多 Agent 协作、阶段审核和可追溯产物的 Agent Platform。对于简单即时对话应用，可采用精简监控；对于高风险或受监管业务，应进一步满足适用的数据保留、审计和合规要求。