F6 · 用户如何启动、操作和控制 Agent？ - Agent Execution
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：03 · Agent Platform 应该提供哪些产品功能？ - Product Architecture
文档类型：专题研究 / 产品架构 / 交互与工程参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何让用户以明确的输入、授权和预算启动 Agent，理解执行状态，在运行中进行干预、暂停、恢复、取消或重试，并可靠地取得结果？
专题导读
本篇属 Product Architecture。F1 - F2 - F3 - F4 - F5 分别研究 Agent 创建、配置、开发测试、发布共享以及工作空间与项目组织。F6 关注用户真正使用 Agent 完成任务的交互闭环：启动之前知道将执行什么，执行过程中知道发生什么，遇到问题能够有效干预，结束之后知道得到什么结果。本篇主要研究单个 Agent 的执行体验；多 Agent 协作编排由 F7 展开，运行监控分析由 F8 展开，产物交付由 F10 展开。
技术上，F6 对应 P1 Control Plane、P2 Execution Plane、P5 Deployment & Runtime Management、P6 Workflow Management、P7 Resource & Integration、P8 API & SDK、P10 Data & Assets 与 P12 Governance。下文中的接口、对象、状态和测试属于参考设计与待验证方案，并非已经部署的 Studio 实现。
研究结论
- 启动 Agent 的产品动作应生成可追踪的 Run，而不是仅发送一次聊天消息。Run 应具有稳定标识、归属、版本快照、输入引用、状态和成本上下文。
- 提交成功、执行成功、业务结果合格必须分开表示。HTTP 接受请求只意味着平台接收执行意图；Run 成功只表示执行机制按定义完成；成果是否通过审核还需独立评价。
- 用户应在启动前看见 Agent 身份、版本、输入、可使用资源、预估成本或预算上限、风险操作与审批要求。对高风险操作实行明确授权。
- 暂停、取消、重试和恢复具有不同语义。用户界面不能将“已请求取消”显示为“已取消”；也不能保证所有执行器都支持任意时点暂停。
- 每次执行固定 Agent Version、关键依赖与权限上下文；运行中的版本切换不应静默改变已启动任务。外部服务的实际行为仍可能随时间变化。
- 运行工作台应统一提供输入、状态、事件时间线、可见中间产物、干预入口、最终结果及故障恢复建议；敏感推理内容和凭证不得默认暴露。
- Studio MVP 优先实现异步 Run、实时事件、取消、失败重试、人工确认、产物关联与执行记录，再逐步扩展暂停恢复、交互式协作和复杂执行策略。
01 · 概念、范围与关键对象
1.1 Agent Execution 的产品含义
Agent Execution 是用户通过平台请求某个 Agent 执行具体任务，并在任务生命周期中观察和控制其行为的产品能力。它包含启动入口、输入配置、执行反馈、人工干预、终止处理与结果访问。它不等同于底层推理循环，也不等同于 Worker 调度器。
| 概念 | 产品含义 | 与 F6 的关系 |
|---|---|---|
| Agent Definition | 可识别的 Agent | 用户选择的执行主体 |
| Agent Version | 不可变的 Agent 定义快照 | 执行时锁定 |
| Deployment | 可供调用的运行配置与入口 | 决定是否允许在环境中运行 |
| Run | 一次用户可追踪的执行请求 | F6 核心对象 |
| Attempt | Run 中一次具体执行尝试 | 重试与故障排查 |
| Event | 执行中可观察的状态或活动 | 时间线、流式反馈 |
| Intervention | 用户或策略发起的控制动作 | 取消、批准、补充输入等 |
| Artifact | 执行生成的文件或结构化成果 | 结果预览与交付入口 |
1.2 Run 与 Session、Message、Workflow Run
Session 表示可持续的交互上下文；Message 是会话中的一条消息；Run 是有明确执行边界和生命周期的一次任务。一次 Session 可包含多个 Run，一个 Run 也可处理多条消息或工具调用。Workflow Run 是工作流级执行，可能包含多个 Agent Run；不能将它们混用为同一标识。
1.3 产品范围边界
F6 负责用户侧的单 Agent 运行操作；F7 负责多个 Agent 的协作关系与工作流交互；F8 负责跨运行的可观测性、指标和故障分析；F9 负责 Agent 生命周期管理；F10 负责成果版本、审核、导出与交付。F6 可以提供这些功能的入口，但不重复定义它们的核心业务规则。
02 · 用户角色、任务与使用情境
| 角色 | 核心目标 | 主要关注点 | 典型权限 |
|---|---|---|---|
| 业务使用者 | 用 Agent 完成一次任务 | 输入简单、过程可理解、结果可用 | 启动、查看本人 Run、请求取消 |
| 项目负责人 | 确保任务符合项目目标 | 预算、风险、审核、进度 | 项目级运行与审批 |
| Agent 构建者 | 验证 Agent 在真实任务中的行为 | 版本、Trace、异常、回归 | 启动测试与诊断 |
| 平台运维者 | 保证运行服务可靠 | 队列、资源、故障、配额 | 运维控制，不自动取得业务数据访问权 |
| 审批人 | 判断高风险步骤是否可继续 | 操作对象、参数、证据、有效期 | 对指定请求批准或拒绝 |
典型情境包括：从 Agent 详情页直接运行、从项目工作台启动、在会话中连续交互、从模板任务启动、通过 API 触发，以及工作流中的某个 Agent 节点被调度执行。不同入口应共享同一套 Run 状态与权限语义。
03 · 产品信息架构与运行工作台
3.1 建议的信息架构
flowchart TB
A[Agent 详情 / 项目工作台 / 会话 / API] --> B[启动面板]
B --> C[运行工作台 Run Workspace]
C --> D[状态与进度]
C --> E[事件时间线]
C --> F[输入与交互]
C --> G[控制操作]
C --> H[结果与产物]
C --> I[运行详情与诊断]
G --> J[取消 / 重试 / 审批 / 恢复]3.2 页面组成
启动面板：Agent 名称、版本、运行环境、任务描述、输入字段、文件引用、资源权限提示、预算和提交按钮。运行工作台：任务标题、状态标签、开始与耗时、当前活动、可见事件、用户操作、结果预览。运行详情：Run ID、版本与配置摘要、事件时间线、失败分类、Attempt、成本和相关产物。历史运行：筛选、排序、重启类似任务、比较结果、归档。
3.3 信息层级
首屏优先回答四个问题：“任务是否开始？”“现在进行到哪里？”“我能做什么？”“结果在哪里？”技术日志、Token 细节、Trace 和复杂元数据应按需展开。长时间运行任务需要明确显示最近一次活动时间，避免把无更新误判为停滞或完成。
04 · 启动 Agent 的交互流程
4.1 标准流程
- 选择 Agent 或 Deployment，读取当前可用版本与能力摘要。
- 填写任务目标、结构化输入、文件或知识资源引用。
- 校验字段、资源访问、执行权限、额度、预算和环境状态。
- 展示执行预检结果；高风险工具或外部副作用显示审批提示。
- 用户确认并提交；平台以幂等键创建 Run。
- 返回 Run ID 与初始状态，进入运行工作台或提供后台运行入口。
4.2 启动前预检
| 检查项 | 示例 | 失败时产品行为 |
|---|---|---|
| Agent 可用性 | 版本已发布且可执行 | 禁止提交，说明需要发布或部署 |
| 输入契约 | 必填字段、类型、长度 | 定位具体字段并保留已填内容 |
| 资源权限 | 检索连接已授权 | 引导连接资源或请求授权 |
| 预算与配额 | 项目剩余额度 | 展示限制与可调整入口 |
| 依赖健康 | 模型服务可用性 | 显示降级策略或建议稍后重试 |
| 风险操作 | 发送邮件、写入数据库 | 展示需要审批的操作范围 |
| 版本固定 | 解析渠道到具体版本 | 展示实际使用的版本标识 |
预检属于提交时的判断，不可替代执行时检查；权限和资源状态可能在任务运行过程中发生变化。
4.3 输入设计
优先根据 Agent Input Schema 生成表单，支持文本、枚举、数值、日期、文件与资产引用。高级模式可允许 JSON 输入，但需提供 Schema 校验、示例和错误定位。文件输入应采用资产引用，不应把大文件直接嵌入 Run 元数据。敏感输入需要分类、脱敏与保留期限说明。
4.4 重复提交
双击按钮、网络超时和浏览器刷新都可能造成重复 Run。前端在提交中禁用重复操作，服务端用 Idempotency-Key 与请求指纹识别重复创建。相同键与不同请求体应返回冲突，而不是静默复用旧任务。
05 · Run 状态模型与用户可见语义
5.1 参考状态机
stateDiagram-v2
[*] --> queued
queued --> running
queued --> cancelled
running --> waiting_input
running --> waiting_approval
running --> pause_requested
pause_requested --> paused
pause_requested --> running
paused --> running
waiting_input --> running
waiting_approval --> running
running --> cancel_requested
cancel_requested --> cancelled
cancel_requested --> succeeded: 已完成的竞态结果
running --> succeeded
running --> failed
running --> timed_out
queued --> failed
waiting_input --> cancelled
waiting_approval --> cancelled
paused --> cancelled
succeeded --> [*]
failed --> [*]
cancelled --> [*]
timed_out --> [*]状态机仅为参考；实现可将 waiting_input 与 waiting_approval 合并为 waiting 加原因字段，或将暂停能力限定在支持检查点的执行器。终态一般不可逆，重试应新建 Attempt 或新 Run，并保留原始记录。
5.2 状态展示
| 状态 | 用户文案 | 可用操作 | 重要说明 |
|---|---|---|---|
| queued | 等待执行 | 取消、查看排队信息 | 不是运行故障 |
| running | 正在执行 | 请求取消、交互、查看进度 | 进度可能无法精确量化 |
| waiting_input | 等待补充信息 | 提交输入、取消 | 需显示等待原因和截止时间 |
| waiting_approval | 等待审批 | 审批人批准/拒绝 | 必须展示待批准动作详情 |
| pause_requested | 正在尝试暂停 | 查看状态 | 不保证立即暂停 |
| paused | 已暂停 | 恢复、取消 | 需要可恢复的状态快照 |
| cancel_requested | 正在取消 | 查看状态 | 可能仍有正在完成的外部操作 |
| succeeded | 执行完成 | 查看结果、重新运行 | 不等于质量审核通过 |
| failed | 执行失败 | 查看原因、重试 | 说明可重试性 |
| cancelled | 已取消 | 查看部分产物、重新运行 | 已发生副作用不能自动撤销 |
| timed_out | 执行超时 | 查看记录、按策略重试 | 需区分平台超时与外部调用超时 |
5.3 进度与时间估计
如果 Agent 任务没有确定步骤总数，不应展示虚假的百分比。可显示阶段标签、已完成步骤数、当前工具活动、最近事件时间及运行时长。预计剩余时间只有在具备可验证估计模型时才展示，并注明估算性质。
06 · 实时反馈、事件流与交互
6.1 事件分类
| 事件 | 用户价值 | 展示策略 |
|---|---|---|
| run.accepted | 已受理 | 显示 Run ID |
| run.started | 已开始 | 更新时间线 |
| agent.message.delta | 输出增量 | 逐步显示，允许断线恢复 |
| tool.call.started | 正在调用工具 | 展示工具名称和安全摘要 |
| tool.call.completed | 工具调用结束 | 展示状态和可公开结果 |
| run.waiting_input | 需要补充输入 | 高优先级提醒 |
| approval.requested | 需要审批 | 展示审批操作与参数摘要 |
| artifact.created | 产生中间成果 | 提供预览入口 |
| run.completed | 执行结束 | 显示最终结果 |
| run.failed | 执行失败 | 显示错误类别与建议 |
6.2 SSE 与事件恢复
Web 端可使用 SSE 接收单向运行事件，交互操作通过独立 HTTP API 提交。每个可恢复事件需要稳定的 event_id 与 Run 内序号；断线后用游标补取，避免遗漏和重复展示。服务端可以对高频 token 事件合并推送，不能假设网络连接永久可靠。
6.3 可见性边界
平台可以展示状态、工具名称、经脱敏的输入输出、结构化步骤和证据链接；不应默认暴露密钥、其他租户数据或模型内部私有推理内容。调试视图需要更严格的权限与数据保留规则。用户看到的“思考中”只应表示可观察的处理状态，不应暗示平台拥有可公开的完整内部推理记录。
07 · 用户控制操作及其执行语义
7.1 取消 Cancel
取消是一个请求：Control Plane 将 Run 标记为 cancel_requested，向执行器传播取消信号，执行器在安全检查点终止后报告 cancelled。如果执行已完成或外部操作已经提交，取消无法保证回滚。产品需显示“取消中”及最终结果，不得立即宣称取消成功。
7.2 暂停与恢复 Pause / Resume
暂停需要执行器支持状态持久化、检查点或明确的等待点。无检查点的长模型调用、不可中断外部工具和流式网络调用可能无法即时暂停。恢复前应检查版本、资源权限、凭证有效性、预算和外部依赖；恢复操作应记录操作者与时间。
7.3 重试 Retry
| 重试方式 | 使用条件 | 关键风险 |
|---|---|---|
| 同一 Run 新 Attempt | 可安全重新执行且语义允许 | 需防止副作用重复 |
| 从检查点恢复 | 已持久化执行状态 | 检查点可能与环境不兼容 |
| 新建 Run 并复用输入 | 需要独立历史和新的配置 | 可能产生不同结果与成本 |
| 仅重试失败工具调用 | 工具支持幂等或可验证结果 | 外部系统可能已执行成功 |
用户界面必须区分“重试整个任务”与“恢复未完成步骤”。对发邮件、付款、数据库写入等操作，未经幂等或结果确认不得盲目重试。
7.4 补充输入与人工审批
用户补充输入应绑定具体 Run 和等待请求，并带有请求版本、有效期和权限校验。审批动作需展示将执行的工具、目标、参数摘要、影响范围及成本，审批结果绑定参数摘要，防止审批后被替换为其他操作。拒绝审批后的行为可以是失败、跳过或走替代分支，需由 Agent/Workflow 契约定义。
7.5 接管与停止自动化
对高风险任务可提供“转为人工处理”或“停止后续自动操作”。接管不等于撤销已执行动作；系统应明确展示哪些操作已发生、哪些仍待处理。
08 · 会话式执行与任务式执行
会话式执行适合问答、持续迭代和多轮协作，核心对象是 Session 与消息历史；任务式执行适合明确目标、可异步完成、需要审核与交付的工作，核心对象是 Run 与 Artifact。两种模式可以共存：用户在会话中发起任务式 Run，执行结束后把结果回填会话。避免把所有会话消息都自动转化为独立长任务，造成成本和状态管理混乱。
在 Studio 中，用户与主管 Agent 的私聊可以是 Session；“生成本周 Agent 技术研究报告”是 Workflow Run；工作流内“调研 Agent 执行文献检索”是 Agent Run。产品应能在三个层级之间导航，而不混淆状态。
09 · 运行历史、结果与可追溯性
9.1 Run 详情最小字段
| 字段 | 用途 |
|---|---|
| run_id / tenant_id / project_id | 唯一身份与归属 |
| agent_id / agent_version_id | 固定执行主体与版本 |
| deployment_revision_id | 运行环境版本 |
| input_asset_refs / input_digest | 输入来源与完整性 |
| status / status_reason | 当前状态与原因 |
| created_by / created_at | 发起者与时间 |
| started_at / ended_at | 生命周期时间 |
| attempt_count | 尝试次数 |
| estimated_cost / actual_cost | 成本估计与实际计量 |
| artifact_refs | 产物引用 |
| trace_id / correlation_id | 诊断与关联 |
| policy_snapshot_ref | 执行时适用治理策略的可追溯引用 |
9.2 结果页面
最终结果至少区分：执行状态、内容结果、审核状态、交付状态。例如，run.status=succeeded、review.status=changes_requested、delivery.status=not_ready 可以同时成立。失败的 Run 也可能保留有价值的部分产物，但必须标注其未完成或未审核性质。
9.3 重跑与复现
“使用相同输入再次运行”不等于确定性复现。模型版本别名、采样随机性、外部 API、检索索引、时间和凭证权限均可能变化。应记录固定版本与可追溯依赖，并明确复现保证的边界。
10 · 安全、授权、成本与风险治理
- 启动授权：检查用户是否可使用 Agent、项目、Deployment 和输入资产。
- 执行授权：工具调用时再次检查主体身份、连接授权、作用域与策略；启动授权不等于工具全权授权。
- 预算预留：创建 Run 时检查并可预留预算；执行中计量、超限处理与结束结算应形成闭环。
- 租户隔离：事件订阅、运行查询、产物访问和取消操作都必须执行对象级授权。
- 风险操作审批：对外发送、写入、删除、资金相关操作应根据风险等级设置明确门禁。
- 审计：记录发起、取消、暂停、恢复、审批、权限拒绝和重试行为，不应在日志中明文记录凭证。
- 滥用与注入：来自文件、网页或工具的文本属于不可信输入，不能直接提升为系统级指令；工具执行应有独立权限约束。
成本显示应区分预估与实际，支持按 Run、Agent、项目归因。预算耗尽的处理应有明确策略：拒绝新 Run、请求追加预算、在安全点暂停或终止；不能隐式超支。
11 · 技术架构与跨组件协作
sequenceDiagram
actor User
participant UI as Run Workspace
participant API as Platform API
participant CP as Control Plane
participant Gov as Governance
participant Reg as Agent Registry
participant Q as Durable Queue
participant EP as Execution Plane
participant Res as Resource Gateway
participant A as Artifact Service
User->>UI: 填写输入并启动
UI->>API: POST /runs + Idempotency-Key
API->>CP: 创建执行请求
CP->>Gov: 授权、配额与预算检查
CP->>Reg: 解析并固定 Agent Version
CP->>Q: 提交执行任务
CP-->>API: run_id / queued
API-->>UI: 202 Accepted
Q->>EP: 分派任务
EP->>Res: 工具调用时重新授权
Res-->>EP: 结果或错误
EP->>A: 写入产物
EP-->>CP: 状态、事件、成本
CP-->>UI: SSE / 事件查询
UI-->>User: 进度、结果与控制入口Control Plane 是 Run 状态与执行准入的权威协调者；Execution Plane 实际运行；Governance 提供策略判断；Registry 提供版本；Asset Service 管理输入和输出；API/SDK 对外提供一致契约。真实系统可采用模块化单体部署，不必将图中的每个逻辑组件独立成微服务。
12 · 参考 API 与数据契约
12.1 创建 Run
POST /v1/projects/{project_id}/runs
Authorization: Bearer <token>
Idempotency-Key: 0198d1f2-unique-request
Content-Type: application/json
{
"agent_id": "agent_topic_001",
"channel": "production",
"input": {"research_topic": "Agent 平台产品功能研究", "language": "zh-CN"},
"input_asset_refs": ["asset_version_123"],
"budget": {"max_cost_usd": 2.50},
"execution_mode": "async"
}HTTP/1.1 202 Accepted
Location: /v1/runs/run_123
{
"run_id": "run_123",
"status": "queued",
"agent_version_id": "agentver_2026_11_01_01",
"created_at": "2026-11-01T08:00:00Z",
"links": {"self": "/v1/runs/run_123", "events": "/v1/runs/run_123/events"}
}12.2 查询与控制
| 方法与路径 | 目的 | 关键约束 |
|---|---|---|
GET /v1/runs/{id} | 查询 Run | 对象级授权 |
GET /v1/runs/{id}/events?after=... | 补取事件 | 游标、排序与脱敏 |
GET /v1/runs/{id}/stream | SSE 订阅 | 认证、断线恢复、租户隔离 |
POST /v1/runs/{id}:cancel | 请求取消 | 幂等、状态冲突处理 |
POST /v1/runs/{id}:pause | 请求暂停 | 检查执行器能力 |
POST /v1/runs/{id}:resume | 请求恢复 | 权限、资源、检查点校验 |
POST /v1/runs/{id}:retry | 创建重试 | 指明策略和副作用风险 |
POST /v1/runs/{id}/inputs | 补充输入 | 绑定等待请求与版本 |
POST /v1/approvals/{id}:decide | 提交审批 | 审批人授权与参数摘要校验 |
GET /v1/runs/{id}/artifacts | 查询产物 | 资产访问权限 |
12.3 错误契约
{
"error": {
"code": "RUN_NOT_PAUSABLE",
"message": "当前执行器不支持在此步骤暂停",
"retryable": false,
"request_id": "req_456",
"details": {"run_id": "run_123", "current_status": "running"}
}
}建议使用明确错误码：INPUT_VALIDATION_FAILED、AGENT_NOT_DEPLOYED、RESOURCE_ACCESS_DENIED、QUOTA_EXCEEDED、BUDGET_EXCEEDED、RUN_STATE_CONFLICT、RUN_NOT_PAUSABLE、APPROVAL_EXPIRED、RUN_ALREADY_TERMINAL。HTTP 状态码应与错误语义一致，例如权限拒绝 403、资源不存在 404、状态冲突 409、请求参数不合法 422、受限请求 429；具体映射需在 API 契约中固定。
13 · 参考持久化模型
-- PostgreSQL 参考草案；实际部署需补齐租户外键、RLS、迁移和索引策略。
CREATE TABLE agent_runs (
tenant_id UUID NOT NULL,
run_id UUID PRIMARY KEY,
project_id UUID NOT NULL,
agent_id UUID NOT NULL,
agent_version_id UUID NOT NULL,
deployment_revision_id UUID,
requested_by UUID NOT NULL,
status TEXT NOT NULL CHECK (status IN (
'queued','running','waiting_input','waiting_approval',
'pause_requested','paused','cancel_requested',
'succeeded','failed','cancelled','timed_out')),
input_ref TEXT NOT NULL,
input_digest TEXT,
budget_limit_usd NUMERIC(12,4),
actual_cost_usd NUMERIC(12,4) DEFAULT 0,
trace_id TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
started_at TIMESTAMPTZ,
ended_at TIMESTAMPTZ,
revision BIGINT NOT NULL DEFAULT 1
);
CREATE TABLE run_attempts (
attempt_id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
run_id UUID NOT NULL REFERENCES agent_runs(run_id),
attempt_no INT NOT NULL,
worker_id TEXT,
status TEXT NOT NULL,
error_code TEXT,
started_at TIMESTAMPTZ,
ended_at TIMESTAMPTZ,
UNIQUE (run_id, attempt_no)
);
CREATE TABLE run_events (
tenant_id UUID NOT NULL,
run_id UUID NOT NULL REFERENCES agent_runs(run_id),
sequence_no BIGINT NOT NULL,
event_type TEXT NOT NULL,
public_payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (run_id, sequence_no)
);
CREATE INDEX idx_runs_project_created ON agent_runs (tenant_id, project_id, created_at DESC);
CREATE INDEX idx_runs_status ON agent_runs (tenant_id, status, created_at);跨租户引用需通过复合外键、RLS 和服务端授权共同防护；上面仅示意字段，不构成完整安全 DDL。状态变更应使用数据库事务、乐观并发控制与 Outbox 事件，防止数据库状态与队列消息不一致。事件序号必须由权威写入方按 Run 分配，不能由多个 Worker 各自推测。
14 · Studio 贯穿案例：选题 Agent 的执行工作台
14.1 任务背景
用户在 huaAgentStudy 项目中希望研究“Agent Platform 的运行控制产品设计”，选择工作空间共享的选题 Agent，并提供研究主题、目标读者、输出数量、参考范围和质量要求。该 Agent 可能调用检索工具，但不具备直接公开发布或向外部发送邮件的权限。
14.2 用户旅程
启动：项目首页点击“运行选题 Agent”，打开任务面板；默认选择已批准的 production 版本，填写研究目标、约束、输入资料并设置预算上限。预检：平台确认用户对项目、Agent、知识资源的使用权，检查检索连接和预算。执行：创建 Run 并进入工作台，显示“准备检索 → 检索资料 → 整理候选 → 生成结果”等可观察阶段；如果这些阶段由执行器实际报告，才展示其状态。干预：Agent 发现研究范围不明确，发出 waiting_input，用户补充“优先关注 Agent Platform”；运行继续。结果：Agent 输出五个候选选题及其理由，平台将结果登记为 Artifact；用户可在 F7 工作流中交给审核 Agent，或在 F10 产物中心查看。
14.3 异常路径
- 检索服务限流：展示“外部检索暂不可用”，按已声明策略等待、回退或失败，避免静默跳过证据要求。
- 用户点击取消：显示“取消中”，完成安全终止后变为“已取消”；保留已生成的部分资料并标注状态。
- 网络断开：Run 继续后台执行；页面恢复后通过事件游标补取，不重新创建任务。
- 预算耗尽：在安全点停止或请求追加预算，记录已发生费用。
- Agent 输出格式不符合 Schema：执行器可标记校验失败，或进入修复步骤；不能仅因模型返回文本就显示“成果合格”。
14.4 建议的页面布局
┌───────────────────────────────────────────────────────────────┐
│ 选题 Agent / Run #123 运行中 · 2分18秒 [请求取消] │
├───────────────────┬───────────────────────────────────────────┤
│ 任务信息 │ 活动时间线 / Agent 输出 │
│ Agent 版本 │ 10:02 任务开始 │
│ 输入资料 │ 10:03 检索完成（3 个来源） │
│ 预算与权限 │ 10:04 正在整理候选选题 │
│ 关联 Workflow │ │
├───────────────────┴───────────────────────────────────────────┤
│ 需要补充输入（仅等待时显示） / 结果预览 / 产物入口 │
└───────────────────────────────────────────────────────────────┘这个布局是信息架构草案，仍需通过真实用户任务测试确认密度、导航、移动端表现和操作优先级。
15 · 产品指标、开发路线与验收标准
15.1 产品指标
| 指标 | 定义 | 解释边界 |
|---|---|---|
| 启动成功率 | 合法请求最终创建 Run 的比例 | 与任务完成率分开 |
| 启动耗时 | 用户提交到返回 Run ID 的时间 | 不等于排队等待时间 |
| 首次反馈延迟 | 提交到首次有意义状态事件的时间 | 排除空心跳 |
| 任务完成率 | 达到 succeeded 的 Run 比例 | 不代表业务质量 |
| 审核通过率 | 通过业务审核的结果比例 | 依赖审核标准一致性 |
| 取消响应时间 | 请求取消到进入终态的时间 | 受工具可中断性影响 |
| 恢复成功率 | 可恢复 Run 成功继续的比例 | 仅针对支持恢复的 Run |
| 重复提交率 | 重复创建意图的请求比例 | 需区分重试与误操作 |
| 用户干预完成率 | 待输入/审批请求得到有效处理的比例 | 应考虑超时与拒绝 |
| 单 Run 成本 | 实际模型、工具与计算成本 | 需注明计量范围 |
15.2 分阶段开发
阶段 A：可运行闭环。 创建 Run、查询状态、保存输入与版本、后台执行、结果展示、基础失败处理。验收重点是刷新页面后任务仍可追踪。
阶段 B：可观察与可控制。 SSE 事件、取消请求、Run 历史、Attempt、错误分类、预算显示和审计。验收重点是网络中断、取消竞态和重复提交不破坏状态。
阶段 C：可干预与可恢复。 等待用户输入、审批、检查点、暂停恢复、精细化重试。验收重点是外部副作用不会因恢复而无意重复。
阶段 D：规模化与多端。 租户公平性、移动端体验、运行队列优化、批量任务、成本分析与更复杂的协作入口。验收重点是隔离、性能和可用性。
16 · 参考测试矩阵（待执行）
| 编号 | 场景 | 预期结果 |
|---|---|---|
| T01 | 合法输入创建 Run | 返回稳定 Run ID 与 queued 状态 |
| T02 | 缺失必填字段 | 字段级校验错误，不创建 Run |
| T03 | 同一幂等键重复提交相同请求 | 复用原 Run，不重复执行 |
| T04 | 同一幂等键提交不同请求 | 返回冲突错误 |
| T05 | 未授权用户启动 Agent | 拒绝创建并记录审计 |
| T06 | 跨租户查询 Run | 不返回其他租户信息 |
| T07 | Agent 版本渠道切换后启动 | 新 Run 固定解析后的版本 |
| T08 | 运行中渠道切换 | 已运行 Run 版本不变 |
| T09 | 资源连接失效 | 运行时授权拒绝或安全降级 |
| T10 | 预算不足 | 阻止启动或按策略提示 |
| T11 | SSE 断线重连 | 按游标补齐事件，不重复渲染 |
| T12 | 事件乱序或重复 | 客户端按序去重处理 |
| T13 | 排队状态取消 | 最终 cancelled 且未启动 Worker |
| T14 | 运行中取消 | 先显示 cancel_requested，再显示终态 |
| T15 | 取消与完成并发 | 只产生一个一致终态 |
| T16 | 不支持暂停的执行器 | 明确拒绝暂停请求 |
| T17 | 支持检查点的暂停与恢复 | 状态恢复且保留执行上下文 |
| T18 | 恢复前权限被撤销 | 禁止恢复或进入待处理状态 |
| T19 | 外部写操作超时后重试 | 避免未确认的重复副作用 |
| T20 | Worker 崩溃 | Run 可恢复或进入明确失败状态 |
| T21 | 用户补充输入过期 | 拒绝过期请求且不推进 Run |
| T22 | 非审批人提交审批 | 拒绝操作 |
| T23 | 审批后参数被替换 | 摘要校验失败，不执行工具 |
| T24 | 工具结果含恶意指令 | 不提升为系统权限 |
| T25 | 失败 Run 保留部分产物 | 标注未完成且权限受控 |
| T26 | 成功 Run 但业务审核失败 | 显示独立的审核状态 |
| T27 | 日志包含密钥或敏感数据 | 输出被脱敏或阻断 |
| T28 | 多个项目同时运行 | 状态、事件与成本归属正确 |
| T29 | 刷新或切换设备 | 通过 Run ID 恢复运行视图 |
| T30 | 重跑相同输入 | 产生新 Run 并标注复现限制 |
| T31 | API 返回 202 但队列暂不可用 | 通过持久化事务/outbox 补偿，Run 不丢失 |
| T32 | Run 已终态再次取消 | 返回幂等结果或明确状态冲突 |
| T33 | 大型输入文件 | 以资产引用处理，避免请求体过大 |
| T34 | 长任务无进度百分比 | 展示真实阶段与最近活动，不伪造进度 |
| T35 | 实际成本超过预估 | 明确展示估算误差并执行预算策略 |
| T36 | 用户只能访问 Run 而无产物权限 | 产物下载仍被独立授权控制 |
测试优先级建议：T01 - T10、T13 - T15、T20、T26、T28、T31 为初期核心验收；其他项目按能力开放阶段逐步执行。所有项目目前均为待执行测试设计。
17 · 局限、开放问题与研究反思
- Agent 的动态推理过程未必存在可精确量化的进度；产品不能为了视觉完整而伪造执行确定性。
- 任意时点暂停、取消与精确恢复依赖执行器、外部工具和检查点机制；不能承诺统一支持。
- 多模型与外部资源使重跑结果存在非确定性；版本固定只能改善追溯性，不能保证输出完全一致。
- 事件流的展示粒度与用户理解存在权衡：过多底层日志增加认知负担，过少信息又损害信任和可控性。
- 实时反馈中的敏感信息、模型内部推理内容与第三方数据需要严格分层授权。
- 长任务的通知、后台继续执行、移动端操作与跨设备状态一致性仍需实证研究。
- 不同 Agent 类型可能需要不同交互模式；对话式助手、批处理研究 Agent 与高风险操作 Agent 不应被强行套用同一套控制按钮。
跨章节契约修订说明（v1.3-r1，2026-11-01）
本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。
Run 产品状态与平台持久化状态映射： [平台设计决策] 本文原有 waiting_approval / waiting_input 是 UI 语义，对应 canonical waiting + status_reason=approval/human_input；pause_requested / cancel_requested 属于命令意图 desired_action，并非持久化主状态；取消进入执行收敛时使用 cancelling。timed_out 暂作为独立终态。本文原状态图保留作产品交互说明，不能直接生成数据库枚举。
状态转移与副作用： 统一使用 status_version 原子裁决取消与完成竞争；succeeded 不代表审核通过或交付完成；重试整个任务创建新 Run，步骤重试追加 Attempt。对邮件发送、付款或其他外部写操作，恢复前先核对结果，不能把 checkpoint 或 Worker 重试当成 exactly-once 保证。
附录 A：参考文献与原始资料
以下优先列出规范、标准与官方工程文档。它们支持特定技术原则，但不构成一套统一的 Agent Execution 产品标准；本文的产品分层与 Studio 方案是综合推导的参考设计。
- OpenAI, Agents SDK Documentation. openai.github.io/openai-agents-python - Agent 执行、工具、会话与追踪的工程参考。
- LangChain, LangGraph Documentation. docs.langchain.com/oss/python/langgraph/overview - 有状态 Agent 编排、持久化与 human-in-the-loop 的工程参考。
- Temporal, Documentation. docs.temporal.io - 持久执行、重试与工作流恢复的工程参考。
- MDN, Using server-sent events. developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events - SSE 事件流及浏览器行为。
- IETF, RFC 9110: HTTP Semantics. www.rfc-editor.org/rfc/rfc9110 - HTTP 方法与状态码语义。
- IETF, RFC 9457: Problem Details for HTTP APIs. www.rfc-editor.org/rfc/rfc9457 - 统一 API 错误表达的标准参考。
- OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html - HTTP API 契约规范。
- PostgreSQL, Documentation: Transaction Isolation. www.postgresql.org/docs/current/transaction-iso.html - 并发与事务一致性参考。
- PostgreSQL, Documentation: Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html - 行级隔离机制。
- OWASP, Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10 - Prompt Injection、敏感信息与工具风险参考。
- NIST, AI Risk Management Framework. www.nist.gov/itl/ai-risk-management-framework - 风险识别、治理与评估参考。
- Kubernetes, Jobs. kubernetes.io/docs/concepts/workloads/controllers/job - 后台任务与重试语义的对照参考；不意味着 Agent Run 等同 Kubernetes Job。
附录 B：研究证据、验证声明与适用边界
证据类型：本文对 HTTP、SSE、数据库事务、RLS 和部分持久执行机制的描述以对应标准或官方文档为依据；Run 产品模型、状态机、页面布局、接口命名、Studio 实现路线及测试矩阵为研究综合与工程设计建议，尚未获得真实部署或用户实验验证。
已核验与未核验的区分：本篇未执行外部文献的逐页在线核验，也未运行所列 SQL、API 或测试用例。参考链接为可供后续复核的官方资料入口；不应把参考设计视为现有平台的实际能力。
适用范围：适用于需要异步任务、运行追踪、用户控制与产物交付的 Agent Platform，尤其是研究报告 Studio 一类项目。对纯同步问答、实时机器人控制、受严格行业监管的高风险自动化，应按具体实时性、安全和合规要求重新设计。
后续研究接口：F7 研究多个 Agent 的协作产品；F8 研究运行监控、Trace 与指标；F9 研究 Agent 管理；F10 研究产物交付。后续应将本文的 Run 操作模型与实际 Studio 原型逐项对照，开展用户任务测试和故障注入验证。