Run 生命周期

识别 runId、取消执行并处理断连与终态。

​

管理 Run 生命周期

每次 POST /v1/agents/:agentId/runs 执行都会被分配一个唯一的 runId（UUID），用于传输层标识。该 ID 通过以下方式暴露：

• 响应头 X-Run-ID（SSE 和 JSON 响应都有）
• SSE 初始 system 事件的 runId 字段
• JSON 响应体的 runId 字段

​

取消 run

要显式取消仍在运行的请求：

POST /v1/runs/:runId/cancel

响应码与响应体：

场景	状态码	响应体
已触发取消	202	{ runId, state: "cancelling" }
重复取消（幂等）	202	{ runId, state: "cancelling" | "cancelled", reason }
run 已处于非取消的终态	409	{ runId, state: "completed" | "failed" }
未知或已过期的 runId	404	{ error: "Run not found" }

终态缓存 TTL 为 5 分钟，过期后重复取消返回 404。

​

SSE 取消语义

当 run 被取消时（显式 API 调用或客户端断连），SSE 流依次发送 cancelled 与 done 事件：

event: cancelled
data: {"runId":"...","reason":"client_request|disconnect"}

event: done
data: {}

• reason=client_request：显式调用 POST /v1/runs/:runId/cancel。
• reason=disconnect：SSE 客户端断开连接。

客户端断连等同于静默取消：关闭 SSE 连接会中止底层 Agent 执行。Runtime 不区分“主动取消”和“网络中断”，两者都会停止 run，以避免浪费 token。

​

范围边界

该 API 属于传输层能力。Runtime 不提供：

• 持久化的 Run 历史记录（请使用外部编排器）
• 重试或故障转移策略
• 可持久化的事件回放（不支持中途重连）
• GET 状态端点（终态通过响应本身传达）

​

关停语义

进程关停时的排空由包装 Runtime 进程的外部编排器（例如 agent-deployer）调用 RunRegistry.closeAll()，在收到 SIGTERM 时排空进行中的 run。Runtime 自身不安装信号处理器——容器级 SIGTERM/KILL 由编排器负责。