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.
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#
- Embedded
- Your JavaScript APIHono, Express, Workers, Node
- rungent in the same processone fetch handler
- Beside your API
- 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.
- Catalogrungent reads your OpenAPI with the user's credential and keeps the operations marked x-rungent that the user may see.
- GroundIf you gave rungent your docs, it searches them for the user's words first.
- RouteA request to create or change something goes straight to that operation.
- FormThe operation's form opens, prefilled: your page's own form in your app.
- ResolveNames the user typed ("train-01") become ids, through your list operations.
- ApproveA write shows a card with its target and changes; the approval binds to those exact arguments.
- Callrungent calls your API with the user's credential and a signed assertion; you authorize it.
- 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