跳转到内容

AG-UI profile

aidy 以 AG-UI 1.0 事件流式输出。任何 AG-UI 客户端(例如 CopilotKit 或 @ag-ui/client)都能直接驱动 aidy,无需适配器。aidy profile 补全了 AG-UI 留空的部分:序号、中断和少量自定义事件。aidy 自己的数据放在 metadata.aidy 下,或放在名为 aidy.* 的 CUSTOM 事件中。

一个 thread 就是一个 aidy 会话。它属于一个 (subject, tenant),同一时刻最多有一个活动的运行。

POST /aidy/v0/threads/{id}/runs
Content-Type: application/json
Accept: text/event-stream

请求体是 AG-UI 的 RunAgentInput,响应是这次运行的事件,以 server-sent events 形式返回。

  • 历史。 会话历史由服务端持有。RunAgentInput.messages 可以重复 aidy 已有的消息;aidy 只追加 id 为新的消息。修改过的早期消息会让运行以 history_conflict 失败。
  • 断线。 运行的生命周期长于它的 HTTP 响应。关闭流不会取消运行,只有 POST /aidy/v0/runs/{id}/cancel 才会。因此确认过的写操作总会执行完并被记录。
  • 用户消息。 用户消息的 content 是文本,或类型为 text、image、document 的 AG-UI content part,图片和文档合计最多 10 个(见下文)。其他类型返回 400。
  • 上下文。 RunAgentInput.context([{description, value}])描述用户正在看的内容:当前页面、选中的条目等。aidy 只把它作为信息(而非指令)加入本次运行的系统提示词:最多 16 条,值合计最多 8000 个字符,超出时先截掉靠后的条目。它不会被保存。
{
"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" } }
}
]
}

图片 part 的 source 是 url 或内联的 data。模型收到的内容:

来源 模型收到
路径(/files/shot.png),或宿主源下的 URL aidy 以用户身份(用户凭据,不带断言)从宿主获取该文件并内联。最大 5 MB;更大或被拒绝的文件换成一条说明。
其他 http(s) URL URL 本身,由服务商自行获取。
data(最大 5 MB) 数据本身。

图片只发给带 vision 的端点,按链的顺序优先。没有视觉端点能回答时,其他端点只收到文本,每张图片的位置换成一条说明;链中根本没有视觉端点时,aidy 不会去获取图片(见模型)。没有用户凭据的运行(例如恢复延迟任务的运行)无法获取宿主文件,会注明这些文件不可用。

