P8 · 平台如何提供统一的 API 与 SDK？ - Platform API & SDK

所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何以稳定、安全、可演进的 API 与 SDK 契约向外部开发者和应用开放 Agent、Workflow、Run、资源、产物与管理能力，同时处理认证授权、异步执行、流式事件、幂等、版本兼容和开发者体验？

专题导读

本篇属 Technical Architecture。P8 研究平台的对外开发者接口层。P7 研究平台如何接入模型、工具与外部服务；P8 研究外部应用如何接入平台。前者是资源集成方向，后者是能力开放方向。P8 与 P1 Control Plane、P2 Execution Plane、P3 Registry、P5 Deployment、P6 Workflow 和 P10 Assets 都有交集，但其核心产物是公开契约及其长期兼容机制，不是把内部数据库和服务端函数原样暴露。

本篇将 API 视为平台的产品边界，将 SDK 视为该契约的类型化开发者适配层。参考方案以 HTTP JSON API、异步 Run、SSE 事件流、Webhook 回调、OpenAPI 契约和 TypeScript/Python SDK 为主；GraphQL、gRPC 等为可选扩展，不是必备条件。所有代码、指标、表结构与验收条目均为参考设计或待验证方案，并非已实现功能。

研究结论

1. API 是稳定的外部能力契约，不是内部服务的直接映射。 对外应围绕 Agent、Version、Deployment、Workflow、Run、Artifact 等资源组织操作，屏蔽执行器、队列和存储实现。
2. 长时间 Agent 任务必须采用异步语义。 创建 Run 立即返回标识和状态；客户端通过查询、事件流或 Webhook 获得进度与结果，不应依赖单次长连接完成所有业务。
3. 请求接受、任务成功、输出质量合格是三种不同状态。 HTTP 202 表示请求已接受，不表示 Agent 执行成功，更不表示结果通过质量审核。
4. SDK 不应创造独立业务语义。 SDK 封装认证、分页、重试、事件流、类型和错误，但以公开 API 契约为权威来源。
5. 幂等、权限与可观测性必须跨 API 和执行面闭环。 Idempotency-Key、request_id、run_id、trace_id 和实际权限决策应贯通网关、控制面、工作流与执行面。
6. 兼容性应被设计和测试，而不是仅靠版本号承诺。 公开字段、枚举、事件、错误、分页和 SDK 版本均需有明确演进规则。
7. Studio MVP 先做好少量高价值接口。 优先覆盖创建任务、获取状态、订阅事件、人工审批、读取产物、取消任务及权限校验，再逐步开放 Agent 构建与组织管理接口。

---

一、定义、边界与职责

1.1 Platform API 的定义

Platform API 是外部主体通过受支持的协议访问平台能力的契约集合，包括资源标识、操作、请求响应结构、认证授权、错误、异步行为、限流、版本与兼容性约定。API 可供平台自有前端、第三方服务、CLI、自动化脚本及 SDK 使用，但不意味着所有主体具有相同权限。

1.2 Platform SDK 的定义

SDK 是围绕 Platform API 构建的语言级开发工具包，通常提供客户端实例、类型、参数校验辅助、认证、分页迭代、重试策略、流式事件解析、错误映射与示例。SDK 的存在不应阻止开发者直接调用 HTTP API。

1.3 相邻组件的责任边界

组件	主要职责	P8 关系
P1 Control Plane	准入、授权、调度控制和治理决策	API 调用业务控制命令，不能绕过控制面
P2 Execution Plane	运行实际任务、工具和模型调用	API 不直接把任意用户输入送入不受控 Worker
P3 Agent Registry	Agent 定义与不可变版本	API 提供版本检索与发布操作，具体规则由 Registry 保证
P4 Development Services	Draft、校验、预览、构建	API/SDK 提供开发入口，不替代构建服务
P5 Deployment & Runtime	部署、实例、Run 生命周期	API 对外呈现稳定的部署与运行状态
P6 Workflow Management	工作流定义、调度和恢复	API 触发、查询和操作 Workflow Run
P7 Resource & Integration	外部资源接入与授权	API 暴露连接管理能力但不泄露密钥
P9 Extensibility	插件、扩展与生态	API 是插件可能使用的契约之一
P10 Platform Data & Assets	文件、产物与共享资产	API 返回授权范围内的资产元数据与访问方式
P11/P12	多租户与平台治理	所有接口继承隔离、配额与策略

1.4 API 不应承担的工作

API 网关不应执行复杂 Agent 推理、不应持有长时间工作流状态、不应替代审计存储、不应直接暴露数据库查询语言给普通用户。同步 API 可提供轻量校验和状态读取；高成本操作通过持久化任务完成。

二、API 产品面与资源模型

