> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerone.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 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` 事件携带文本增量、思考片段和工具调用进度：

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

事件流示例：

```text theme={null}
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 级粒度的场景：

```bash theme={null}
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 响应返回完整结果：

```bash theme={null}
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"`） |

```json theme={null}
{
  "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 生命周期](/zh/runtime/run-lifecycle)。