# HTTP API

rungent 在你的源站上提供的每个端点：各自如何认证，一次运行推送的 AG-UI 事件，有哪些中断、如何回答，以及回答和错误的结构。

rungent 在你自己的源站上提供这些路径。内嵌的运行时在你的进程里直接作答；使用 `rungent serve` 时，由你的代理转发。`/rungent/v0` 下的路径都使用 JSON，只有两个推送事件流的端点例外。`rungent/client` 是覆盖全部接口的类型化客户端。

## 端点一览

| 端点 | 调用方 | 用途 |
|---|---|---|
| `POST /rungent/v0/threads` | 用户 | 创建对话：`{title?}` → `201 {id, title, createdAt}`。 |
| `GET /rungent/v0/threads?cursor=` | 用户 | 用户的对话，最新的在前，每页 20 条，带 `next`。 |
| `GET /rungent/v0/threads/{id}` | 用户 | 一个对话，含 AG-UI `messages` 和未答复的 `interrupts`。 |
| `PATCH /rungent/v0/threads/{id}` | 用户 | 重命名：`{title}`，1 到 200 个字符。 |
| `DELETE /rungent/v0/threads/{id}` | 用户 | 取消其运行，并连同其中的一切删除；`204`。 |
| `POST /rungent/v0/threads/{id}/runs` | 用户 | 开始一次运行；回答是它的事件流（SSE）。 |
| `GET /rungent/v0/threads/{id}/events?after={seq}` | 用户 | 重放 `seq` 之后的事件，再实时跟随（SSE）。 |
| `POST /rungent/v0/runs/{id}/cancel` | 用户 | 取消一次运行：`202 {id, status: "cancelling"}`。 |
| `PUT /rungent/v0/threads/{id}/messages/{messageId}/feedback` | 用户 | 给助手的一条消息评分：`{rating: "up" \| "down", comment?}`。 |
| `GET /rungent/v0/feedback?since=&limit=&cursor=` | `rungent:admin` | 租户内的评分，最早的在前。 |
| `GET /rungent/v0/info` | 任何人 | `{name}`：助手的名字。 |
| `GET /rungent/v0/catalog` | 用户 | 这个用户能看到的操作，及其输入 schema。 |
| `GET /rungent/v0/search?q=&limit=&types=` | 用户 | 联邦搜索。 |
| `GET /rungent/v0/settings` | 用户 | 当前生效的模型链，不含密钥。 |
| `PUT`, `DELETE /rungent/v0/settings` | `rungent:admin` | 替换或清除保存的模型链。 |
| `POST /rungent/v0/tasks/{taskId}` | 你的 API | 完成一个延后任务。 |
| `POST /rungent/v0/generate` | 你的 API | 为你的某项任务做一次模型生成。 |
| `/mcp` | 用户 | 基于 streamable HTTP 的 MCP。 |
| `GET /skill.md`, `GET /llms.txt` | 任何人 | 根据调用方的目录生成、给 Agent 读的文档。 |
| `GET /.well-known/rungent-keys.json` | 任何人 | rungent 的签名公钥，供查验。 |
| `GET /.well-known/oauth-protected-resource/mcp` | 任何人 | 配置了授权服务器时，MCP 的 OAuth 元数据。 |

协议版本是 `rungent/0`；小版本仍可能改动它，[更新日志](changelog.md)列出了每一处破坏性变更。

## 认证

