运行入口与调试面：API、RunManifest 与 Developer Console

前置：外部能力适配：MCP 与 Workspace / Sandbox
核心问题：API、RunManifest、Developer Console 都围绕一次 Run，但它们分别负责发命令、固定版本还是解释发生了什么？

用户通过 API 创建和控制 Run，RunManifest 固定这次执行的版本基线，Developer Console 再从 canonical event/trace projection 展示时间线和失败节点。三者职责不同：API 发命令，Manifest 解释“当时跑的是什么”，Console 解释“实际发生了什么”。

API / Event Stream

API 创建/查询/取消/恢复 Run；Event Stream 只传领域事件，真正状态来自 StateStore，客户端断线不必等于 Run 消失。

API 暴露 create/get/cancel/resume/approve 等 command/query；Event Stream 提供观察但不是唯一事实源。长 Run 与 HTTP connection 生命周期分离。

RunManifest Assembly

Shadow Harness 的 Run Manifest 是 Run 创建时写入的不可变版本快照，记录 model/provider/settings、instruction/prompt revision、Tool catalog/schema、retrieval index、workspace base、runtime commit 与关键配置，使 Trace/Eval/Artifact 都能回到同一执行基线。

敏感 secret 只记录引用/版本，不记录值。

Developer Console Data Model

Console 是 Runtime 的观测窗口：timeline、DAG、context budget、tool/model spans、checkpoint、cost/eval；不应成为隐藏业务状态源。

从创建 Run 到 Console 展示

POST /runs
  ↓ create Run + immutable RunManifest
202 {run_id=r-42}
  ↓
Worker emits domain events
  ↓
StateStore / EventLog / TracePipeline
  ├─ GET /runs/r-42          → current projection
  ├─ /runs/r-42/events       → live observation
  └─ Developer Console       → DAG/timeline/context/cost

用户稍后打开 Console，不需要依赖当时那条 HTTP connection；它从 durable projection + trace 重建视图。Manifest 则让页面能明确显示“这个失败发生在 model X、tool catalog v12、workspace commit abc123”，避免用当前配置解释历史 Run。

Failure Modes

API 恢复请求没有校验 RunManifest / Workspace

症状： 客户端只带 run_id，服务直接绑定当前 workspace/config 继续执行。

为什么危险： Run 可能在不同代码、Tool catalog 或 workspace base 上继续，失去可复现性。

处理： resume 前校验 manifest/workspace identity；不兼容变化显式 migrate 或 fork。

Developer Console 发明第二套状态模型

症状： 前端重新推断 Run/Node/Tool 状态。

为什么危险： UI 成功而 Store/Trace 失败，调试失真。

处理： Console 消费 canonical events/view model；OTel exporter 也是同一 domain trace 映射。

Developer Console 反向成为事实来源

症状： 前端为了展示方便自行推导并持久化 node/run 状态。

为什么危险： UI 与 Runtime 形成第二套状态机，刷新或重放时产生冲突。

处理： Console 只读 Runtime event/trace projection；所有状态变化必须来自 backend domain event。

如何验证

Case	断言
改变 workspace commit/tool catalog 后 resume	系统拒绝直接继续，要求 migrate/fork；Console 显示 manifest mismatch。
Developer Console 发明第二套状态模型	同一 event log 回放，API/Console/OTel 的 operation/status 一致。
Developer Console 反向成为事实来源	模拟前端提交伪造 status 更新，断言 backend 拒绝，状态只能由 Runtime command/event 改变。

自测

1. Developer Console 显示一个 Run “完成”，它应该从 Runtime status 读事实还是从最后一条模型文本猜？
2. RunManifest 在 API 启动时固定哪些版本/配置，才能让同一次运行后续可追踪和复现？

Sources

• OpenAI Agents SDK — Running agents
• OpenAI Agents SDK — Results
• OpenAI Agents SDK — Tracing