rungentReference
HTTP API
Every endpoint rungent serves on your origin, how each is authenticated, the AG-UI events a run streams, the interrupts and how to answer them, and the shapes of answers and errors.
rungent serves these paths on your own origin. An embedded runtime answers them in your process;
with rungent serve, your proxy forwards them. Every path under /rungent/v0 speaks JSON, except the
two that stream events. rungent/client is a typed client of all of it.
Endpoints#
| Endpoint | Who calls it | Purpose |
|---|---|---|
POST /rungent/v0/threads |
user | Create a thread: {title?} → 201 {id, title, createdAt}. |
GET /rungent/v0/threads?cursor= |
user | The user's threads, newest first, 20 a page, with next. |
GET /rungent/v0/threads/{id} |
user | A thread with its AG-UI messages and open interrupts. |
PATCH /rungent/v0/threads/{id} |
user | Rename: {title}, 1 to 200 characters. |
DELETE /rungent/v0/threads/{id} |
user | Cancel its run and delete it with everything it holds; 204. |
POST /rungent/v0/threads/{id}/runs |
user | Start a run; the answer is its events (SSE). |
GET /rungent/v0/threads/{id}/events?after={seq} |
user | Replay events after seq, then follow live (SSE). |
POST /rungent/v0/runs/{id}/cancel |
user | Cancel a run: 202 {id, status: "cancelling"}. |
PUT /rungent/v0/threads/{id}/messages/{messageId}/feedback |
user | Rate an assistant message: {rating: "up" | "down", comment?}. |
GET /rungent/v0/feedback?since=&limit=&cursor= |
rungent:admin |
The tenant's ratings, oldest first. |
GET /rungent/v0/info |
anyone | {name}: the assistant's name. |
GET /rungent/v0/catalog |
user | The operations this user can see, with their input schemas. |
GET /rungent/v0/search?q=&limit=&types= |
user | Federated search. |
GET /rungent/v0/settings |
user | The model chain in effect, without keys. |
PUT, DELETE /rungent/v0/settings |
rungent:admin |
Replace or forget the saved model chain. |
POST /rungent/v0/tasks/{taskId} |
your API | Complete a deferred task. |
POST /rungent/v0/generate |
your API | One model completion for a job of yours. |
/mcp |
user | MCP over streamable HTTP. |
GET /skill.md, GET /llms.txt |
anyone | Documents for agents, generated from the caller's catalog. |
GET /.well-known/rungent-keys.json |
anyone | rungent's public signing keys, for inspection. |
GET /.well-known/oauth-protected-resource/mcp |
anyone | MCP's OAuth metadata, when authorization servers are configured. |
The protocol version is rungent/0; a minor release may still change it, and the
changelog lists every break.
Authentication#
A user's request carries the credential your app already uses: its Authorization header, its
Cookie header, or both. rungent forwards them to your identity operation to learn who the user is
(Acting as the user). A request with neither, or one your
identity operation refuses, answers 401 unauthorized. A thread belongs to the
(subject, tenant) that created it; anyone else gets 404.
Your API's own calls, POST /rungent/v0/tasks/{taskId} and POST /rungent/v0/generate, carry an
Rungent-Host-Assertion instead.
rungent refuses requests another site could make for a user signed in with cookies. Every POST,
PUT, PATCH and DELETE with Sec-Fetch-Site: cross-site answers 403 cross_site. Outside
/mcp, a body must be application/json, else 415 unsupported_media_type.
Errors#
Every error outside an event stream is {"error": {"code", "message"}}:
| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
The body or a query parameter is invalid; the message says which. |
| 401 | unauthorized |
No credential, or your identity operation refused it. |
| 401 | rungent_assertion_invalid |
A task completion or host job without a valid Rungent-Host-Assertion. |
| 403 | forbidden, cross_site |
Needs rungent:admin; or a cross-site write. |
| 404 | not_found, session_not_found |
No such thread, message, run or task for this caller; an unknown MCP session. |
| 409 | run_active, task_closed |
The thread already has a run in progress; the task was completed or cancelled. |
| 415 | unsupported_media_type |
A body that is not application/json. |
| 422 | invalid_output |
A host job's answer still does not fit its schema after one repair. |
| 502 | host_unavailable |
rungent could not read your OpenAPI document. |
| 503 | settings_unreadable, model_unavailable |
Settings sealed with a lost secret; no model could answer a host job. |
| 504 | timeout |
A host job ran past the run timeout. |
| 500 | internal |
Anything else. |
Start a run#
POST /rungent/v0/threads/{id}/runs takes AG-UI RunAgentInput. rungent reads three fields:
{
"messages": [{ "id": "m_1", "role": "user", "content": "Stop gpu-train-01" }],
"context": [{ "description": "The page the user is on", "value": "/console/instance/vm-42" }],
"resume": []
}
messages. rungent owns the history: send the thread's messages or only the new one, and rungent appends those whose ids it has not seen. A changed earlier message fails the run withhistory_conflict. A user message'scontentis text, or AG-UI parts of typetext,imageanddocument, at most 10 images and documents.context. What the user is looking at, added to this run's prompt as information, never as instructions: at most 16 entries and 8000 characters. It is not stored.resume. The answers to the thread's open interrupts; see Interrupts.
The answer is text/event-stream, ending after RUN_FINISHED or RUN_ERROR. A run outlives its
response: closing the stream does not stop it, so an approved write always finishes and is
recorded. Only a cancel stops a run.
An image or document part's source is a URL or inline data. A path or URL on your origin
is fetched from your API with the user's credential, up to 5 MB; another URL is passed to the
model provider; inline data may be up to 5 MB. Images go only to vision endpoints; a text-like
document is given to the model as text, up to 20 000 characters.
Events#
A run streams AG-UI 1.0 events. Each frame is an id: line with the
event's sequence number and a data: line with its JSON, and : keepalive comments come between
events. rungent's own data sits under metadata.rungent, or in CUSTOM events named rungent.*.
id: 41
data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"rungent":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}
id: 44
data: {"type":"RUN_FINISHED","threadId":"th_1","runId":"run_7","outcome":{"type":"interrupt","interrupts":[{"id":"int_3","reason":"rungent:approval",…}]},"metadata":{"rungent":{"seq":44}}}
| What happens | AG-UI events | What rungent fixes |
|---|---|---|
| A run starts, ends or fails | RUN_STARTED, RUN_FINISHED, RUN_ERROR |
RUN_FINISHED.outcome.type is success, interrupt or cancelled; its usage lists tokens per provider and model. RUN_ERROR.code is a run error code. |
| One model step | STEP_STARTED, STEP_FINISHED |
stepName is model:1, model:2, … |
| Assistant text | TEXT_MESSAGE_START, _CONTENT, _END |
Deltas are coalesced to about 50 ms. Raw reasoning is never sent. |
| A tool call | TOOL_CALL_START, _ARGS, _END, _RESULT |
START carries {op, title, effect}; the arguments arrive whole and redacted; RESULT.metadata.rungent is {status, error?, deduplicated?}. |
| Progress | ACTIVITY_SNAPSHOT |
activityType is rungent.progress, content is {message}. |
| Anything else | CUSTOM |
See Custom events. |
A failed call's result is {"error": {code, message, detail?}}, where detail is your API's
error body, redacted and cut to 4 KB, so the model can correct the call from your fields. With
knowledge, a run that appends a user message starts with a search call before model:1.
Run error codes#
RUN_ERROR.code |
Meaning |
|---|---|
model_unavailable |
No endpoint of the model chain could answer. |
max_steps |
The run reached its step limit (16 by default). |
open_interrupts |
The thread has open interrupts that resume did not answer. |
history_conflict |
messages changed a message rungent already holds. |
invalid_interaction |
A resume entry is invalid: unknown or answered interrupt, a payload that does not fit its responseSchema, an argsHash that does not match, or a user resolving a task. |
internal |
Anything else, including a run past its time limit (600 s by default). |
Tool error codes#
These go back to the model, which explains them in its own words; a client does not show them as errors.
| Code | Meaning |
|---|---|
invalid_arguments |
The arguments do not fit the input schema. An operation with a form opens its form instead. |
unresolved_reference |
A name matched no item, or several. |
repeated_call |
A read that already succeeded in this run, repeated. |
already_attempted |
An approved write of this operation already failed in this run. |
not_executed |
The user rejected or cancelled, the approval expired, or the call no longer fits the catalog. Nothing ran. |
credential_expired |
The user's credential expired mid-run, or the run has none (it resumes a task). |
timeout |
Your API did not answer within timeoutSeconds. |
http_{status} |
Your API answered this status (http_403), with its body as detail. |
Interrupts#
A run pauses by ending with outcome: {type: "interrupt", interrupts: [...]}. Every interrupt has
an id, a reason, a message to show, its toolCallId, rungent's data in metadata.rungent, and,
except tasks, a responseSchema for the answer.
reason |
When | metadata.rungent |
The answer's payload |
|---|---|---|---|
rungent:approval |
Before a write | {op, arguments, argsHash, impact} |
{approved} |
rungent:form |
Before an operation with a form | {op, arguments, form, issues?} |
{arguments} |
rungent:input |
The model asks which thing or which action | {form} |
{answers} |
rungent:task |
Your API runs the work later | {taskId, op} |
none; your API completes it |
The next run answers every open interrupt in resume:
{ "interruptId": "int_3", "status": "resolved", "payload": { "approved": true }, "metadata": { "rungent": { "argsHash": "q2…" } } }
status is resolved or cancelled; a cancelled entry needs no payload, and its call ends with
not_executed. A user who types a new message instead sends cancelled for each open interrupt
alongside it.
Approval (rungent:approval)#
impact is the card: {title, target, effect, risk, costHint, changes}, from the operation's
confirmation, with changes its fields as label: value. The answer
is {approved: true | false} with metadata.rungent.argsHash echoing the hash. rungent then runs the
frozen arguments, at most once. An approval expires 15 minutes after it is asked (expiresAt).
Form (rungent:form)#
{
"op": "create_vm",
"arguments": { "name": "prod" },
"form": { "prompt": "Create a server",
"questions": [{ "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true, "options": [{ "id": "z1", "label": "Beijing A" }] }] },
"issues": [{ "path": "zone_id", "message": "required" }]
}
arguments are what the form starts from; form is your generic form, for a client without the
product's own component; issues say why the last submission was refused. The answer is
{arguments}, the operation's complete arguments. A client showing the generic form builds
them with answersToArguments from rungent/protocol, which sets each answer at its
question's dotted path.
A form, here and in rungent:input, has a prompt and 1 to 24 questions with unique ids:
| Question | Keys |
|---|---|
text |
id, prompt, kind: "text", required, optional placeholder and default |
choice |
id, prompt, kind: "choice", required, options (at least one), optional multiple, allowCustom and default |
| option | id, label, optional description and recommended |
Question (rungent:input)#
The model's request_input tool asks which thing or which action the user means, as {form}. The
answer is {answers: {questionId: answer}}: a string for a text question,
{selected: [optionIds], custom?} for a choice.
Task (rungent:task)#
An operation that answers 202 {"rungentTask": "<id>"} pauses the run and emits rungent.task with
status: "running". Your API completes it with POST /rungent/v0/tasks/{taskId};
the user may only answer it as cancelled.
Custom events#
name |
value |
|---|---|
rungent.ui.open |
{path}: show this product page, from x-rungent.open after success. |
rungent.citation |
{messageId, citations: [{n, hit}]}: each search hit the message cites as [n]. Hits carry no content. |
rungent.context |
{usedTokens, budgetTokens, source}: how full the model's context is. |
rungent.model.retry |
{step, attempt, maxAttempts, reason, endpoint, fallback}: a model attempt failed and is retried. |
rungent.message.discard |
{messageId}: drop the partial text of an attempt that will be retried. |
rungent.task |
{taskId, status, message?}: a task's progress. |
Clients skip custom events they do not know; a generic AG-UI client still shows text, tool calls and interrupts correctly.
Replay after a disconnect#
seq increases by thread, across runs, and the SSE id: line is the same number. A client that
loses the stream reconnects with GET /rungent/v0/threads/th_1/events?after=44: rungent replays every
event after it, then follows the thread live. Last-Event-ID works too, so a browser
EventSource resumes on its own.
Catalog and search#
GET /rungent/v0/catalog answers {operations: [{name, title, description, effect, approval, surfaces, input}]}, without role operations; input is the
input schema.
GET /rungent/v0/search takes q (required), limit (default 10, at most 50) and types
(comma-separated). It answers {hits, failed}: each hit names its source and carries no
content; each failed source is {source, code} with timeout, http_<status> or
invalid_response.
Settings#
GET /rungent/v0/settings answers {models: {chain: [...]}}, each entry with hasApiKey and never a
key; an entry from code shows as provider custom. PUT replaces the whole chain with entries of
the model chain's fields; an entry sent without apiKey keeps the
stored key of the entry with the same id. DELETE forgets the saved chain, so the configured one
applies again. Both need rungent:admin and answer as GET does.
Deferred tasks#
When the work of a 202 operation is done, your API completes the task:
POST /rungent/v0/tasks/task_123
Content-Type: application/json
Rungent-Host-Assertion: <compact JWS>
{"status": "succeeded", "result": {"id": "vm-43"}}
status is succeeded or failed; result becomes the tool result, redacted as the operation
says. The assertion's op is the operation that deferred, and its sub and ten the thread
owner's. It answers 202 {"runId"}: rungent starts a run that resumes the interrupt. That run has no
user credential, so a call it makes to your API fails with credential_expired.
Host jobs#
POST /rungent/v0/generate is one model completion for a job of yours, such as a weekly report's
summary, signed with a Rungent-Host-Assertion whose op is generate:
{
"instructions": "Write the weekly report's summary in two sentences.",
"input": "Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).",
"schema": { "type": "object", "properties": { "headline": { "type": "string" } }, "required": ["headline"] },
"maxOutputTokens": 400
}
input is required (up to 200 000 characters). With schema, the answer is {object}, valid
against it; without, {text}. The call uses the model chain without tools or a thread; an answer
that does not fit schema goes back to the model once.
Host assertions#
Rungent-Host-Assertion has the shape of the assertion rungent sends you: an EdDSA compact JWS with
header {"alg": "EdDSA", "kid", "typ": "rungent-call+jwt"}, signed with a key rungent pins in
hostKeys (RUNGENT_HOST_KEYS).
| Claim | Value |
|---|---|
iss |
Your origin. |
aud |
rungent's own URL. |
sub, ten |
Whom the call is for. |
sid, rid, cid |
Ids of your choosing, for audit. |
op |
The deferred operation, or generate. |
htm, htu |
POST, and the origin of rungent's public URL followed by the path you post to. |
bsh |
base64url SHA-256 of the exact body. |
iat, exp, jti |
At most 60 seconds apart; each jti is accepted once. |
A JavaScript host signs with signAssertion from rungent/delegation. In other
languages, any Ed25519 JWS library makes the token.
Documents and keys#
/skill.md (text/markdown) and /llms.txt (text/plain) answer 200 with or without a
credential. With one, they list the caller's operations. Without one, they list the catalog your
API serves anonymously; if that answers 401 or 403, they hold the guide and how to connect,
and rungent remembers that for 5 minutes. /.well-known/rungent-keys.json is
{"keys": [{"kty": "OKP", "crv": "Ed25519", "x", "kid"}]}. On /mcp, each tool carries its CLI
spelling in _meta.rungent ({command, args, effect}).
For agents: http-api.mdEdit this page