Run API 实战

发起 Run、解析 SSE 事件流、处理各类事件、中断 Run、查询恢复的完整流程。

1. 发起 Run

POST /cells/{cellID}/run
Content-Type: application/json

{
  "actor": "alice",
  "session_id": "s-001",
  "agent_id": "assistant",
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [{"type": "text", "text": "分析这份报告的要点"}]
    }
  ]
}

必填字段：

actor：空 → ErrActorRequired
model：空 → ErrModelRequired

响应为 SSE 流（text/event-stream）。

2. SSE 事件类型

流式输出

事件	含义
`stream_delta`	模型文本增量输出
`thinking_delta`	推理内容增量

生命周期

事件	含义
`run_start`	Run 开始
`turn_start`	新轮次开始
`turn_end`	轮次结束
`done`	Run 正常完成
`error`	Run 错误
`interrupted`	Run 被中断

工具调用

事件	含义
`tool_start`	工具调用开始
`tool_progress`	工具执行进度
`tool_end`	工具调用完成

Plan

事件	含义
`plan_created`	计划创建
`plan_updated`	步骤状态更新
`plan_completed`	计划完成
`plan_interrupted`	计划中断

HITL

事件	含义
`approval_request`	需要用户审批
`hitl_pending`	HITL 等待中

3. 事件解析示例（Go）

for evt := range events {
    switch evt.Type {
    case engine.EventStreamDelta:
        // 追加到 UI 文本缓冲区
        buffer.WriteString(evt.Delta)

    case engine.EventToolStart:
        // 显示工具调用开始
        log.Printf("调用工具: %s", evt.ToolName)

    case engine.EventDone:
        // Run 完成，reason 说明终止原因
        log.Printf("完成: reason=%s", evt.Reason)

    case engine.EventError:
        // 区分可重试与不可重试错误
        if evt.Severity == "info" {
            // 不可重试（guardrail/budget/安全策略）
        } else {
            // 可重试（provider 瞬时错误）
        }
    }
}

4. Run 生命周期与 SSE 解耦

INV-RUN-DETACH：Run 生命周期始终与 SSE 连接解耦。

SSE 断开不会取消 Run
重连后通过事件重放续播：GET /cells/{cellID}/runs/{runID}/events?from_seq=N

取消 Run 的合法途径：

POST /cells/{cellID}/sessions/{sid}/interrupt（用户主动）
CycleDetector HITL 超时（真循环）
ErrorStreakDetector HITL 超时（伪进展）
外部 BudgetCheckFn 返回 Exhausted
Cell Stop（生命周期）

5. 中断 Run

POST /cells/{cellID}/sessions/{sid}/interrupt

中断后 Run 发出 EventDone("context_cancelled") 或 EventInterrupted。

6. 批量中断

POST /cells/{cellID}/sessions/interrupt-all

需要 admin token。中断 Cell 内所有正在运行的 Run。

7. 查询孤儿 Run

GET /cells/{cellID}/observe/runs?status=resumable

Cell boot 自动执行 MarkInterruptedSessions() + ListOrphanedRuns()（INV-CKPT-04），消费方无需手动调用。

8. 事件重放

GET /cells/{cellID}/runs/{runID}/events
Accept: text/event-stream

支持 ?from_seq=N 参数，SSE 重连后续播事件。