2.1 资源分组

API 资源	代表性操作	常见主体
Organizations / Workspaces	查询、创建、成员管理	管理员、团队成员
Agents / Agent Versions	列表、读取、草稿、发布	开发者、管理员
Deployments	创建、更新目标版本、停用	运维、开发者
Workflows / Workflow Versions	定义、发布、查询	开发者
Runs / Step Runs	创建、查询、取消、恢复	应用、用户、工作流服务
Approvals	获取待审批项、批准、驳回	被授权审批人
Artifacts	元数据、授权下载、版本引用	任务参与者
Resources / Connections	列表、连接、绑定、撤销	管理员、开发者
Usage / Audit	用量、配额、审计记录	管理员、审计员
Webhook Endpoints	创建、验证、轮换密钥、停用	开发者

资源目录不代表所有端点都应立即公开。应区分 public、partner、internal、admin 接口面，并分别管理授权、稳定性承诺和文档。

2.2 统一标识与归属

建议采用不可猜测的稳定标识（如 UUID/ULID 等）；标识不是授权凭据。每个对象需明确 organization_id、workspace_id、所有者、创建时间及生命周期状态。跨工作空间资源引用需要显式授权；不允许通过猜测 ID 绕过隔离。

2.3 URL 设计原则

推荐资源名使用复数、路径表达归属、动作使用清晰的子资源或命令端点。避免把状态机内部细节编码为大量不稳定 URL。示例：

GET    /v1/workspaces/{workspace_id}/agents
GET    /v1/agents/{agent_id}/versions/{version_id}
POST   /v1/deployments/{deployment_id}/runs
GET    /v1/runs/{run_id}
POST   /v1/runs/{run_id}/cancel
GET    /v1/runs/{run_id}/events
POST   /v1/approvals/{approval_id}/decisions
GET    /v1/artifacts/{artifact_id}
POST   /v1/webhook-endpoints

以上是示例契约，不能直接推断为某现有平台的官方 API。

三、整体技术架构

flowchart TB
  C[Web / CLI / SDK / External App] --> E[API Edge: TLS / WAF / Rate Limit]
  E --> A[Authentication & Authorization]
  A --> G[Public API / BFF]
  G --> CP[P1 Control Plane]
  G --> RG[P3 Registry]
  G --> DS[P4 Development Services]
  G --> WF[P6 Workflow Management]
  G --> AS[P10 Asset Service]
  CP --> DB[(Transactional DB)]
  CP --> Q[(Durable Queue)]
  Q --> EX[P2 / P5 Execution Workers]
  EX --> EV[(Run Events / Outbox)]
  EV --> S[Event Stream Service]
  EV --> W[Webhook Delivery]
  S --> C
  W --> C
  G --> O[Audit / Metrics / Tracing]

这是逻辑架构，不要求每个方框独立部署。MVP 可以在模块化单体内实现 API、控制面和服务模块，执行 Worker 与队列独立运行。对外响应结构应独立于内部数据表和队列消息格式。

3.1 读写分离的语义

读请求可以查询只读投影；写请求必须经过授权与领域校验，产生事务性状态变更。对于最终一致的状态查询，应在文档中说明可能存在短暂延迟，并提供稳定的 updated_at、sequence 或 revision 字段辅助客户端判断新旧。

3.2 事务性创建 Run

创建 Run 的核心是业务状态与任务投递一致性：在同一数据库事务内写入 Run、幂等记录和 Outbox 事件，由后台投递器发送队列。避免“接口返回成功但队列消息丢失”，也避免“队列已消费但数据库尚未提交”。Outbox 是一种设计模式，仍需通过去重、重试和监控验证其可靠性。

四、HTTP 契约与同步/异步操作

4.1 创建异步 Run

POST /v1/deployments/dep_123/runs HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: research-job-20261031-001

{
  "input": {"topic": "Agent Platform API design", "language": "zh-CN"},
  "metadata": {"project_id": "proj_123"},
  "client_reference_id": "research-001"
}

参考响应：

HTTP/1.1 202 Accepted
Location: /v1/runs/run_789
Content-Type: application/json

{
  "id": "run_789",
  "status": "queued",
  "deployment_id": "dep_123",
  "resolved_agent_version_id": "av_456",
  "created_at": "2026-10-31T15:00:00Z",
  "links": {"self": "/v1/runs/run_789", "events": "/v1/runs/run_789/events"}
}

202 Accepted 仅说明请求已被接受；若需要保证已持久化，服务必须在事务提交后再响应。对于不需要异步的简单读取/配置操作，可以使用普通同步 200/201。

4.2 Run 状态机

