跳转到内容

事件

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)。详见 审批。

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?}:延后任务的进度。

客户端跳过不认识的自定义事件。

每个事件都带有 metadata.aidy.seq,这是一个正整数,在同一会话内跨运行单调递增。SSE 的 id: 行是同一个数字:

id: 42
data: {"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 能停止它。