rungent v0.5.1
EN中文

rungentConcepts

How it works

The parts of rungent, where the runtime runs, what happens during one request, the protocol the UI speaks, and the words these docs use.

Where people and agents workIn-app assistantthe dock beside your pages⌘K searchresources and docsMCP clientsClaude Code, Cursor, …CLIyour branded commandskill.md · llms.txtfor any agentrungentOne catalogyour OpenAPI, as each user sees itRouting → form → approvalone path for every changeAgent loopmodel chain, retries, limitsThreads and streamingAG-UI events, resumableSearch and knowledgefederated, citedYour productHTTP APIOpenAPI 3.1 + x-rungentIdentitywho is signed inPermissionsyour rules decidePage formsthe same form as your pageDocsanswers cite themthe user'ssessionuser credential+ signed assertionresults,your errorsEvery call runs as the signed-in user. rungent holds no privilege of its own.Where people and agents workIn-app assistantthe dock beside your pages⌘K searchresources and docsMCP clientsClaude Code, Cursor, …CLIyour branded commandskill.md · llms.txtfor any agentthe user'ssessionrungentOne catalogyour OpenAPI, as each user sees itRouting → form → approvalone path for every changeAgent loopmodel chain, retries, limitsThreads and streamingAG-UI events, resumableSearch and knowledgefederated, citeduser credential+ signed assertionYour productHTTP APIOpenAPI 3.1 + x-rungentIdentitywho is signed inPermissionsyour rules decidePage formsthe same form as your pageDocsanswers cite them

Every call runs as the signed-in user. rungent holds no privilege of its own.

What you install#

rungent is one runtime, written in TypeScript on Web-standard APIs. It ships as one npm package, rungent, whose entry points you import as your stack needs them:

Import What it is
rungent The runtime: createRungent, the stores
rungent/react The dock, ⌘K palette, approval cards, forms, model settings
rungent/client A typed client of the HTTP API that reduces its events into a thread
rungent/delegation Signing keys, and the assertion checks your API runs
rungent/knowledge Your docs as a cited search source
rungent/sql/postgres, /sql/sqlite, /sql/d1 Database drivers for the stores and knowledge
rungent/node nodeHandler for Node's (req, res), and the server behind rungent serve
rungent/cli The CLI as a library, for a branded CLI
rungent/protocol, /catalog, /search, /documents The contract's types and helpers, for tools of your own

The package's one command is rungent: the CLI of every rungent host, the authoring tools (check, keys, brand) and rungent serve. Two more pieces live outside npm: the Docker image ghcr.io/rungent/rungent-server, which runs rungent serve, and the Python kit rungent on PyPI (imported as rungent).

Where the runtime runs#

  1. Embedded
    • Your JavaScript APIHono, Express, Workers, Node
    • rungent in the same processone fetch handler
  2. Beside your API
    • Your APIPython, Go, Java, …
    • rungent serve next to ityour proxy forwards /rungent and /mcp
  3. Either way
    • Same originyour users' cookies just work
    • Same contractOpenAPI in, assertions out

Both shapes serve the same paths on your own domain: /rungent/v0/* for the assistant, /mcp, /skill.md, /llms.txt and /.well-known/rungent-keys.json. Your web app calls them as same-origin requests, so the user's existing session is the credential. JavaScript embeds rungent; Python and other stacks runs it beside your API.

One request, step by step#

When a user sends a message, rungent runs these steps. Each one is in code, not in a prompt.

  1. Catalogrungent reads your OpenAPI with the user's credential and keeps the operations marked x-rungent that the user may see.
  2. GroundIf you gave rungent your docs, it searches them for the user's words first.
  3. RouteA request to create or change something goes straight to that operation.
  4. FormThe operation's form opens, prefilled: your page's own form in your app.
  5. ResolveNames the user typed ("train-01") become ids, through your list operations.
  6. ApproveA write shows a card with its target and changes; the approval binds to those exact arguments.
  7. Callrungent calls your API with the user's credential and a signed assertion; you authorize it.
  8. StreamText, tool activity and results stream to the UI as events, resumable after a disconnect.

Questions take the short path: the agent looks things up with your read operations and search, and answers with citations. Reads never ask for approval unless you say so.

Calls as the user#

rungent has no account in your product. Every call carries the user's own credential, so your permission checks run unchanged, and a Rungent-Assertion: a signed token naming the user, the operation, the exact request and the approval. Your API verifies it with rungent's public key. See Acting as the user.

The protocol#

The assistant speaks AG-UI over HTTP with server-sent events. rungent adds a small profile: a sequence number on every event, so a client that reconnects gets exactly what it missed, and four kinds of pause, each answered by the user:

Pause When The user answers with
Approval Before a write Approve or reject
Form Before an operation with a form The operation's complete arguments
Question The agent asks which thing or which action A choice
Task Your API runs the work later Nothing; your API reports back

Any AG-UI client can drive rungent; the React dock is one. See HTTP API.

How rungent differs#

Agent frameworks (LangGraph, Mastra, the Vercel AI SDK) give you a loop and leave the tools, identity and UI to you. OpenAPI generators (Stainless, Speakeasy) give developers SDKs and MCP servers that call your API with the developer's own key. rungent starts from the API you already have and runs the agent inside your product for the signed-in user, with your forms and an approval enforced in code. It combines with them: a long LangGraph workflow can be an operation that answers a deferred task.

Words used in these docs#

Word Meaning
Host Your product, the service whose API rungent calls
Catalog The operations of your OpenAPI that carry x-rungent, as one user sees them
Operation One HTTP endpoint in the catalog; a tool for the agent, MCP and the CLI
Effect What an operation does: read, create, update, delete, or reach outside
Write Any operation whose effect is not read
Surface Where an operation appears: the assistant, MCP, the CLI
Identity The one operation that says who a credential belongs to
Assertion The signed token on every call rungent makes for a user
Form The input an operation collects from the user before it runs
Routing The step that sends a request to change something to its form
Interrupt A pause in a run that waits for the user: approval, form, question or task
Dock The assistant panel beside your pages, from rungent/react

For agents: how-it-works.mdEdit this page