stateDiagram-v2
  [*] --> queued
  queued --> running
  queued --> cancelled
  running --> waiting_approval
  waiting_approval --> running
  waiting_approval --> cancelled
  running --> succeeded
  running --> failed
  running --> cancelling
  cancelling --> cancelled
  cancelling --> failed
  succeeded --> [*]
  failed --> [*]
  cancelled --> [*]

状态机是参考设计。实际实现还可能有 paused、timed_out、expired 等状态，必须给出合法转换与权限矩阵。取消是请求，不是瞬时完成保证；已经发出的外部副作用可能无法撤销。

4.3 查询结果与质量状态分离

{
  "id": "run_789",
  "status": "succeeded",
  "quality_review": {"status": "needs_revision", "review_id": "rev_001"},
  "output_artifact_ids": ["art_001"],
  "completed_at": "2026-10-31T15:05:00Z"
}

执行成功只意味着工作流按定义完成；审核不通过应使用独立的业务质量状态，而非误写成基础设施失败。

五、身份认证与授权

5.1 认证方式选择

• 用户交互式客户端：优先采用符合适用安全实践的 OAuth 2.0 / OpenID Connect 流程；公共客户端考虑授权码 + PKCE。
• 服务到服务：使用受限服务身份、短期访问令牌或合适的工作负载身份机制。
• 个人 API Key：可作为受限 MVP 方案，但需最小权限、可轮换、可撤销、不可记录明文，并明确泄露处理流程。

不能将 API Key 视为自动满足企业级认证要求；不得将高权限密钥放入浏览器前端、移动应用包或公开仓库。

5.2 授权决策维度

authorize(subject, action, resource, context)
  subject: user/service identity, organization membership
  action: runs.create / runs.cancel / artifacts.read / agents.publish
  resource: tenant, workspace, object ownership, sensitivity
  context: environment, policy, delegated scope, approval state

授权必须由服务端执行。即使客户端通过 SDK 类型检查，也不能替代权限检查。读取列表时同样要按租户和权限过滤；错误响应避免泄露其他租户资源是否存在。

5.3 委托授权与 Agent 身份

用户授权平台启动任务，不等于授予 Agent 任意访问用户所有资源的权限。运行时工具调用应使用与该 Run 绑定的受限授权上下文，区分发起者身份、平台服务身份和实际资源访问身份。撤销授权后应阻止后续调用；已完成的外部副作用不保证可逆。

六、API 版本与兼容性

6.1 版本维度不可混淆

版本	例子	控制对象
Platform API version	/v1	外部接口契约
SDK package version	1.x.y	语言客户端实现
Agent Version	av_456	Agent 定义快照
Workflow Version	wv_123	工作流定义快照
Deployment Revision	dr_789	部署配置快照
Event schema version	event_version: 1	事件载荷格式

升级 SDK 不应隐式改变运行中的 Agent Version；发布 Agent Version 也不意味着 API 路径需要升级。

6.2 兼容性规则

通常可兼容的变化包括：新增可选响应字段、新增可选请求字段、增加新端点；但客户端如果错误地采用“拒绝未知字段/枚举”，仍可能发生故障。高风险变化包括：删除或重命名字段、改变字段类型、改变状态含义、修改分页游标语义、增加强制请求字段、改变错误码或 Webhook 签名方式。

对外应明确：废弃通知、迁移指南、支持窗口、变更日志、契约测试、弃用字段的实际移除策略。不要仅依靠“遵循 SemVer”来替代行为兼容测试。

6.3 ETag 与并发控制

修改 Draft、配置或 Webhook 时可使用 ETag / If-Match 防止覆盖并发编辑；失败返回 412 Precondition Failed。已发布的不可变 Agent Version 不允许原地修改。

七、错误模型与可恢复性

7.1 统一错误信封

可采用 RFC 9457 Problem Details 思路，并扩展稳定的业务错误码：

{
  "type": "https://docs.example.invalid/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Workspace concurrent run limit reached",
  "code": "WORKSPACE_RUN_QUOTA_EXCEEDED",
  "request_id": "req_abc",
  "retryable": true,
  "retry_after_seconds": 30
}

示例中的 .invalid 域名是保留的占位符，不是真实文档地址。不要将内部栈追踪、凭据、完整 Prompt 或其他租户信息放入公开错误。

7.2 HTTP 状态与业务错误

HTTP 状态	典型场景	注意
400	JSON 解析失败或无效参数	返回字段级错误
401	未认证或令牌失效	不透露敏感认证细节
403	已认证但权限不足	与 404 隐藏资源策略一致
404	资源不存在或不可见	防止枚举
409	状态冲突、幂等键冲突	提供可操作错误码
412	If-Match 前置条件失败	支持刷新重试
422	结构正确但业务校验失败	明确违反的业务规则
429	限流或配额不足	尽可能提供 Retry-After
500/503	服务内部故障或不可用	标明重试安全条件

