rungent v0.5.1
EN中文

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.

  • approval is never or always, 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.
  • surfaces lists where the operation appears. MCP starts read-only; list mcp on 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 properties is flattened into top-level properties; any other body becomes one body property.
  • $refs into #/components/schemas stay as $defs references, 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:

  1. calls op as the user, asking for 100 items when it takes a page_size query parameter;
  2. takes the items from the answer: the array itself, or the first nested array of objects that carry key ({"items": [...]});
  3. keeps the value when an item's key equals it, because it is already an id;
  4. otherwise compares it with each item's name, display_name, displayName or title, ignoring case, and replaces it with the one match's key.

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#

  • open names 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.
  • redact lists result fields the model and MCP clients never see (ip). Fields with secret-like names (password, token, api_key, cookie and similar) are always removed.
  • timeoutSeconds bounds 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: true when 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