# 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.

*rungent between the surfaces people use and your product's API*

## 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

<ol class="planes">
<li><b>Embedded</b><ul class="main"><li>Your JavaScript API<small>Hono, Express, Workers, Node</small></li><li>rungent in the same process<small>one fetch handler</small></li></ul></li>
<li><b>Beside your API</b><ul class="bar"><li>Your API<small>Python, Go, Java, …</small></li><li>rungent serve next to it<small>your proxy forwards /rungent and /mcp</small></li></ul></li>
<li><b>Either way</b><ul><li>Same origin<small>your users' cookies just work</small></li><li>Same contract<small>OpenAPI in, assertions out</small></li></ul></li>
</ol>

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](javascript.md) embeds rungent; [Python and other stacks](python.md) 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.

<ol class="steps">
<li><b>Catalog</b>rungent reads your OpenAPI with the user's credential and keeps the operations marked x-rungent that the user may see.</li>
<li><b>Ground</b>If you gave rungent your docs, it searches them for the user's words first.</li>
<li><b>Route</b>A request to create or change something goes straight to that operation.</li>
<li><b>Form</b>The operation's form opens, prefilled: your page's own form in your app.</li>
<li><b>Resolve</b>Names the user typed ("train-01") become ids, through your list operations.</li>
<li><b>Approve</b>A write shows a card with its target and changes; the approval binds to those exact arguments.</li>
<li class="host"><b>Call</b>rungent calls your API with the user's credential and a signed assertion; you authorize it.</li>
<li><b>Stream</b>Text, tool activity and results stream to the UI as events, resumable after a disconnect.</li>
</ol>

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](acting-as-the-user.md).

## The protocol

The assistant speaks [AG-UI](https://docs.ag-ui.com) 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](http-api.md#events).

## 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](http-api.md#deferred-tasks).

## 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` |