Run.status=failed 通常仍可通过 GET /runs/{id} 返回 200，因为查询请求本身成功，不能把任务失败误映射为查询 HTTP 500。

7.3 重试边界

客户端可对安全的读取请求使用指数退避与抖动；写请求只有在服务支持并验证了幂等机制时才能自动重试。对 POST /runs，同一租户、端点、幂等键和请求摘要应解析到同一逻辑结果；相同键对应不同请求内容必须报冲突。幂等记录需有明示的保留期限。

八、分页、过滤与查询

列表 API 应支持受限 limit、稳定排序和不透明 cursor。游标不能包含可被篡改的明文授权上下文；授权仍需在每次请求重新检查。过滤字段与排序字段应有白名单和索引支持，避免无限制表达式导致昂贵查询或注入风险。

{
  "data": [{"id": "run_1", "status": "running"}],
  "pagination": {"next_cursor": "opaque-token", "has_more": true}
}

对于频繁变化的数据集，应说明游标分页是否保证快照一致性；如果不保证，客户端必须容忍新增、删除或短暂重复，并通过稳定 ID 去重。

九、流式事件：SSE、WebSocket 与轮询

9.1 三种模式比较

机制	适用场景	关键限制
Polling	简单状态读取、低频客户端	延迟与请求开销
SSE	服务端单向推送文本事件、运行进度	代理超时、断线续传、事件保留
WebSocket	双向实时控制、协同编辑	连接状态、认证续期、复杂基础设施

MVP 可采用 GET /runs/{id} + SSE；如无稳定事件流基础设施，先用轮询也合理。不要为了“实时”引入无法保障恢复语义的长连接。

9.2 SSE 事件契约

id: 1042
event: run.step.completed
data: {"event_version":1,"run_id":"run_789","step_run_id":"step_3","sequence":1042,"timestamp":"2026-10-31T15:03:00Z"}

id: 1043
event: run.completed
data: {"event_version":1,"run_id":"run_789","status":"succeeded","sequence":1043,"timestamp":"2026-10-31T15:05:00Z"}

客户端需支持断线重连、按 sequence 去重、事件缺口检测、重新查询权威 Run 状态。Last-Event-ID 是否可用取决于服务端是否保留可重放事件；若无事件重放能力，不应承诺无损续传。

9.3 事件与状态的关系

事件流用于观察变化，持久化状态用于权威查询。 事件可能重复、延迟、乱序或因保留期限而丢失。前端在重连、进入页面或检测序列缺口时，应重新拉取 Run/Step 的最新状态。对用户可见的 token 增量流可单独设计，不应与审计事件等同。

十、Webhook 回调设计

Webhook 适合第三方系统在任务完成、审批产生或产物准备就绪时获得通知。建议提供 endpoint 注册、事件订阅、签名密钥轮换、投递历史、失败重试和停用能力。

{
  "event_id": "evt_123",
  "event_version": 1,
  "type": "run.completed",
  "occurred_at": "2026-10-31T15:05:00Z",
  "workspace_id": "ws_123",
  "data": {"run_id": "run_789", "status": "succeeded"}
}

10.1 安全与投递语义

• 使用 HTTPS，并对原始请求体和时间戳生成 HMAC 签名；接收方进行常量时间比较和时间窗口校验。
• Webhook 投递通常采用至少一次语义，接收方必须根据 event_id 去重。
• 平台应限制回调目标，防范 SSRF（私有地址、元数据服务、重定向与 DNS 变化等），并设置连接超时、大小限制与重试上限。
• 不应将敏感产物全文推送给任意回调；优先发送事件元数据及可授权访问的资源引用。
• 重试结束后的死信与人工重放需要可审计；人工重放也可能产生重复事件。

十一、SDK 架构与开发者体验

11.1 SDK 分层

flowchart TB
  U[Developer Application] --> R[Typed Resource Clients]
  R --> H[HTTP Transport]
  R --> S[Stream / Pagination Helpers]
  H --> AU[Auth Provider]
  H --> RT[Retry / Timeout / Idempotency]
  H --> ER[Error Mapping]
  H --> OT[Tracing / Request IDs]
  H --> API[Public Platform API]
  S --> API

11.2 TypeScript 参考用法

// 伪代码：演示期望的开发者体验，非已发布 SDK
const client = new PlatformClient({
  tokenProvider: async () => process.env.PLATFORM_TOKEN!,
  timeoutMs: 15_000,
});

const run = await client.runs.create({
  deploymentId: "dep_123",
  input: { topic: "Agent Platform API" },
  idempotencyKey: "research-001",
});

for await (const event of client.runs.events(run.id)) {
  if (event.type === "run.completed") break;
}

