rungentConcepts
The catalog
Your OpenAPI document, with x-rungent on the operations agents may use, is the catalog. What an operation is, what its effect implies, how names become ids, how two calls chain, and how to check it all before you ship.
A cloud console already has an OpenAPI 3.1 document. Three of its endpoints become a catalog
with one x-rungent object each:
"/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}?" }
}
}
}
Operations without x-rungent stay invisible to rungent. The assistant, MCP, the CLI, skill.md and
search all read the same annotations, so you describe each operation once. Every key is in
x-rungent.
What an operation is#
An operation is one HTTP method on one path that carries x-rungent. It is a tool for the agent,
a tool for MCP clients and a command of the CLI. Its name is the only required key: lowercase
letters, digits and _, at most 64 characters, unique in the catalog.
| Where | Spelling |
|---|---|
The agent's tool, the MCP tool, the assertion's op |
stop_vm |
| The CLI command | stop-vm, or the words in cli.command (vm stop) |
description is what the model reads to choose a tool: name the resource and the words users
say for it ("cloud server (VM)"). title labels approval cards, activity rows and CLI help.
Both default to the OpenAPI summary.
Effects, approval and surfaces#
effect says what a call does, and it sets the defaults for everything else. rungent takes it
from the HTTP method unless you say otherwise:
effect |
Meaning | Default for | approval |
surfaces |
|---|---|---|---|---|
read |
Changes nothing | GET, HEAD |
never |
agent, mcp, cli |
create |
Creates something | POST |
always |
agent, cli |
update |
Changes something that exists | PUT, PATCH |
always |
agent, cli |
delete |
Removes something | DELETE |
always |
agent, cli |
external |
Reaches outside: sends mail, charges a card | none | always |
agent, cli |
Set effect when the method does not say it: stopping a server is a POST that changes an
existing server, so stop_vm is an update. A GET must stay a read.
approvalisneveroralways, decided by the runtime from the catalog, never by a prompt. A read that should still be confirmed, such as exporting every customer, sets"approval": "always". See Forms and approvals.surfaceslists where the operation appears. MCP starts read-only; listmcpon a write to offer it to MCP clients that can ask the user to confirm. See Surfaces.
Operations with a special role#
Some operations answer rungent itself instead of being tools. They carry role, have no surfaces,
and are never offered to the model:
role |
Shape | Page |
|---|---|---|
identity |
GET, no parameters; exactly one per catalog |
Acting as the user |
search |
GET with a required q query parameter |
Search and knowledge |
form |
POST that answers a form; rungent treats it as a read |
Forms and approvals |
Each user sees their own catalog#
rungent fetches your OpenAPI document with the signed-in user's own credential and keeps what it
read for 5 minutes per credential. Your server may leave out operations a user may not call,
and no surface offers them to that user. GET /rungent/v0/catalog lists what the caller sees.
Hiding an operation is a courtesy: your API still authorizes every call it receives.
The input schema#
rungent turns each operation into one flat input schema, which the model, MCP clients and the CLI all see:
- Path and query parameters become top-level properties; path parameters are required.
- A JSON body that is an object with
propertiesis flattened into top-level properties; any other body becomes onebodyproperty. $refs into#/components/schemasstay as$defsreferences, so recursive schemas stay valid.
For POST /api/vms/{vm_id}/stop with the body {"forced": boolean}, the input is
{vm_id, forced}, with vm_id required. rungent splits the arguments back into path, query and
body when it calls your API.
Before any call, rungent coerces the arguments (a numeric string to a number, a JSON string to an
object) and validates them. Arguments that do not fit never reach your API: the model gets
invalid_arguments with each problem at its path (vm_id: required) and corrects its call.
An operation with a form opens its form instead.
Turn names into ids#
The user writes "stop gpu-train-01"; your route takes vm-42. resolve maps an argument to the
read operation that lists its candidates, {op, key?}, where key is the item field holding
the id (id by default). For each listed argument that holds a string, rungent:
- calls
opas the user, asking for 100 items when it takes apage_sizequery parameter; - takes the items from the answer: the array itself, or the first nested array of objects that
carry
key({"items": [...]}); - keeps the value when an item's
keyequals it, because it is already an id; - otherwise compares it with each item's
name,display_name,displayNameortitle, ignoring case, and replaces it with the one match'skey.
No match, or several, fails the call with unresolved_reference and names up to ten
candidates, so the model can pick one or ask the user. Names resolve before the approval card,
so the approval binds to vm-42 and a rename while the card waits cannot change what runs. A
confirmation lookup puts the name back on the card.
Resolve suits collections one list call returns whole: servers, projects, members. For larger ones, the model finds the id with search or a filtered list.
Run two calls as one#
Some actions take two calls: prepare a draft that checks quota and prices it, then commit it.
next on the first operation names the second, and rungent runs it right after success, before
the model writes anything:
"x-rungent": {
"name": "prepare_vm_draft",
"approval": "never",
"next": {
"op": "commit_vm_draft",
"arguments": { "draft_id": "id", "revision": "revision" },
"when": { "status": "prepared" }
}
}
The draft answers {"id": "d-7", "revision": 3, "status": "prepared", …}, so rungent calls
commit_vm_draft with {"draft_id": "d-7", "revision": 3}. A draft that answers
"status": "needs_quota" fails when: the chain stops and the model explains the result.
argumentsFrom takes a result object as the next call's whole input instead
(x-rungent).
The next call goes through validation, resolve and its own approval like any other, so a chain never skips a card. Each operation runs at most once per chain, so a cycle ends.
What happens after a call#
opennames a page of your product to show after success, filled from the arguments and the result (/console/instance/{vm_id}). The dock passes it to your router.redactlists result fields the model and MCP clients never see (ip). Fields with secret-like names (password,token,api_key,cookieand similar) are always removed.timeoutSecondsbounds the call: 120 seconds by default, at most 3600.- Within one run, a write repeated with identical arguments is answered from the first result.
Set
repeatable: truewhen repeating is the point ("add one more GPU"). - An operation that needs longer than a request answers
202 {"rungentTask": "<id>"}, and the run waits until your API completes the task.
Check the catalog#
rungent validates the catalog when it reads it and refuses one with errors. Check a document before you deploy it:
npx rungent check --openapi http://localhost:3000/api/openapi.json --routes routes.txt
It prints every issue and exits 1 when there is any; the rules are in
x-rungent. --routes takes the requests your UI makes, one
METHOD /path per line, and fails each one no operation serves, unless the line ends with
# browser-only: <reason>. That keeps the agent able to do what your UI does.
Where to go next#
Acting as the user shows how rungent calls these operations with the user's own rights.
For agents: catalog.mdEdit this page