事件
aidy 以 AG-UI 1.0 事件流式输出。任何 AG-UI 客户端,例如 CopilotKit 或 @ag-ui/client,都可以不加适配直接驱动 aidy。本页是 aidy profile:AG-UI 留给实现决定、由 aidy 固定下来的部分。背景见 AG-UI。
一个 thread 就是一个 aidy 会话。它归属于一个 (subject, tenant),同一时间最多有一个进行中的运行。
| 发生了什么 | AG-UI 事件 | aidy profile |
|---|---|---|
| 运行开始、结束或失败 | RUN_STARTED、RUN_FINISHED、RUN_ERROR |
RUN_FINISHED.outcome.type 为 success、interrupt 或 cancelled。RUN_ERROR.code 取值见 运行错误码。RUN_FINISHED.usage 报告 token 用量。 |
| 一个模型步骤 | STEP_STARTED、STEP_FINISHED |
stepName 为 model:{n}。 |
| 助手文本 | TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END |
增量合并到约 50 ms 一次。 |
| provider 的推理过程 | 无 | 原始推理内容从不发送。 |
| 工具调用 | TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_RESULT |
见 工具调用。 |
| 进度 | ACTIVITY_SNAPSHOT |
activityType: "aidy.progress",content: {message}。 |
| 其他 | CUSTOM |
见 自定义事件。 |
RUN_FINISHED.usage 是一个列表,运行中用到的每个 provider 和模型各占一项,包含 AG-UI 的 token 计数(inputTokens、outputTokens、totalTokens、reasoningTokens、cachedInputTokens,以 provider 实际报告的为准)。
RUN_ERROR.code |
含义 |
|---|---|
model_unavailable |
模型链中的所有模型都失败了。 |
max_steps |
运行达到步数上限。 |
open_interrupts |
会话有未完成的中断,而 resume[] 没有全部回应。 |
history_conflict |
messages 修改了 aidy 已保存的消息。 |
invalid_interaction |
恢复条目无效:中断不存在或已被回应、payload 与其 schema 不符、argsHash 不匹配,或用户试图完成延后任务。 |
internal |
其他错误,包括运行超出时间上限。 |
TOOL_CALL_START.metadata.aidy为{op, title, effect}。内置工具search和request_input以自身名字作为op。- 参数在一个
TOOL_CALL_ARGS中完整给出,已脱敏。 TOOL_CALL_RESULT.content是脱敏后的 JSON 结果。失败时内容为{"error": {"code", "message", "detail"?}};宿主调用失败时,detail是宿主的错误响应体,按结果的规则脱敏,JSON 不超过 4 KB 时完整保留,否则截取前 4 KB 的 JSON 文本。TOOL_CALL_RESULT.metadata.aidy为{status: "succeeded" | "failed", error?: {code, message}, deduplicated?}。deduplicated: true表示同一次运行中相同的写操作直接返回了第一次的结果(见 x-aidy 的repeatable)。
这些错误码返回给模型,由模型用自己的话解释;客户端不会把它们作为错误展示给用户。
| 错误码 | 含义 |
|---|---|
invalid_arguments |
参数不符合操作的输入 schema。 |
unresolved_reference |
resolve 查找没有匹配,或匹配到多个。 |
repeated_call |
模型重复了本次运行中已成功的读操作;结果已在历史中。 |
already_attempted |
本次运行中该操作的一次已审批写操作已经失败;模型应向用户说明原因,而不是重试。 |
not_executed |
用户拒绝或取消、审批过期,或已审批的调用与目录不再一致。没有执行任何操作。 |
credential_expired |
用户凭据在运行中过期;运行暂停,直到下一次请求带来新的凭据。 |
timeout |
宿主未在 timeoutSeconds 内响应。 |
http_{status} |
宿主返回了该 HTTP 状态(http_403、http_500),其错误响应体放在 detail 中。失败的延后任务报告为 http_500。 |
运行以 outcome: {type: "interrupt", interrupts: [...]} 结束即表示暂停。aidy 使用三种 reason。会话有未完成的中断时,下一次运行必须在 resume[] 中逐一回应;用户如果改为发送新消息,需要为每个中断附带 cancelled。
每个恢复条目的结构如下:
{ "interruptId": "int_…", "status": "resolved", "payload": {}, "metadata": {} }status 为 resolved 或 cancelled。cancelled 条目不需要 payload,对应的调用以 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"] } } }}恢复条目:
{ "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } }}回传的 argsHash 必须与保存的一致。随后 aidy 执行冻结的参数,最多执行一次。approved: false 使调用以 not_executed 结束。审批在发出 15 分钟后过期(expiresAt)。详见 审批。
输入(表单)
Section titled “输入(表单)”reason 为 aidy:input,附带 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 }] } ]}一个表单最多 24 个问题。每个问题是 text(可选 placeholder 和 default)或 choice(带 options,可选 multiple、allowCustom 和 default)。选项包含 id、label,可选 description 和 recommended。responseSchema 由表单推导。
恢复条目:
{ "interruptId": "int_…", "status": "resolved", "payload": { "answers": { "name": "prod-eu", "zone_id": { "selected": ["z1"] } } }}文本题的答案是字符串;选择题的答案是 {selected: [ids], custom?}。答案无效时运行以 invalid_interaction 失败。
表单有两个来源:模型的内置工具 request_input,以及由 x-aidy.form 指定的宿主 role: form 操作。后一种情况下,每个问题的 id 是它所填参数的点分路径。详见 表单。
reason 为 aidy:task,metadata.aidy 为 {taskId, op}。操作返回 202 和 {"aidyTask": "<id>"} 即表示延后执行。宿主通过 POST /aidy/v0/tasks/{taskId} 完成任务,aidy 随后发起一次运行来恢复该中断。用户只能以 cancelled 回应:
{ "interruptId": "int_…", "status": "cancelled" }name |
value |
|---|---|
aidy.ui.open |
{path}:展示这个产品页面,来自成功后的 x-aidy.open。 |
aidy.citation |
{messageId, citations: [{n, hit}]}:消息引用的每个搜索结果,n 是消息中写作 [n] 的编号,按 n 排序。结果不带 content。 |
aidy.context |
{usedTokens, budgetTokens, source: "estimated" | "provider"}。 |
aidy.model.retry |
{step, attempt, maxAttempts, reason, endpoint, fallback}:在链中端点 endpoint 上的第 attempt 次尝试(共 maxAttempts 次)因 reason(http_429、timeout、unknown_tool 等)失败;下一次尝试换到另一个端点时 fallback 为 true。见模型。 |
aidy.message.discard |
{messageId}:丢弃某次将被重试的模型尝试产生的部分文本。 |
aidy.task |
{taskId, status: "running" | "succeeded" | "failed" | "cancelled", message?}:延后任务的进度。 |
客户端跳过不认识的自定义事件。
序号与 SSE id
Section titled “序号与 SSE id”每个事件都带有 metadata.aidy.seq,这是一个正整数,在同一会话内跨运行单调递增。SSE 的 id: 行是同一个数字:
id: 42data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_…","delta":"Stopping","metadata":{"aidy":{"seq":42}}}客户端重连时,向 GET /aidy/v0/threads/{id}/events 发送 Last-Event-ID(或 ?after=),即可准确收到错过的事件。运行的生命周期长于事件流;只有 POST /aidy/v0/runs/{id}/cancel 能停止它。