const latest = await client.runs.retrieve(run.id);

11.3 Python 参考用法

# 伪代码：演示 SDK 形态，非可直接安装的包
from example_platform import PlatformClient

with PlatformClient.from_env() as client:
    run = client.runs.create(
        deployment_id="dep_123",
        input={"topic": "Agent Platform API"},
        idempotency_key="research-001",
    )
    result = client.runs.wait(run.id, timeout_seconds=600)
    print(result.status)

wait() 只是客户端便利方法，底层仍是异步 Run 与状态查询；超时退出等待不等于取消服务端任务。SDK 应提供同步/异步客户端（按语言惯例）、显式超时、取消令牌、类型提示、资源清理和敏感信息日志脱敏。

11.4 生成 SDK 与手写 SDK

OpenAPI 代码生成适合提供基础类型和接口客户端，但生成器可能无法自动表达复杂事件流、幂等约束、长轮询和领域错误。可采用“OpenAPI 生成核心客户端 + 少量手写高层辅助函数”的模式，配合契约测试防止文档与实现漂移。

11.5 开发者门户

最小可用文档应包含：快速开始、身份认证、首个 Run、状态查询、事件流、审批、产物下载、错误与重试、分页、限流、Webhook 签名验证、SDK 示例、版本与弃用策略。沙箱环境与可复制示例应使用虚构凭据，禁止文档嵌入真实密钥。

十二、限流、配额、成本与服务保护

应区分请求速率限制、并发 Run 配额、模型 Token/费用预算、存储配额与Webhook 投递限制。API 网关的每分钟请求限制不能代替控制面的计算资源预算；反之亦然。

维度	控制点	返回/观测
API QPS	Edge / API Gateway	429、Retry-After
Run 并发	Control Plane	409/429 或排队，需固定契约
Token/费用	Model Gateway / Governance	用量记录、预算拒绝
Artifact 存储	Asset Service	配额错误、生命周期策略
Webhook 重试	Delivery Service	投递状态、死信队列

限流应以租户、工作空间、应用与服务身份组合评估，避免共享 IP 导致误伤；公开限制应清晰，并保留运维调整空间。

十三、可观测性、审计与安全

13.1 关联标识

request_id → run_id → workflow_run_id → step_run_id → attempt_id
                    ↘ trace_id / span_id

request_id 关联入口请求，trace_id 关联分布式调用，run_id 关联持久化业务执行。它们可以相关但不可相互替代。对外暴露的 trace 信息需遵守租户与敏感信息策略。

13.2 关键指标

建议记录 API 请求量、P50/P95/P99 延迟、4xx/5xx、认证失败、授权拒绝、幂等命中与冲突、Run 创建成功率、事件流断线率、Webhook 延迟和重试次数、SDK 版本分布。指标应按租户适度聚合，避免高基数字段导致成本失控。

13.3 审计记录

关键写操作包括发布版本、修改部署、创建/取消 Run、审批决定、授权变更、Webhook 密钥轮换、产物共享。审计至少包含主体、动作、资源、时间、结果、关联请求与必要的变更摘要；不得直接保存敏感令牌、密钥或未经治理的原始输入。

13.4 威胁模型

威胁	风险	控制建议
BOLA / IDOR	跨租户读取 Run 或 Artifact	对象级服务端授权与负向测试
API Key 泄露	非授权调用与费用损失	最小权限、轮换、撤销、异常检测
重放写请求	重复创建 Run / 外部副作用	幂等键、签名时间窗、去重
Webhook SSRF	访问内部网络	目标校验、网络出口隔离、重定向限制
恶意或过大输入	成本耗尽、服务拒绝	请求大小、速率、预算、Schema 校验
事件流越权	泄露任务输出	连接建立及重连时鉴权
SDK 供应链风险	客户端凭据泄露	依赖锁定、发布签名、包来源核验
Prompt/工具输出注入	越权调用与错误决策	P7 工具授权与执行面策略复核

十四、数据契约、OpenAPI 与事件规范

14.1 OpenAPI 最小示例

openapi: 3.1.0
info:
  title: Example Agent Platform API
  version: 1.0.0
paths:
  /v1/runs/{run_id}:
    get:
      operationId: getRun
      parameters:
        - in: path
          name: run_id
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Run state
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id: {type: string}
                  status:
                    type: string
                    enum: [queued, running, waiting_approval, cancelling, succeeded, failed, cancelled]
        '401': {description: Unauthenticated}
        '404': {description: Not found or not visible}

这是局部示例，不构成完整可上线的 OpenAPI 文件。实际还应定义 security schemes、请求体、错误 schema、分页、可空字段、示例和版本演进规则。

14.2 事件规范