document part(用户附加的文件)如果是文本类(text/*、JSON、XML、YAML、CSV),会以同样方式获取,并以文本形式交给模型,最多 20 000 个字符;其他文档不会被读取。

每个图片和文档之前,aidy 都会为模型加一段说明它的文本:[Attachment "shot.png" (image/png): /files/shot.png],内联数据以外都带 URL。这样不支持视觉、或读不了该文件的模型,仍然可以提到它,或把它的 URL 传给工具。文件名放在 metadata.aidy.name 中。

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

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

每一帧由一行 id: 和一行包含事件 JSON 的 data: 组成。事件之间,aidy 会发送 : keepalive 注释行,SSE 客户端会忽略它们。

断线的客户端重新连接到:

GET /aidy/v0/threads/{id}/events?after=42

aidy 重放该 seq 之后的所有事件,然后继续实时推送。该接口同样支持 Last-Event-ID,所以浏览器的 EventSource 能自动续上。

发生了什么 AG-UI 事件 aidy profile
运行开始、结束或失败 RUN_STARTED、RUN_FINISHED、RUN_ERROR outcome 为 success、interrupt 或 cancelled。RUN_FINISHED.usage 报告 token 用量。RUN_ERROR.code 为 model_unavailable、max_steps、open_interrupts、history_conflict 或 internal。
一个模型步骤 STEP_STARTED、STEP_FINISHED stepName 为 model:{n}。
助手文本 TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END 增量合并为约 50 ms 一批。
模型推理过程 无 原始推理内容从不发送。
工具调用 TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_RESULT TOOL_CALL_START.metadata.aidy 为 {op, title, effect}。参数经过脱敏,在一个 TOOL_CALL_ARGS 中完整到达。TOOL_CALL_RESULT.content 是脱敏后的 JSON 结果,其 metadata.aidy 为 {status, error?, deduplicated?}。
进度 ACTIVITY_SNAPSHOT activityType: "aidy.progress",content: {message}。
其他 CUSTOM 见自定义事件。

工具结果的 status 为 succeeded 或 failed。失败时带有 error: {code, message},错误码为 invalid_arguments、unresolved_reference、repeated_call、already_attempted、not_executed、credential_expired、timeout 或 http_{status} 之一。宿主调用失败时,结果还带有 detail:宿主的错误响应体,按结果的规则脱敏(JSON 不超过 4 KB 时完整保留,否则截取前 4 KB 的 JSON 文本),让模型能根据结构化字段修正调用。这些错误返回给模型,由模型解释;客户端不会把它们当作错误展示给用户。

运行以 outcome: {type: "interrupt", interrupts: [...]} 结束来表示暂停。aidy 使用三种 reason:

reason metadata.aidy 回答
aidy:approval {op, arguments, argsHash, impact} payload: {approved: true | false},并回传 metadata.aidy.argsHash。见审批。
aidy:input {form} payload: {answers: {...}}。见表单。
aidy:task {taskId, op} 由宿主完成;用户只能发送 cancelled。

每个中断都有 id、message、所属的 toolCallId,以及描述其 payload 的 responseSchema。审批还有 expiresAt,为 15 分钟之后。

下一次运行在 RunAgentInput.resume[] 中作答:

{
"threadId": "th_…",
"runId": "run_…",
"messages": [],
"resume": [
{
"interruptId": "int_…",
"status": "resolved",
"payload": { "approved": true },
"metadata": { "aidy": { "argsHash": "q2…" } }
}
]
}

会话有未关闭的中断时,新的运行必须按 AG-UI 的要求回答其中每一个,否则以 RUN_ERROR、错误码 open_interrupts 失败。用户如果直接发送新消息,需要同时为每个未关闭的中断发送 {interruptId, status: "cancelled"}。

延迟任务。 操作通过返回 202 和 {"aidyTask": "<id>"} 进入延迟状态,运行以 aidy:task 暂停。之后宿主调用 POST /aidy/v0/tasks/{taskId},请求体为 {status: "succeeded" | "failed", result},并附 Aidy-Host-Assertion 签名,aidy 随即启动一次恢复该中断的运行。

name value
aidy.ui.open {path}:展示这个产品页面。来自成功后的 x-aidy.open。
aidy.citation {messageId, citations: [{n, hit}]}:消息引用的每个搜索结果,n 是消息中写作 [n] 的编号。结果不带 content。
aidy.context {usedTokens, budgetTokens, source: "estimated" | "provider"}。
aidy.model.retry {step, attempt, maxAttempts, reason, endpoint, fallback}:在链中端点 endpoint 上的这次尝试失败;下一次尝试换到另一个端点时 fallback 为 true。
aidy.message.discard {messageId}:丢弃某次将被重试的模型尝试输出的部分文本。
aidy.task {taskId, status, message?}:延迟任务的进度。

客户端会跳过不认识的自定义事件。通用的 AG-UI 客户端依然能正确渲染文本、工具调用和中断;处理 aidy.message.discard 可以避免显示被重试尝试的半截文本。

  • @aidy-dev/client 是 HTTP API 的类型化客户端,带有 AG-UI reducer(reduceThread)和恢复辅助函数(answerApproval、answerForm、cancelAll)。
  • @aidy-dev/react 在它之上渲染会话、审批卡片和表单。
  • 任何 AG-UI 客户端都可以直接调用 POST /aidy/v0/threads/{id}/runs。

协议版本字符串为 aidy/0。见 HTTP API 参考和事件参考。