Events
aidy streams AG-UI 1.0 events. Any AG-UI client, such as CopilotKit or @ag-ui/client, can drive aidy without an adapter. This page is the aidy profile: the parts AG-UI leaves open, which aidy fixes. For the background, see AG-UI.
A thread is an aidy session. It belongs to one (subject, tenant) and has at most one active run at a time.
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 |
RUN_FINISHED.outcome.type is success, interrupt, or cancelled. RUN_ERROR.code is one of the run error codes. RUN_FINISHED.usage reports tokens. |
| 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 |
See Tool calls. |
| Progress | ACTIVITY_SNAPSHOT |
activityType: "aidy.progress", content: {message}. |
| Anything else | CUSTOM |
See Custom events. |
RUN_FINISHED.usage is a list with one entry per provider and model used in the run, each with the AG-UI token counts (inputTokens, outputTokens, totalTokens, reasoningTokens, cachedInputTokens, when the provider reports them).
Run error codes
Section titled “Run error codes”RUN_ERROR.code |
Meaning |
|---|---|
model_unavailable |
Every model in the chain failed. |
max_steps |
The run reached its step limit. |
open_interrupts |
The thread has open interrupts that resume[] did not answer. |
history_conflict |
messages changed a message aidy already holds. |
invalid_interaction |
A resume entry is invalid: an unknown or already answered interrupt, a payload that does not match its schema, an argsHash that does not match, or a user resolving a deferred task. |
internal |
Anything else, including a run that exceeded its time limit. |
Tool calls
Section titled “Tool calls”TOOL_CALL_START.metadata.aidyis{op, title, effect}. The built-in toolssearchandrequest_inputuse their own name asop.- The arguments arrive whole in one
TOOL_CALL_ARGS, redacted. TOOL_CALL_RESULT.contentis the redacted JSON result. A failure’s content is{"error": {"code", "message", "detail"?}};detailis the host’s error body for a failed host call, redacted like a result, whole when its JSON is at most 4 KB and otherwise its JSON text cut to 4 KB.TOOL_CALL_RESULT.metadata.aidyis{status: "succeeded" | "failed", error?: {code, message}, deduplicated?}.deduplicated: truemeans an identical write in the same run was answered from the first result (seerepeatablein x-aidy).
Tool error codes
Section titled “Tool error codes”These are returned to the model, which explains them in its own words; clients do not show them to users as errors.
| Code | Meaning |
|---|---|
invalid_arguments |
The arguments do not match the operation’s input schema. |
unresolved_reference |
A resolve lookup found no item, or several. |
repeated_call |
The model repeated a read that already succeeded in this run; its result is in the history. |
already_attempted |
An approved write of this operation already failed in this run; the model should tell the user why instead of retrying. |
not_executed |
The user declined or cancelled, the approval expired, or the approved call no longer matches the catalog. Nothing ran. |
credential_expired |
The user’s credential expired mid-run; the run pauses until the next request brings a fresh one. |
timeout |
The host did not answer within timeoutSeconds. |
http_{status} |
The host answered this HTTP status (http_403, http_500), with its error body as detail. A failed deferred task reports http_500. |
Interrupts
Section titled “Interrupts”A run pauses by finishing with outcome: {type: "interrupt", interrupts: [...]}. aidy uses three reasons. A run on a thread with open interrupts must answer every one of them in resume[]; a user who sends a new message instead sends cancelled for each.
Every resume entry has this shape:
{ "interruptId": "int_…", "status": "resolved", "payload": {}, "metadata": {} }status is resolved or cancelled. A cancelled entry needs no payload, and the call finishes with not_executed.
Approval
Section titled “Approval”Reason aidy:approval:
{ "id": "int_…", "reason": "aidy:approval", "message": "Stop server gpu-train-01?", "toolCallId": "call_…", "expiresAt": "2026-11-19T08:15:00Z", "responseSchema": { "type": "object", "properties": { "approved": { "type": "boolean" } }, "required": ["approved"] }, "metadata": { "aidy": { "op": "stop_vm", "arguments": { "vm_id": "vm-42", "forced": false }, "argsHash": "q2…", "impact": { "title": "Stop server gpu-train-01?", "target": "gpu-train-01", "effect": "update", "risk": "medium", "costHint": null, "changes": ["Force: No"] } } }}Resume entry:
{ "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } }}The echoed argsHash must equal the stored one. aidy then executes the frozen arguments, at most once. approved: false finishes the call with not_executed. An approval expires 15 minutes after it is asked (expiresAt). See Approvals.
Input (forms)
Section titled “Input (forms)”Reason aidy:input, with metadata.aidy.form:
{ "prompt": "Create a Kubernetes cluster", "questions": [ { "id": "name", "prompt": "Name", "kind": "text", "required": true }, { "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true, "options": [{ "id": "z1", "label": "Beijing A", "recommended": true }] } ]}A form has at most 24 questions. Each is text (with optional placeholder and default) or choice (with options, and optional multiple, allowCustom and default). An option has id, label, and optional description and recommended. responseSchema is derived from the form.
Resume entry:
{ "interruptId": "int_…", "status": "resolved", "payload": { "answers": { "name": "prod-eu", "zone_id": { "selected": ["z1"] } } }}A text answer is a string; a choice answer is {selected: [ids], custom?}. An invalid answer fails the run with invalid_interaction.
Forms come from two places: the model’s built-in request_input tool, and a host’s role: form operation named by x-aidy.form. In the second case each question id is the dotted path of the argument it fills. See Forms.
Deferred task
Section titled “Deferred task”Reason aidy:task, with metadata.aidy = {taskId, op}. An operation defers by answering 202 with {"aidyTask": "<id>"}. The host completes it with POST /aidy/v0/tasks/{taskId}, and aidy starts a run that resumes the interrupt. The user may only answer it as cancelled:
{ "interruptId": "int_…", "status": "cancelled" }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], ordered by n. Hits carry no content. |
aidy.context |
{usedTokens, budgetTokens, source: "estimated" | "provider"}. |
aidy.model.retry |
{step, attempt, maxAttempts, reason, endpoint, fallback}: attempt attempt (of maxAttempts) on chain endpoint endpoint failed for reason (http_429, timeout, unknown_tool, …); fallback is true when the next attempt goes to another endpoint. See Models. |
aidy.message.discard |
{messageId}: drop partial text from a model attempt that will be retried. |
aidy.task |
{taskId, status: "running" | "succeeded" | "failed" | "cancelled", message?}: progress of a deferred task. |
Clients skip custom events they do not know.
Sequence and SSE ids
Section titled “Sequence and SSE ids”Every event carries metadata.aidy.seq, a positive integer that increases monotonically per thread across runs. The SSE id: line is the same number:
id: 42data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_…","delta":"Stopping","metadata":{"aidy":{"seq":42}}}A client that reconnects sends Last-Event-ID (or ?after=) to GET /aidy/v0/threads/{id}/events and receives exactly what it missed. A run outlives its stream; only POST /aidy/v0/runs/{id}/cancel stops it.