建议建立统一的事件信封：event_id、event_version、type、occurred_at、tenant/workspace、resource_id、sequence、data。事件类型应稳定且文档化。内部事件总线消息与公开 Webhook 事件可采用不同 schema，避免内部实现变化破坏外部兼容。

14.3 契约治理流水线

修改 API Schema
  → 静态校验 / lint
  → 与上个公开版本进行兼容性差异检查
  → 生成客户端类型
  → 服务端契约测试
  → SDK 集成测试
  → 文档示例测试
  → 发布候选 / 灰度
  → 正式发布 / 监控

契约测试必须包含错误路径和权限路径，而不只是正常请求。API 文档应与版本化代码一起审查和发布。

十五、研究报告 Studio 的贯穿案例

15.1 用户场景

Studio 用户在 Web 页面创建研究项目，选择工作流模板，提交研究主题。平台依次执行选题、审核、深度调研、分析、写作、人工确认和交付。用户可能关闭浏览器、切换设备或通过外部系统读取结果。

15.2 最小 API 组合

操作	端点示例	关键语义
启动研究	POST /v1/workflows/{id}/runs	幂等、异步、固定 Workflow Version
查询任务	GET /v1/runs/{id}	权威状态与版本引用
订阅进度	GET /v1/runs/{id}/events	SSE，重连后回查
查询待审批	GET /v1/runs/{id}/approvals	仅返回可见审批
提交审批	POST /v1/approvals/{id}/decisions	权限、幂等、状态校验
获取成果	GET /v1/runs/{id}/artifacts	元数据与授权下载
取消任务	POST /v1/runs/{id}/cancel	异步取消请求

15.3 Studio 端到端时序

sequenceDiagram
  participant UI as Studio Web
  participant API as Platform API
  participant CP as Control Plane
  participant WF as Workflow Service
  participant EX as Execution Worker
  participant ES as Event Service
  UI->>API: POST /workflows/{id}/runs + Idempotency-Key
  API->>CP: AuthZ + quota + version resolution
  CP->>WF: Persist Run + outbox
  WF-->>API: run_id, queued
  API-->>UI: 202 Accepted
  UI->>ES: Subscribe /runs/{id}/events
  WF->>EX: Dispatch eligible step
  EX-->>WF: Step result / artifact refs
  WF->>ES: Persist state event
  ES-->>UI: run.step.completed
  WF-->>ES: approval.requested
  ES-->>UI: approval.requested
  UI->>API: POST approval decision
  API->>WF: Validate approver + transition
  WF->>EX: Resume downstream steps
  WF->>ES: run.completed
  ES-->>UI: run.completed
  UI->>API: GET /runs/{id}/artifacts
  API-->>UI: Authorized artifact metadata

15.4 前端状态设计

前端可维护 serverState（来自 API 的权威状态）、eventBuffer（增量更新）与 localUIState（折叠、筛选、编辑草稿）。不能仅依赖 SSE 消息推导永久业务状态。人工审批必须由后端判断是否仍有效；页面上显示的按钮不构成授权。

15.5 版本与重试的实际例子

选题 Agent v1 运行中发布 v2：旧 Run 固定 v1，新 Run 依据部署渠道解析 v2。客户端断网后重试创建请求：相同幂等键与相同请求应返回同一 Run，而不是重复创建两个研究项目。审批按钮重复点击：第二次提交应得到幂等结果或明确状态冲突，不得重复推进下游任务。

15.6 MVP 实施顺序

阶段 A：最小可用闭环。 Token 认证、工作空间隔离、创建 Run、查询状态、取消、产物列表、统一错误、请求关联标识。

阶段 B：交互体验。 SSE 事件、审批接口、幂等键、分页、基础 TypeScript SDK、Webhook 完成通知。

阶段 C：开发者平台化。 OpenAPI 自动生成、Python SDK、公开文档门户、应用凭据与细粒度权限、契约兼容测试。

阶段 D：生态与规模。 多租户配额、细粒度用量计费、SDK 版本治理、Webhook 投递平台、外部合作伙伴接入。

阶段划分是建议，不代表已经实现。若 Studio 当前仍以假数据演示为主，应先从真实后端 Run 生命周期和权限边界入手，不应优先建设完整开发者门户。

十六、工程验证与验收矩阵

以下均为待执行测试，不代表已通过。

