rungent v0.5.1
EN中文

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 with history_conflict. A user message's content is text, or AG-UI parts of type text, image and document, 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.

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