rungent参考
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;小版本仍可能改动它,更新日志列出了每一处破坏性变更。
认证#
用户的请求带着你的应用已经在用的凭据:Authorization 头、Cookie 头,或两者都有。rungent 把它们转发给你的身份操作,以得知用户是谁(以用户身份调用)。两者都没有,或被你的身份操作拒绝,就返回 401 unauthorized。一个对话属于创建它的 (subject, tenant);其他人访问得到 404。
你的 API 自己发起的调用,即 POST /rungent/v0/tasks/{taskId} 和 POST /rungent/v0/generate,改为携带 Rungent-Host-Assertion。
对于以 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 读取其中三个字段:
{
"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。 对对话中未答复中断的回答;见中断。
回答是 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 事件。每一帧是一行 id:(事件的序号)加一行 data:(事件的 JSON),事件之间穿插 : keepalive 注释。rungent 自己的数据放在 metadata.rungent 下,或放在名为 rungent.* 的 CUSTOM 事件里。
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 是一个运行错误码。 |
| 一个模型步骤 | 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 |
见自定义事件。 |
失败调用的结果是 {"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 中回答每个未答复的中断:
{ "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,其中 changes 是它的 fields,以 label: value 形式给出。回答是 {approved: true | false},并在 metadata.rungent.argsHash 中回传这个哈希。rungent 随后用冻结的参数执行调用,最多一次。确认在发出 15 分钟后过期(expiresAt)。
表单(rungent:form)#
{
"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} 完成它;用户只能以 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。
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 用符合模型链字段的项替换整条链;不带 apiKey 发送的项,沿用同一 id 的项已保存的密钥。DELETE 清除保存的链,配置中的那条链重新生效。两者都需要 rungent:admin,返回内容与 GET 相同。
延后任务#
202 操作的工作完成后,由你的 API 完成这个任务:
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 签名:
{
"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 写法。
供 Agent 读取: http-api.md编辑此页