rungent v0.5.1
EN中文

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编辑此页