rungent核心概念
表单与确认
每次变更只走一条路。创建或修改的请求会打开你页面自己的表单并预先填好;提交的内容变成一张绑定确切参数的确认卡;只有用户确认后才会执行调用。

- 提问「创建一台 GPU 服务器,叫 train-01。」
- 路由一次静默的模型调用选中 create_vm,并保留用户说过的内容:名称。
- 表单你的创建表单在对话中打开,名称已经填好。
- 解析提交的内容经过校验,名称换成 ID。
- 确认卡片原样展示提交的内容,用户确认。
- 执行你的 API 收到带确认 ID 的调用,并进行授权。
为什么只有一条路#
让模型去创建东西,它往往会即兴发挥:用文字列出字段、猜一个可用区,或者连问三个问题,下一次运行又换一种做法。你的产品早就有做这件事的表单,带着选项、默认值和校验。指定了表单的操作,只从那个表单获得输入;每个写操作都要等一张确认卡,而这张卡由运行时展示,不由模型展示。同样的请求,每次都走同样的路。
声明表单#
操作指向你的 API 中一个 role: form 的操作:
"/api/vms": {
"post": { "x-rungent": { "name": "create_vm", "description": "Create a cloud server (VM).", "form": "vm_form" } }
},
"/api/vms/form": {
"post": { "x-rungent": { "name": "vm_form", "role": "form" } }
}
表单操作是一个不改变任何东西的 POST,所以 rungent 把它当作无需确认的读操作。rungent 把目前已知的参数发给它,它返回表单的通用描述,因此可以只列出用户配额允许的可用区:
{
"prompt": "Create a server",
"questions": [
{ "id": "name", "prompt": "Name", "kind": "text", "required": true },
{ "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true,
"options": [{ "id": "z1", "label": "Beijing A", "recommended": true }, { "id": "z2", "label": "Beijing B" }] }
]
}
每个问题的 id 是它所填参数的点分路径(zone_id、network.cidr)。一个表单有 1 到 24 个问题,每个是 text 或 choice(需要时加 multiple 和 allowCustom);完整结构见 HTTP API。你的 Web 应用会改为显示自己的表单组件,没有自己组件的客户端显示这份描述。
路由把请求送到表单#
当目录里有带表单的操作时,每条新的用户消息都先经过路由:一次静默的模型调用,它只看得到这些操作和一个 continue 工具。如果消息要创建或修改的东西正是其中某个操作做的,rungent 立即打开它的表单,Agent 循环不会运行。即使请求还要求先问一问,或者提到了一个可能不存在的选项,也照样送到表单:这些问题就该在表单里回答。
其他请求,比如一个问题、一次查询,或者「stop gpu-train-01」,都交给 Agent。路由不发出任何事件,也不往对话里加任何内容。
显示页面自己的表单#
在 RungentProvider 上用 forms 按操作名注册你创建页面所用的组件:
import { RungentDock, RungentProvider, type HostFormProps } from 'rungent/react';
import { CreateVmForm } from './vms/create-vm-form';
function CreateVm({ arguments: args, issues, submit, cancel }: HostFormProps) {
return <CreateVmForm initial={args} errors={issues} onSubmit={submit} onCancel={cancel} />;
}
<RungentProvider client={client} forms={{ create_vm: CreateVm }}>
<RungentDock>{page}</RungentDock>
</RungentProvider>
| 属性 | 含义 |
|---|---|
op |
表单对应的操作 |
arguments |
起始值:用户说过的内容,或他们上一次提交的内容 |
issues |
{path, message}[]:上一次提交被拒的原因;第一次打开时为空 |
submit(args) |
提交操作的完整参数 |
cancel() |
关闭表单;调用不会执行 |
表单从用户说过的参数开始填;模型弄错的参数会被丢掉。rungent 按操作的输入 schema 校验提交的内容。不符合的会重新打开表单,每个问题对应一条 issue({"path": "zone_id", "message": "required"}),什么也不会执行。符合的继续进入名称解析和确认卡。
问清是哪一个#
Agent 还有一种提问方式:内置的 request_input 工具,用来以选项的形式问清用户指的是哪个对象、哪个动作。有两台名字相近的服务器时,「停掉那台 gpu 服务器」会问是哪一台,而不是去猜。它从不用来收集操作的输入,那是表单的事。
由什么决定一次调用需要确认#
只由目录里操作的 approval 决定:每个写操作默认是 always,读操作是 never(目录)。这个决定写在运行时的代码里,提示词和模型输出都不参与,所以模型没法靠说服绕过确认卡。你的 API 还会再检查一次:approval: always 的调用,其断言必须以 apr 带上确认的 ID。
在确认卡出现之前,rungent 依次校验输入(或通过表单收集输入)、解析名称、查出目标的名称。任何一步失败,调用就停下,不会有写请求到达你的 API。

编写确认卡#
操作上的 confirmation 决定卡片的样子:
"confirmation": {
"title": "Stop server {resource_name}?",
"target": "{resource_name} ({vm_id})",
"fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }],
"lookup": { "path": "/api/vms/{vm_id}", "labelPath": "name" },
"risk": "medium",
"costHint": "Billing drops to storage only, about ¥0.4/hour."
}
模板里可以用 {参数名} 占位符和 {resource_name}。有 lookup 时,rungent 在出卡片前以用户身份对 path 发一次 GET,从返回里读出 labelPath 作为 {resource_name},这样模型传的是 vm-42,用户看到的是 gpu-train-01。这个路径必须由目录里的某个 GET 操作提供,查询失败就停止调用。没有 confirmation 时,卡片标题是操作的 title。所有键见 x-rungent。
确认绑定到确切参数#
卡片出现时,rungent 冻结它展示的参数,并把确认连同这些参数的哈希 argsHash 一起存下:参数按规范 JSON(RFC 8785)序列化后的 SHA-256,用 base64url 编码。客户端回答时带上它展示过的哈希。
- 哈希和存下的不一致就拒绝,什么也不执行。
- rungent 执行的是冻结的参数;回答无法换成别的参数。
- 每个确认最多执行一次,即使两个 rungent 副本同时收到回答。
- 已确认的调用一定会执行完并被记录,即使用户关掉了页面。
- 确认在卡片出现 15 分钟后过期。之后再确认、拒绝,或者改发一条新消息,都不会执行任何东西,模型会告诉用户这一点。
助手之外#
表单只属于助手:MCP 客户端和 CLI 传入操作的完整参数,由同一份输入 schema 校验。但每个入口在写操作前都会先问:
- MCP。
mcp入口上的写操作通过 MCP elicitation 询问用户,标题、对象和变更都一样。不支持 elicitation 的客户端会收到not_executed,什么也不会执行。 - CLI。 CLI 在终端上问
[y/N];脚本里用--yes确认。既没有终端也没有--yes时,写操作会被拒绝。
两者都在断言里带上确认 ID,所以你的 API 在哪里都是同一套检查。
接下来#
搜索与知识讲 Agent 如何找到用户叫不出名字的东西。
供 Agent 读取: forms-and-approvals.md编辑此页