用户的请求带着你的应用已经在用的凭据：`Authorization` 头、`Cookie` 头，或两者都有。rungent 把它们转发给你的身份操作，以得知用户是谁（[以用户身份调用](acting-as-the-user.md#who-the-user-is)）。两者都没有，或被你的身份操作拒绝，就返回 `401 unauthorized`。一个对话属于创建它的 `(subject, tenant)`；其他人访问得到 `404`。

你的 API 自己发起的调用，即 `POST /rungent/v0/tasks/{taskId}` 和 `POST /rungent/v0/generate`，改为携带 [`Rungent-Host-Assertion`](#host-assertions)。

对于以 cookie 登录的用户，rungent 拒绝其他站点可以代为发起的请求。带 `Sec-Fetch-Site: cross-site` 的 `POST`、`PUT`、`PATCH` 和 `DELETE` 一律返回 `403 cross_site`。除 `/mcp` 外，请求体必须是 `application/json`，否则返回 `415 unsupported_media_type`。

## 错误

事件流之外的错误都是 `{"error": {"code", "message"}}`：

| 状态码 | `code` | 何时出现 |
|---|---|---|
| 400 | `invalid_request` | 请求体或某个查询参数无效；message 会说明是哪个。 |
| 401 | `unauthorized` | 没有凭据，或被你的身份操作拒绝。 |
| 401 | `rungent_assertion_invalid` | 完成任务或宿主任务时没有有效的 `Rungent-Host-Assertion`。 |
| 403 | `forbidden`, `cross_site` | 需要 `rungent:admin`；或是跨站写请求。 |
| 404 | `not_found`, `session_not_found` | 对这个调用方而言，没有这个对话、消息、运行或任务；未知的 MCP 会话。 |
| 409 | `run_active`, `task_closed` | 对话已有一次运行在进行；任务已完成或已取消。 |
| 415 | `unsupported_media_type` | 请求体不是 `application/json`。 |
| 422 | `invalid_output` | 宿主任务的回答修复一次后仍不符合其 `schema`。 |
| 502 | `host_unavailable` | rungent 读不到你的 OpenAPI 文档。 |
| 503 | `settings_unreadable`, `model_unavailable` | 设置是用一个已丢失的密钥加密的；没有模型能回答宿主任务。 |
| 504 | `timeout` | 宿主任务超过了运行超时。 |
| 500 | `internal` | 其他情况。 |

## 开始一次运行

`POST /rungent/v0/threads/{id}/runs` 接收 AG-UI 的 `RunAgentInput`。rungent 读取其中三个字段：

```json
{
  "messages": [{ "id": "m_1", "role": "user", "content": "Stop gpu-train-01" }],
  "context": [{ "description": "The page the user is on", "value": "/console/instance/vm-42" }],
  "resume": []
}
```

- **`messages`。** 历史由 rungent 保存：你可以发送对话的全部消息，也可以只发新的一条，rungent 会追加它没见过 id 的消息。改动了更早的消息，运行就以 `history_conflict` 失败。用户消息的 `content` 是文本，或类型为 `text`、`image`、`document` 的 AG-UI parts，图片和文档最多 10 个。
- **`context`。** 用户正在看什么，作为信息加入本次运行的提示词，绝不作为指令：最多 16 条、8000 个字符。它不会被保存。
- **`resume`。** 对对话中未答复中断的回答；见[中断](#interrupts)。

回答是 `text/event-stream`，在 `RUN_FINISHED` 或 `RUN_ERROR` 之后结束。运行的生命期比响应长：关闭事件流不会停止它，所以已确认的写操作总会执行完并被记录。只有取消才能停止一次运行。

`image` 或 `document` part 的 `source` 是一个 URL 或内联 `data`。你源站上的路径或 URL，会带着用户的凭据从你的 API 取回，最大 5 MB；其他 URL 直接交给模型提供商；内联数据最大 5 MB。图片只发给 `vision` 端点；类文本文档以文本形式交给模型，最多 20 000 个字符。

## 事件

一次运行推送 [AG-UI 1.0](https://docs.ag-ui.com) 事件。每一帧是一行 `id:`（事件的序号）加一行 `data:`（事件的 JSON），事件之间穿插 `: keepalive` 注释。rungent 自己的数据放在 `metadata.rungent` 下，或放在名为 `rungent.*` 的 `CUSTOM` 事件里。

```text
id: 41
data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"rungent":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}

id: 44
data: {"type":"RUN_FINISHED","threadId":"th_1","runId":"run_7","outcome":{"type":"interrupt","interrupts":[{"id":"int_3","reason":"rungent:approval",…}]},"metadata":{"rungent":{"seq":44}}}
```

| 发生了什么 | AG-UI 事件 | rungent 约定的内容 |
|---|---|---|
| 运行开始、结束或失败 | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR` | `RUN_FINISHED.outcome.type` 是 `success`、`interrupt` 或 `cancelled`；其 `usage` 按提供商和模型列出 token。`RUN_ERROR.code` 是一个[运行错误码](#run-error-codes)。 |
| 一个模型步骤 | `STEP_STARTED`, `STEP_FINISHED` | `stepName` 是 `model:1`、`model:2`…… |
| 助手文本 | `TEXT_MESSAGE_START`, `_CONTENT`, `_END` | 增量约每 50 ms 合并一次。原始推理过程从不发送。 |
| 一次工具调用 | `TOOL_CALL_START`, `_ARGS`, `_END`, `_RESULT` | `START` 携带 `{op, title, effect}`；参数完整、已脱敏地一次到达；`RESULT.metadata.rungent` 是 `{status, error?, deduplicated?}`。 |
| 进度 | `ACTIVITY_SNAPSHOT` | `activityType` 是 `rungent.progress`，`content` 是 `{message}`。 |
| 其他 | `CUSTOM` | 见[自定义事件](#custom-events)。 |

失败调用的结果是 `{"error": {code, message, detail?}}`，其中 `detail` 是你的 API 的错误响应体，已脱敏并截断到 4 KB，好让模型根据你的字段修正调用。启用知识时，追加了用户消息的运行会在 `model:1` 之前先调用一次 `search`。

### 运行错误码

| `RUN_ERROR.code` | 含义 |
|---|---|
| `model_unavailable` | 模型链上没有任何端点能作答。 |
| `max_steps` | 运行达到了步数上限（默认 16）。 |
| `open_interrupts` | 对话有未答复的中断，而 `resume` 没有回答它们。 |
| `history_conflict` | `messages` 改动了 rungent 已保存的某条消息。 |
| `invalid_interaction` | 某条 resume 无效：中断未知或已答复、payload 不符合其 `responseSchema`、`argsHash` 不匹配，或用户试图完成一个任务。 |
| `internal` | 其他情况，包括运行超出时间上限（默认 600 秒）。 |

### 工具错误码

这些错误会返回给模型，由模型用自己的话解释；客户端不把它们当作错误显示。

| 错误码 | 含义 |
|---|---|
| `invalid_arguments` | 参数不符合输入 schema。带表单的操作会改为打开表单。 |
| `unresolved_reference` | 一个名字没有匹配到任何项，或匹配到多个。 |
| `repeated_call` | 本次运行中已经成功过的读操作被重复调用。 |
| `already_attempted` | 本次运行中，这个操作已确认的写操作已经失败过。 |
| `not_executed` | 用户拒绝或取消了、确认过期了，或调用已不再符合目录。什么都没执行。 |
| `credential_expired` | 用户的凭据在运行中过期，或运行没有凭据（它在继续一个任务）。 |
| `timeout` | 你的 API 没有在 `timeoutSeconds` 内作答。 |
| `http_{status}` | 你的 API 返回了这个状态码（`http_403`），响应体作为 `detail`。 |

## 中断

运行以 `outcome: {type: "interrupt", interrupts: [...]}` 结束，表示暂停。每个中断都有 `id`、`reason`、要展示的 `message`、对应的 `toolCallId`、放在 `metadata.rungent` 中的 rungent 数据，以及（任务除外）回答用的 `responseSchema`。

| `reason` | 何时出现 | `metadata.rungent` | 回答的 `payload` |
|---|---|---|---|
| `rungent:approval` | 写操作之前 | `{op, arguments, argsHash, impact}` | `{approved}` |
| `rungent:form` | 带表单的操作之前 | `{op, arguments, form, issues?}` | `{arguments}` |
| `rungent:input` | 模型询问是哪个对象或哪个动作 | `{form}` | `{answers}` |
| `rungent:task` | 你的 API 稍后才执行这项工作 | `{taskId, op}` | 无；由你的 API 完成 |

下一次运行在 `resume` 中回答每个未答复的中断：

```json
{ "interruptId": "int_3", "status": "resolved", "payload": { "approved": true }, "metadata": { "rungent": { "argsHash": "q2…" } } }
```

`status` 是 `resolved` 或 `cancelled`；`cancelled` 不需要 payload，对应的调用以 `not_executed` 结束。用户如果不作答、而是直接输入新消息，就随新消息为每个未答复的中断发送 `cancelled`。

### 确认（`rungent:approval`）

`impact` 就是确认卡：`{title, target, effect, risk, costHint, changes}`，来自操作的 [confirmation](x-rungent.md#confirmation)，其中 `changes` 是它的 `fields`，以 `label: value` 形式给出。回答是 `{approved: true | false}`，并在 `metadata.rungent.argsHash` 中回传这个哈希。rungent 随后用冻结的参数执行调用，最多一次。确认在发出 15 分钟后过期（`expiresAt`）。

### 表单（`rungent:form`）

```json
{
  "op": "create_vm",
  "arguments": { "name": "prod" },
  "form": { "prompt": "Create a server",
    "questions": [{ "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true, "options": [{ "id": "z1", "label": "Beijing A" }] }] },
  "issues": [{ "path": "zone_id", "message": "required" }]
}
```

`arguments` 是表单的初始值；`form` 是你的通用表单，给没有产品自有组件的客户端用；`issues` 说明上一次提交为什么被拒。回答是 `{arguments}`，即操作的**完整**参数。展示通用表单的客户端用 `rungent/protocol` 中的 `answersToArguments` 构造它，这个函数把每个答案放到对应问题的点分路径上。

表单（这里和 `rungent:input` 中都一样）有一个 `prompt` 和 1 到 24 个 id 互不相同的 `questions`：

| 问题 | 键 |
|---|---|
| `text` | `id`、`prompt`、`kind: "text"`、`required`，可选 `placeholder` 和 `default` |
| `choice` | `id`、`prompt`、`kind: "choice"`、`required`、`options`（至少一个），可选 `multiple`、`allowCustom` 和 `default` |
| 选项 | `id`、`label`，可选 `description` 和 `recommended` |

### 提问（`rungent:input`）

模型的 `request_input` 工具以 `{form}` 询问用户指的是哪个对象或哪个动作。回答是 `{answers: {questionId: answer}}`：`text` 问题给一个字符串，`choice` 问题给 `{selected: [optionIds], custom?}`。

### 任务（`rungent:task`）

一个返回 `202 {"rungentTask": "<id>"}` 的操作会暂停运行，并发出 `status: "running"` 的 `rungent.task`。你的 API 用 [`POST /rungent/v0/tasks/{taskId}`](#deferred-tasks) 完成它；用户只能以 `cancelled` 回答它。

## 自定义事件

| `name` | `value` |
|---|---|
| `rungent.ui.open` | `{path}`：展示这个产品页面，成功后来自 `x-rungent.open`。 |
| `rungent.citation` | `{messageId, citations: [{n, hit}]}`：消息中以 `[n]` 引用的每个搜索结果。结果不带 `content`。 |
| `rungent.context` | `{usedTokens, budgetTokens, source}`：模型上下文的占用程度。 |
| `rungent.model.retry` | `{step, attempt, maxAttempts, reason, endpoint, fallback}`：一次模型尝试失败，正在重试。 |
| `rungent.message.discard` | `{messageId}`：丢弃一次将被重试的尝试已输出的部分文本。 |
| `rungent.task` | `{taskId, status, message?}`：任务的进度。 |

客户端会跳过不认识的自定义事件；普通的 AG-UI 客户端照样能正确显示文本、工具调用和中断。

## 断线后重放

`seq` 按对话递增，跨越多次运行，SSE 的 `id:` 行就是同一个数字。丢了事件流的客户端用 `GET /rungent/v0/threads/th_1/events?after=44` 重连：rungent 重放其后的每个事件，再实时跟随这个对话。`Last-Event-ID` 同样有效，所以浏览器的 `EventSource` 会自动续上。

## 目录与搜索

`GET /rungent/v0/catalog` 返回 `{operations: [{name, title, description, effect, approval,
surfaces, input}]}`，不含角色操作；`input` 是[输入 schema](catalog.md#the-input-schema)。

`GET /rungent/v0/search` 接收 `q`（必填）、`limit`（默认 10，最多 50）和 `types`（逗号分隔）。返回 `{hits, failed}`：每个结果标明其 `source`，不带 `content`；每个失败的来源是 `{source, code}`，code 为 `timeout`、`http_<status>` 或 `invalid_response`。

## 设置

`GET /rungent/v0/settings` 返回 `{models: {chain: [...]}}`，每一项带 `hasApiKey`，从不包含密钥；在代码里配置的项显示为提供商 `custom`。`PUT` 用符合[模型链字段](deploy.md#choose-models)的项替换整条链；不带 `apiKey` 发送的项，沿用同一 `id` 的项已保存的密钥。`DELETE` 清除保存的链，配置中的那条链重新生效。两者都需要 `rungent:admin`，返回内容与 `GET` 相同。

## 延后任务

`202` 操作的工作完成后，由你的 API 完成这个任务：

```http
POST /rungent/v0/tasks/task_123
Content-Type: application/json
Rungent-Host-Assertion: <compact JWS>

{"status": "succeeded", "result": {"id": "vm-43"}}
```

`status` 是 `succeeded` 或 `failed`；`result` 成为工具结果，按该操作的规则脱敏。断言的 `op` 是发起延后的那个操作，`sub` 和 `ten` 是对话所有者的。它返回 `202 {"runId"}`：rungent 开始一次运行，继续那个中断。这次运行没有用户凭据，所以它对你的 API 发起的调用会以 `credential_expired` 失败。

## 宿主任务

`POST /rungent/v0/generate` 为你的某项任务（比如周报的摘要）做一次模型生成，用一个 `op` 为 `generate` 的 `Rungent-Host-Assertion` 签名：

```json
{
  "instructions": "Write the weekly report's summary in two sentences.",
  "input": "Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).",
  "schema": { "type": "object", "properties": { "headline": { "type": "string" } }, "required": ["headline"] },
  "maxOutputTokens": 400
}
```

`input` 必填（最多 200 000 个字符）。带 `schema` 时，回答是符合它的 `{object}`；不带时是 `{text}`。调用使用模型链，不带工具，也不关联对话；不符合 `schema` 的回答会退回模型重来一次。

## 宿主断言

`Rungent-Host-Assertion` 的形式与 rungent 发给你的断言相同：一个 EdDSA compact JWS，header 为 `{"alg": "EdDSA", "kid", "typ": "rungent-call+jwt"}`，用 rungent 在 `hostKeys`（`RUNGENT_HOST_KEYS`）中固定的密钥签名。

| Claim | 值 |
|---|---|
| `iss` | 你的源站。 |
| `aud` | rungent 自己的 URL。 |
| `sub`, `ten` | 这次调用代表谁。 |
| `sid`, `rid`, `cid` | 由你自定的 id，用于审计。 |
| `op` | 被延后的操作，或 `generate`。 |
| `htm`, `htu` | `POST`；以及 rungent 公开 URL 的源，后接你所 post 的路径。 |
| `bsh` | 原样请求体的 SHA-256，base64url 编码。 |
| `iat`, `exp`, `jti` | 相差最多 60 秒；每个 `jti` 只接受一次。 |

JavaScript 宿主用 `rungent/delegation` 中的 `signAssertion` 签名。其他语言里，任何 Ed25519 JWS 库都能生成这个令牌。

## 文档与密钥

`/skill.md`（`text/markdown`）和 `/llms.txt`（`text/plain`）无论有没有凭据都返回 `200`。带凭据时，列出调用方的操作。不带时，列出你的 API 匿名提供的目录；如果那里返回 `401` 或 `403`，就只包含使用指南和连接方法，rungent 会把这个结果记住 5 分钟。`/.well-known/rungent-keys.json` 是 `{"keys": [{"kty": "OKP", "crv": "Ed25519", "x", "kid"}]}`。在 `/mcp` 上，每个工具在 `_meta.rungent`（`{command, args, effect}`）中带着它的 CLI 写法。
