AG-UI profile
aidy streams AG-UI 1.0 events. Any AG-UI client, such as CopilotKit
or @ag-ui/client, can drive aidy without an adapter. The aidy profile fixes the parts
AG-UI leaves open: sequence numbers, interrupts and a few custom events. aidy’s own data goes
under metadata.aidy or in CUSTOM events named aidy.*.
Threads and runs
Section titled “Threads and runs”A thread is an aidy session. It belongs to one (subject, tenant) and has at most one active
run at a time.
POST /aidy/v0/threads/{id}/runsContent-Type: application/jsonAccept: text/event-streamThe body is AG-UI RunAgentInput, and the response is that run’s events as server-sent events.
- History. The server owns a thread’s history.
RunAgentInput.messagesmay repeat messages aidy already holds; aidy appends only those with new ids. A changed earlier message fails the run withhistory_conflict. - Disconnects. A run outlives its HTTP response. Closing the stream does not cancel it;
only
POST /aidy/v0/runs/{id}/canceldoes. A confirmed write therefore always finishes and is recorded. - User messages. A user message’s
contentis text, or AG-UI content parts of typetext,imageanddocument, at most 10 images and documents (below). Other parts answer400. - Context.
RunAgentInput.context([{description, value}]) is what the user is looking at: the page, the selected item. aidy adds it to this run’s system prompt only, as information rather than instructions: at most 16 entries and 8000 characters of values, later entries cut first. It is not stored.
User messages
Section titled “User messages”{ "id": "m_1", "role": "user", "content": [ { "type": "text", "text": "Why is this box slow?" }, { "type": "image", "source": { "type": "url", "value": "/files/shot.png", "mimeType": "image/png" }, "metadata": { "aidy": { "name": "shot.png" } } } ]}An image part’s source is a url or inline data. aidy gives the model:
| Source | The model gets |
|---|---|
A path (/files/shot.png), or a URL on the host’s origin |
The file, fetched from the host as the user (the user’s credential, no assertion) and inlined. At most 5 MB; a larger or refused file becomes a note. |
Another http(s) URL |
The URL, for the provider to fetch. |
data (at most 5 MB) |
The data. |
Images go only to endpoints with vision, first in chain order. When no vision endpoint can
answer, the others get the text alone, with a note in place of each image; without any vision
endpoint aidy never fetches the images (Models). A run without a
user credential, such as one resuming a deferred task, cannot fetch host files and notes them
as unavailable.
A document part (a file the user attached) whose type is text-like (text/*, JSON, XML,
YAML, CSV) is fetched the same way and given to the model as text, up to 20 000 characters;
other documents are not read.
Every image and document is preceded, for the model, by a text part naming it:
[Attachment "shot.png" (image/png): /files/shot.png], with its URL unless it is inline data.
A model without vision, or one that cannot read the file, can still refer to it or pass its URL
to a tool. The file name travels in metadata.aidy.name.
Sequence and replay
Section titled “Sequence and replay”Every event carries metadata.aidy.seq, a number that increases monotonically per thread,
across runs. The SSE id: line holds the same number:
id: 41data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"aidy":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}
id: 42data: {"type":"TOOL_CALL_ARGS","toolCallId":"call_1","delta":"{\"vm_id\":\"vm-42\",\"forced\":false}","metadata":{"aidy":{"seq":42}}}Each frame is an id: line and a data: line with the event JSON. Between events, aidy sends
: keepalive comment lines, which SSE clients ignore.
A client that loses the connection reconnects to:
GET /aidy/v0/threads/{id}/events?after=42aidy replays every event after that seq, then follows the thread live. The endpoint also
honors Last-Event-ID, so a browser EventSource resumes on its own.
Event mapping
Section titled “Event mapping”| What happens | AG-UI event | aidy profile |
|---|---|---|
| A run starts, finishes or fails | RUN_STARTED, RUN_FINISHED, RUN_ERROR |
outcome is success, interrupt or cancelled. RUN_FINISHED.usage reports tokens. RUN_ERROR.code is model_unavailable, max_steps, open_interrupts, history_conflict or internal. |
| One model step | STEP_STARTED, STEP_FINISHED |
stepName is model:{n}. |
| Assistant text | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END |
Deltas are coalesced to about 50 ms. |
| Provider reasoning | none | Raw reasoning is never sent. |
| A tool call | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT |
TOOL_CALL_START.metadata.aidy is {op, title, effect}. The arguments arrive whole, redacted, in one TOOL_CALL_ARGS. TOOL_CALL_RESULT.content is the redacted JSON result, with metadata.aidy = {status, error?, deduplicated?}. |
| Progress | ACTIVITY_SNAPSHOT |
activityType: "aidy.progress", content: {message}. |
| Anything else | CUSTOM |
See Custom events. |
A tool result’s status is succeeded or failed. Failures carry error: {code, message}
with one of invalid_arguments, unresolved_reference, repeated_call, already_attempted,
not_executed, credential_expired, timeout or http_{status}. A failed host call’s result
also has detail, the host’s error body, redacted like a result (whole up to 4 KB of JSON,
otherwise its JSON text cut to 4 KB), so the model can correct the call from structured fields.
These go back to the model, which explains them; clients do not show them to users as errors.
Interrupts
Section titled “Interrupts”A run pauses by finishing with outcome: {type: "interrupt", interrupts: [...]}. aidy uses three
reasons:
reason |
metadata.aidy |
Answer |
|---|---|---|
aidy:approval |
{op, arguments, argsHash, impact} |
payload: {approved: true | false}, echoing metadata.aidy.argsHash. See Approvals. |
aidy:input |
{form} |
payload: {answers: {...}}. See Forms. |
aidy:task |
{taskId, op} |
Completed by the host; the user may only send cancelled. |
Each interrupt has an id, a message, the toolCallId it belongs to, and a
responseSchema describing its payload. Approvals also have expiresAt, 15 minutes out.
The next run answers in RunAgentInput.resume[]:
{ "threadId": "th_…", "runId": "run_…", "messages": [], "resume": [ { "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } } } ]}A run on a thread with open interrupts must answer every one of them, as AG-UI requires.
Otherwise it fails with RUN_ERROR code open_interrupts. A user who sends a new message
instead sends {interruptId, status: "cancelled"} for each open interrupt, alongside the
message.
Deferred tasks. An operation defers by answering 202 with {"aidyTask": "<id>"}. The run
pauses with aidy:task. Your host later calls POST /aidy/v0/tasks/{taskId} with
{status: "succeeded" | "failed", result}, signed with an
Aidy-Host-Assertion, and aidy starts a
run that resumes the interrupt.
Custom events
Section titled “Custom events”name |
value |
|---|---|
aidy.ui.open |
{path}: show this product page. It comes from x-aidy.open after success. |
aidy.citation |
{messageId, citations: [{n, hit}]}: each search hit the message cites, under the number n it wrote as [n]. Hits carry no content. |
aidy.context |
{usedTokens, budgetTokens, source: "estimated" | "provider"}. |
aidy.model.retry |
{step, attempt, maxAttempts, reason, endpoint, fallback}: the attempt on chain endpoint endpoint failed; fallback is true when the next attempt goes to another endpoint. |
aidy.message.discard |
{messageId}: drop partial text from a model attempt that will be retried. |
aidy.task |
{taskId, status, message?}: progress of a deferred task. |
Clients skip custom events they do not know. A generic AG-UI client still renders text, tool
calls and interrupts correctly; handling aidy.message.discard keeps it from showing partial
text of a retried attempt.
Clients
Section titled “Clients”@aidy-dev/clientis a typed client of the HTTP API with an AG-UI reducer (reduceThread) and resume helpers (answerApproval,answerForm,cancelAll).@aidy-dev/reactrenders threads, approval cards and forms on top of it.- Any AG-UI client can call
POST /aidy/v0/threads/{id}/runsdirectly.
The protocol version string is aidy/0. See the HTTP API reference
and the events reference.