rungent v0.5.1
EN中文

rungent核心概念

表单与确认

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

对话中出现的产品自己的创建表单
用户写了「create a server」。路由选中 create_vm,控制台自己的表单随即打开;模型从没有用文字询问各个字段。

  1. 提问「创建一台 GPU 服务器,叫 train-01。」
  2. 路由一次静默的模型调用选中 create_vm,并保留用户说过的内容:名称。
  3. 表单你的创建表单在对话中打开,名称已经填好。
  4. 解析提交的内容经过校验,名称换成 ID。
  5. 确认卡片原样展示提交的内容,用户确认。
  6. 执行你的 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。

助手面板里的确认卡:Stop server gpu-train-01?
用户要求停止 gpu-train-01。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编辑此页