Skip to content

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

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}/runs
Content-Type: application/json
Accept: text/event-stream

The 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.messages may repeat messages aidy already holds; aidy appends only those with new ids. A changed earlier message fails the run with history_conflict.
  • Disconnects. A run outlives its HTTP response. Closing the stream does not cancel it; only POST /aidy/v0/runs/{id}/cancel does. A confirmed write therefore always finishes and is recorded.
  • User messages. A user message’s content is text, or AG-UI content parts of type text, image and document, at most 10 images and documents (below). Other parts answer 400.
  • 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.
{
"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.

Every event carries metadata.aidy.seq, a number that increases monotonically per thread, across runs. The SSE id: line holds the same number:

id: 41
data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"aidy":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}
id: 42
data: {"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=42

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

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.

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.

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.

  • @aidy-dev/client is a typed client of the HTTP API with an AG-UI reducer (reduceThread) and resume helpers (answerApproval, answerForm, cancelAll).
  • @aidy-dev/react renders threads, approval cards and forms on top of it.
  • Any AG-UI client can call POST /aidy/v0/threads/{id}/runs directly.

The protocol version string is aidy/0. See the HTTP API reference and the events reference.