rungent v0.5.1
EN中文

rungentConcepts

Forms and approvals

Every change takes one path. A request to create or change something opens your page's own form, prefilled; the submission becomes an approval card bound to its exact arguments; only an approval runs the call.

The product's own create form inside the conversation
The user wrote “create a server”. Routing picked create_vm and the console's own form opened; the model never asked for the fields in text.

  1. Ask“Create a GPU server called train-01.”
  2. RouteOne quiet model call picks create_vm and keeps what the user said: the name.
  3. FormYour create form opens in the conversation with the name filled in.
  4. ResolveThe submission is validated, and names become ids.
  5. ApproveA card shows exactly what was submitted; the user approves it.
  6. RunYour API receives the call with the approval's id and authorizes it.

Why one path#

A model asked to create something improvises: it lists the fields in text, guesses a zone, or asks three questions in a row, and the next run does something else. Your product already has a form for this, with its options, defaults and checks. An operation that names a form gets its input only from that form, and every write waits for a card the runtime shows, not the model. The same request takes the same path every time.

Declare the form#

The operation names a role: form operation of your API:

"/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" } }
}

A form operation is a POST that changes nothing, so rungent treats it as a read that needs no approval. rungent sends it the arguments known so far, and it answers a generic description of the form, so it can offer only the zones the user's quota allows:

{
  "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" }] }
  ]
}

Each question's id is the dotted path of the argument it fills (zone_id, network.cidr). A form has 1 to 24 questions, each text or choice (with multiple and allowCustom when needed); the full shape is in HTTP API. Your web app shows its own form component instead, and clients without one show this.

Routing sends the request to the form#

When the catalog offers operations with a form, each new user message first goes through routing: one quiet model call that sees only those operations and a continue tool. If the message asks to create or change something one of them does, rungent opens its form at once; the agent loop does not run. A request still goes to the form when it also asks to be asked first, or names an option that may not exist: the form is where those are answered.

Anything else, a question, a lookup or "stop gpu-train-01", goes on to the agent. Routing emits no events and adds nothing to the conversation.

Show your page's own form#

Register the component your create page uses, by operation name, with forms on RungentProvider:

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>
Prop What it is
op The operation the form is for
arguments What to start from: what the user said, or their last submission
issues {path, message}[]: why the last submission was refused; empty the first time
submit(args) Sends the operation's complete arguments
cancel() Closes the form; the call does not run

The form starts from the arguments the user stated; ones the model got wrong are left out. rungent validates the submission against the operation's input schema. One that does not fit opens the form again with an issue per problem ({"path": "zone_id", "message": "required"}), and nothing runs. One that fits goes on to name resolution and the card.

Ask which one#

The agent has one more way to ask: the built-in request_input tool, for which thing or which action the user means, offered as choices. "Stop the gpu server" with two servers named alike asks which one instead of guessing. It is never used for an operation's inputs; those belong to the form.

What decides that a call needs approval#

The operation's approval in the catalog, and nothing else: always by default for every write, never for reads (The catalog). The decision is made in the runtime's code; no prompt or model output takes part in it, so the model cannot talk its way past a card. Your API checks it again: the assertion of an approval: always call must carry the approval's id as apr.

Before the card, rungent validates the input (or collects it through the form), resolves names, and looks up the target's name, in that order. The first step that fails stops the call, and nothing reaches your API as a write.

An approval card in the dock: Stop server gpu-train-01?
The user asked to stop gpu-train-01. rungent found the server, looked up its name, and waits; nothing has reached the API yet.

Write the card#

confirmation on the operation shapes the card:

"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."
}

Templates take {argument} placeholders and {resource_name}. With lookup, rungent makes a GET of path as the user before the card and reads labelPath from the answer as {resource_name}, so the user sees gpu-train-01 where the model passed vm-42. The path must be served by a GET operation of the catalog, and a lookup that fails stops the call. Without confirmation, the card's title is the operation's title. Every key is in x-rungent.

The approval binds to the exact arguments#

When the card appears, rungent freezes the arguments it shows and stores the approval with their hash, argsHash: base64url SHA-256 of the arguments as canonical JSON (RFC 8785). The client answers with the hash it showed.

  • A hash that differs from the stored one is refused, and nothing runs.
  • rungent runs the frozen arguments; an answer cannot substitute others.
  • Each approval runs at most once, even when two rungent replicas receive the answer at once.
  • A confirmed call always finishes and is recorded, even if the user closes the page.
  • An approval expires 15 minutes after the card appears. Approving it later, rejecting it, or sending a new message instead runs nothing, and the model tells the user so.

Outside the assistant#

Forms belong to the assistant: MCP clients and the CLI pass an operation's complete arguments, and the same input schema checks them. Every surface still asks before a write:

  • MCP. A write on the mcp surface asks the user through MCP elicitation, with the same title, target and changes. A client without elicitation gets not_executed, and nothing runs.
  • CLI. The CLI asks [y/N] on the terminal; --yes confirms for scripts. Without a terminal and without --yes, the write is declined.

Both carry an approval id in the assertion, so your API's check is the same everywhere.

Where to go next#

Search and knowledge covers how the agent finds what the user cannot name.

For agents: forms-and-approvals.mdEdit this page