Skip to content

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.

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.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_CALL_START.metadata.aidy is {op, title, effect}. The built-in tools search and request_input use their own name as op.
  • The arguments arrive whole in one TOOL_CALL_ARGS, redacted.
  • TOOL_CALL_RESULT.content is the redacted JSON result. A failure’s content is {"error": {"code", "message", "detail"?}}; detail is 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.aidy is {status: "succeeded" | "failed", error?: {code, message}, deduplicated?}. deduplicated: true means an identical write in the same run was answered from the first result (see repeatable in x-aidy).

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.

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.

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.

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.

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" }
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.

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: 42
data: {"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.