编号	场景	预期验收点
T01	未带令牌访问受保护接口	返回 401，不泄露内部信息
T02	无权限访问其他工作空间 Run	拒绝访问，不能通过 ID 枚举
T03	相同幂等键与相同请求重复创建	返回同一逻辑 Run
T04	相同幂等键与不同请求体	明确冲突，不复用错误结果
T05	创建 Run 后队列短暂不可用	Run 可恢复投递，无丢单
T06	创建成功后客户端断网	可通过幂等键找回结果
T07	Run 执行失败后查询	HTTP 查询成功，业务状态为 failed
T08	重复取消 Run	状态稳定，不重复产生副作用
T09	取消与完成并发	状态转换一致、可解释
T10	SSE 断线重连	去重、补偿或明确要求回查
T11	SSE 事件乱序/重复	客户端状态不回退
T12	SSE 授权撤销后重连	拒绝继续订阅
T13	Webhook 发送失败	按策略重试并记录投递
T14	Webhook 重复投递	接收方可依据 event_id 去重
T15	Webhook 签名错误或过期	接收方拒绝
T16	Webhook 目标指向内网地址	平台阻断 SSRF
T17	SDK 超时等待	只停止客户端等待，不误取消 Run
T18	SDK 自动重试写请求	仅在幂等条件满足时重试
T19	API 新增可选字段	旧 SDK 仍可工作
T20	API 删除旧字段	兼容性检查阻止无计划发布
T21	If-Match 与并发编辑冲突	返回 412，防止静默覆盖
T22	大量分页与复杂过滤	限制资源消耗，无越权
T23	触发工作空间并发配额	返回文档化的排队/拒绝语义
T24	人工审批重复提交	不重复推进工作流
T25	Agent Version 更新期间运行	旧 Run 仍固定已解析版本
T26	Artifact 下载链接过期或撤权	不能继续访问受保护内容
T27	Trace 与审计关联	可从 request_id 定位 Run 和审批记录
T28	错误响应与日志脱敏	不泄露密钥、令牌或敏感原文

16.1 建议验收指标（待实测后确定）

不预先宣称 P95 延迟、成功率或可用性达标。应在实际负载下测量 API P95/P99、Run 创建到入队延迟、SSE 重连恢复时间、Webhook 成功投递比例、跨租户越权测试结果和 SDK 契约测试通过率。阈值需要由 Studio 的真实业务量、预算和用户体验目标共同确定。

十七、常见误区与架构决策

误区一：SDK 就是 API。 SDK 是调用接口的语言封装；公开 API 才是跨语言、跨客户端的稳定契约。

误区二：API 返回 200 就代表 Agent 任务成功。 HTTP 请求状态与异步任务状态属于不同层次；还需区分业务质量审核。

误区三：流式输出可以替代持久化状态。 SSE/WebSocket 连接可能中断，必须有可查询的权威 Run 状态。

误区四：所有 POST 都可以自动重试。 没有明确幂等保障的写请求可能重复创建任务或产生外部副作用。

误区五：API Key 是权限模型。 API Key 只是认证凭据的一种形式，授权还需要租户、资源、动作和上下文检查。

误区六：版本路径 /v1 足以保证兼容。 仍需契约测试、弃用策略和行为稳定性管理。

误区七：Webhook 是可靠的一次性消息。 实际设计应假设重复投递、延迟与接收方不可用，并支持去重。

17.1 建议优先记录的 ADR

1. REST + SSE 是否作为初期公开接口的主协议。
2. API Gateway 与应用层授权如何分工。
3. Run 创建事务与 Outbox 的一致性策略。
4. API Key 与 OAuth 何时切换或并存。
5. 幂等键范围、请求摘要和保留期。
6. 事件流保留期与断线重连语义。
7. Webhook 安全、重试和签名轮换策略。
8. OpenAPI 生成 SDK 与手写辅助层的边界。
9. API 兼容性承诺与弃用窗口。
10. 产物下载采用代理流还是短期授权 URL。

十八、专题总结与后续衔接

P8 将平台内部的 Agent、Workflow、Run、资源与产物能力转换为可供外部应用长期依赖的稳定契约。其核心不是端点数量，而是身份、权限、异步语义、事件可靠性、错误、版本、SDK 和文档之间的一致性。

P9 将进一步研究插件、扩展与第三方生态：哪些扩展点应被公开，插件如何安装、授权、隔离和升级，以及插件与 API、SDK、P7 资源连接器之间的关系。P8 的接口是 P9 的基础，但不能把插件机制简单等同于公开 REST API。

---

跨章节契约修订说明（v1.3-r1，2026-11-01）

本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见 04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。

HTTP 与平台契约分层： [标准已核验] RFC 9110 的 202 Accepted 表示请求受理，不意味着 Run 执行完成；建议 POST /runs 返回 run_id、execution_status、status_url。Idempotency-Key 的作用域、TTL、请求摘要与 409 冲突策略属于[平台设计决策]，不能仅援引 RFC 9110 证明。

