Runs API

Runtime Agent 执行与取消接口参考。

​

Runs API

POST /v1/agents/:agentId/runs 通过 Accept 头的内容协商（Streamable HTTP）在同一个端点上支持流式与阻塞响应。请求体至少提供 message；响应通过 X-Run-ID 头返回传输标识。

​

流式（SSE）

发送 Accept: text/event-stream 获取 token 级流式输出，partial_message 事件携带文本增量、思考片段和工具调用进度：

curl -N -X POST http://localhost:3000/v1/agents/assistant/runs \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message":"Hello"}'

事件流示例：

event: system
data: {"type":"system","subtype":"init",...}

event: partial_message
data: {"type":"partial_message","partial":{"type":"thinking","text":"Let me..."}}

event: partial_message
data: {"type":"partial_message","partial":{"type":"text","text":"Hello!"}}

event: partial_message
data: {"type":"partial_message","partial":{"type":"tool_use","tool_name":"Read",...}}

event: assistant
data: {"type":"assistant","message":{"role":"assistant","content":[...]}}

event: tool_result
data: {"type":"tool_result","result":{...}}

event: result
data: {"type":"result","subtype":"success",...}

event: done
data: {}

SSE 客户端必须处理 system、消息事件、cancelled、错误与 done，并在 done 后关闭消费循环。

​

SSE Block 模式

在请求体中设置 stream: "block"，SSE 只发送完整消息，不包含 partial_message 事件。适合需要流式推送但不需要 token 级粒度的场景：

curl -N -X POST http://localhost:3000/v1/agents/assistant/runs \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message":"Hello","stream":"block"}'

​

阻塞（JSON）

发送 Accept: application/json，以单个 JSON 响应返回完整结果：

curl -X POST http://localhost:3000/v1/agents/assistant/runs \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"message":"Hello"}'

​

错误响应（阻塞模式）

上游 LLM 失败（限流、认证失败、连接错误等）时，响应返回非 200 状态码并携带 state: "failed"，而不是看似成功的空结果：

状态码	含义
429	上游限流（errorType: "rate_limit"）
502	其他所有上游失败（如 errorType: "auth"、"error_during_execution"）

{
  "runId": "...",
  "sessionId": "...",
  "state": "failed",
  "error": "HTTP 429: too many requests",
  "errorType": "rate_limit",
  "errors": ["HTTP 429: too many requests"],
  "text": "",
  "usage": {},
  "numTurns": 0,
  "durationMs": 5
}

text 可能包含失败前已生成的部分输出。客户端应检查 HTTP 状态码（或 state / error 字段）区分成功与失败。通过 POST /v1/runs/:runId/cancel 取消的 run 仍返回 200 且 state: "cancelled"——取消优先于错误上报。

​

向后兼容

未提供 Accept 头时，仍支持旧的 stream 请求体字段：

stream 取值	行为
true 或 "raw"（默认）	SSE，包含 partial_message 事件
"block"	SSE，不包含 partial_message 事件
false	JSON 阻塞响应

新集成应优先使用 Accept 头方式（Streamable HTTP），它遵循标准 HTTP 内容协商。

​

取消 Run

POST /v1/runs/:runId/cancel

取消请求是幂等的，但终态缓存过期后会返回 404。详细状态码见 Run 生命周期。