rungent核心概念
目录
你的 OpenAPI 文档,在允许 Agent 使用的操作上加上 x-rungent,就是目录。本页讲什么是操作、效果意味着什么、名称怎样变成 ID、两次调用怎样串起来,以及上线前怎样把这些全部检查一遍。
一个云控制台本来就有 OpenAPI 3.1 文档。给其中三个端点各加一个 x-rungent 对象,就得到一份目录:
"/api/vms": {
"get": {
"x-rungent": { "name": "list_vms", "description": "List the user's cloud servers (VMs)." }
},
"post": {
"x-rungent": { "name": "create_vm", "description": "Create a cloud server (VM).", "form": "vm_form" }
}
},
"/api/vms/{vm_id}/stop": {
"post": {
"x-rungent": {
"name": "stop_vm",
"description": "Stop a running cloud server (VM).",
"effect": "update",
"resolve": { "vm_id": { "op": "list_vms" } },
"confirmation": { "title": "Stop server {vm_id}?" }
}
}
}
没有 x-rungent 的操作对 rungent 不可见。助手、MCP、CLI、skill.md 和搜索读的都是同一份标注,所以每个操作只需描述一次。所有键见 x-rungent。
什么是操作#
操作就是某个路径上带 x-rungent 的某个 HTTP 方法。它是 Agent 的一个工具、MCP 客户端的一个工具,也是 CLI 的一条命令。唯一必填的键是 name:小写字母、数字和 _,最长 64 个字符,在目录中唯一。
| 用在哪里 | 写法 |
|---|---|
Agent 的工具、MCP 工具、断言的 op |
stop_vm |
| CLI 命令 | stop-vm,或 cli.command 里写的词(vm stop) |
description 是模型选工具时读的:写清资源,以及用户对它的叫法(「cloud server (VM)」)。title 用在确认卡、活动行和 CLI 帮助里。两者都默认取 OpenAPI 的 summary。
效果、确认与入口#
effect 说明一次调用做什么,其余所有默认值都由它决定。除非你另行指定,rungent 按 HTTP 方法推断:
effect |
含义 | 默认对应 | approval |
surfaces |
|---|---|---|---|---|
read |
不做任何改动 | GET、HEAD |
never |
agent、mcp、cli |
create |
创建资源 | POST |
always |
agent、cli |
update |
修改已有资源 | PUT、PATCH |
always |
agent、cli |
delete |
删除资源 | DELETE |
always |
agent、cli |
external |
对外动作:发邮件、刷卡扣款 | 无 | always |
agent、cli |
方法表达不清时就写明 effect:停服务器是一个修改已有服务器的 POST,所以 stop_vm 是 update。GET 必须保持为 read。
approval取never或always,由运行时根据目录决定,从不由提示词决定。一个仍然需要确认的读操作,比如导出全部客户,就设"approval": "always"。见表单与确认。surfaces列出操作出现在哪些入口。MCP 默认只读;在写操作上列出mcp,就会把它提供给能请用户确认的 MCP 客户端。见入口。
特殊角色的操作#
有些操作不是工具,而是给 rungent 自己应答的。它们带 role,不出现在任何入口,也从不提供给模型:
role |
形式 | 页面 |
|---|---|---|
identity |
GET,无参数;每份目录恰好一个 |
以用户身份调用 |
search |
GET,带必填的查询参数 q |
搜索与知识 |
form |
应答表单的 POST;rungent 把它当作读操作 |
表单与确认 |
每个用户看到自己的目录#
rungent 用当前登录用户自己的凭据获取你的 OpenAPI 文档,读到的内容按凭据缓存 5 分钟。你的服务器可以略去某个用户无权调用的操作,那么任何入口都不会向这个用户提供它们。GET /rungent/v0/catalog 列出调用者看到的内容。隐藏操作只是一种礼貌:你的 API 仍要对收到的每次调用做授权。
输入结构#
rungent 把每个操作变成一个扁平的输入结构,模型、MCP 客户端和 CLI 看到的都是它:
- 路径参数和查询参数成为顶层属性;路径参数必填。
- JSON 请求体如果是带
properties的对象,就展开成顶层属性;其他请求体变成一个body属性。 - 指向
#/components/schemas的$ref保留为$defs引用,所以递归结构依然有效。
对于 POST /api/vms/{vm_id}/stop,请求体为 {"forced": boolean},输入就是 {vm_id, forced},其中 vm_id 必填。调用你的 API 时,rungent 再把参数拆回路径、查询和请求体。
每次调用前,rungent 先转换参数类型(数字字符串转成数字,JSON 字符串转成对象),再做校验。不合规的参数永远到不了你的 API:模型收到 invalid_arguments,其中按路径列出每个问题(vm_id: required),然后修正自己的调用。带表单的操作则改为打开表单。
把名称换成 ID#
用户写「stop gpu-train-01」,你的路由要的是 vm-42。resolve 把一个参数映射到列出候选项的读操作 {op, key?},其中 key 是条目里存放 ID 的字段(默认 id)。对每个列出的、值为字符串的参数,rungent:
- 以用户身份调用
op;如果它接受查询参数page_size,就请求 100 条; - 从应答中取出条目:应答本身就是数组,或者是第一个由带
key的对象组成的嵌套数组({"items": [...]}); - 如果某个条目的
key等于这个值,就保留原值,因为它已经是 ID; - 否则不区分大小写,拿它和每个条目的
name、display_name、displayName或title比较,用唯一匹配项的key替换它。
没有匹配或匹配到多个,调用就以 unresolved_reference 失败,并列出最多十个候选项,模型可以从中选一个,或者去问用户。名称在确认卡之前解析,所以确认绑定的是 vm-42,卡片等待期间即使有人改名,也改变不了实际执行的内容。确认卡上的 lookup 会把名称写回卡片。
resolve 适合一次列表调用就能完整返回的集合:服务器、项目、成员。更大的集合,模型通过搜索或带过滤的列表找到 ID。
把两次调用当一次运行#
有些动作需要两次调用:先准备一份草稿,检查配额并报价,再提交它。第一个操作上的 next 指明第二个操作,rungent 在第一次成功后、模型写任何内容之前立即运行它:
"x-rungent": {
"name": "prepare_vm_draft",
"approval": "never",
"next": {
"op": "commit_vm_draft",
"arguments": { "draft_id": "id", "revision": "revision" },
"when": { "status": "prepared" }
}
}
草稿应答 {"id": "d-7", "revision": 3, "status": "prepared", …},于是 rungent 用 {"draft_id": "d-7", "revision": 3} 调用 commit_vm_draft。如果草稿应答 "status": "needs_quota",when 不满足:链条停下,由模型解释结果。argumentsFrom 则把结果中的一个对象整个作为下一次调用的输入(x-rungent)。
下一次调用和其他调用一样,要经过校验、解析和它自己的确认,所以链条从不跳过确认卡。每个操作在一条链中最多运行一次,所以环路会自行终止。
调用之后会发生什么#
open指明成功后要展示的产品页面,用参数和结果填充(/console/instance/{vm_id})。面板把它交给你的路由器。redact列出模型和 MCP 客户端永远看不到的结果字段(ip)。名称像密钥的字段(password、token、api_key、cookie等)总会被移除。timeoutSeconds限定调用时长:默认 120 秒,最多 3600 秒。- 在一次运行中,用相同参数重复的写操作直接以第一次的结果作答。如果重复正是目的(「再加一块 GPU」),就设
repeatable: true。 - 需要的时间超过一次请求的操作,应答
202 {"rungentTask": "<id>"},运行会一直等到你的 API 完成这项任务。
检查目录#
rungent 读取目录时会校验它,有错误就拒绝。部署前先检查文档:
npx rungent check --openapi http://localhost:3000/api/openapi.json --routes routes.txt
它打印每一个问题,只要有问题就以 1 退出;规则见 x-rungent。--routes 接收你的界面发出的请求,每行一个 METHOD /path,没有操作承接的行都会报失败,除非该行以 # browser-only: <reason> 结尾。这样能保证你的界面能做的事,Agent 也能做。
接下来#
以用户身份调用讲 rungent 怎样以用户自己的权限调用这些操作。
供 Agent 读取: catalog.md编辑此页