统一幂等建议： (tenant_id, method, route, key) 唯一约束；同摘要返回同一逻辑 Run；不同摘要冲突；保留期和过期重放行为须公开说明。SDK 只在写操作具备明确幂等保障时自动重试。waiting_approval 等产品态在 API 中统一表示为 execution_status=waiting, status_reason=approval；执行、审核、交付各自查询。

附录 A：参考文献与原始资料

以下以规范和官方文档作为可核验入口；持续更新的网页需在工程实施时确认具体版本。本文参考架构并非任何单一标准的强制实现。

1. IETF RFC 9110, HTTP Semantics：<www.rfc-editor.org/rfc/rfc9110>。HTTP 方法、状态码与语义。
2. IETF RFC 9457, Problem Details for HTTP APIs：<www.rfc-editor.org/rfc/rfc9457>。标准化错误表示。
3. IETF RFC 6749, OAuth 2.0 Authorization Framework：<www.rfc-editor.org/rfc/rfc6749>。授权框架背景。
4. IETF RFC 9700, Best Current Practice for OAuth 2.0 Security：<www.rfc-editor.org/rfc/rfc9700>。OAuth 安全实践。
5. IETF RFC 7636, Proof Key for Code Exchange：<www.rfc-editor.org/rfc/rfc7636>。PKCE 机制。
6. OpenID Connect Core：<openid.net/specs/openid-connect-core-1_0.html>。身份层与 ID Token 语义。
7. OpenAPI Specification：<spec.openapis.org/oas/latest.html>。HTTP API 描述与工具生态。
8. JSON Schema：<json-schema.org/specification>。数据结构校验。
9. WHATWG HTML Standard, Server-sent events：<html.spec.whatwg.org/multipage/server-sent-events.html>。SSE 事件格式与连接机制。
10. IETF RFC 6455, The WebSocket Protocol：<www.rfc-editor.org/rfc/rfc6455>。双向实时通信。
11. IETF RFC 9111, HTTP Caching：<www.rfc-editor.org/rfc/rfc9111>。HTTP 缓存语义。
12. OpenTelemetry Documentation：<opentelemetry.io/docs>。Trace、Metric、Log 与上下文传播。
13. OWASP API Security Top 10：<owasp.org/API-Security>。对象级授权、资源消耗等 API 风险。
14. CloudEvents Specification：<cloudevents.io>。事件信封与互操作参考；本文未要求全部公开事件必须采用 CloudEvents。
15. PostgreSQL Documentation：<www.postgresql.org/docs>。事务、并发控制与 Outbox 参考实现的数据库基础。
16. Kubernetes API Concepts：<kubernetes.io/docs/reference/using-api/api-concepts>。资源 API、版本与并发更新的参考案例；不意味着 Agent Platform 必须使用 Kubernetes 风格 API。
17. Google API Improvement Proposals (AIPs)：<aip.dev>。API 资源设计、分页和长时间操作的设计参考；不作为通用强制标准。
18. AsyncAPI Specification：<www.asyncapi.com/docs/reference/specification/latest>。异步消息与事件接口描述的可选参考。

引用与证据说明：标准文献支持其各自定义的协议或设计方法；本文资源模型、Run API、状态机、Studio 时序、测试矩阵和阶段路线是综合工程建议，不应被误写为标准强制要求。文中未对厂商实时 API 功能、价格或服务 SLA 进行核验。

附录 B：研究证据、验证声明与适用边界

内容	证据属性	验证状态
HTTP、OAuth、OpenAPI、SSE、RFC 9457	公开规范	提供官方原文入口；未进行实现一致性测试
Platform API 资源划分与 URL 示例	工程参考设计	未部署
Run 异步创建、Outbox 与幂等策略	架构推演与成熟模式借鉴	未执行故障注入或压测
SSE 续传、Webhook 投递与签名	协议结合工程设计	未完成真实集成验证
TypeScript / Python SDK 示例	接口体验示意	伪代码，非可安装软件包
Studio 场景与实施路线	场景化推演	需依据真实代码库调整
28 项工程测试	待执行验收计划	未执行，不得表述为通过
性能、成本、稳定性指标	需要真实负载与运营数据	未测量，不设未经验证的达标声明

适用范围：适用于需要向自有前端、自动化脚本、第三方应用和合作伙伴开放 Agent / Workflow / Run 能力的 Agent Platform。单用户内部工具可以缩小接口规模，但仍需明确身份、错误、任务状态、幂等和资源权限。金融、医疗、政府等敏感场景应额外评估合规、数据驻留、审计留存和行业认证要求。

最终自检：专题名称与 v1.3 目录一致；明确 P7/P8 边界；包含定义、对象、架构、API、SDK、身份授权、版本、异步、流式、Webhook、可靠性、Studio 案例、28 项待验证测试和证据声明；未宣称真实部署或测试通过。