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}/runsContent-Type: application/jsonAccept: 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: 41data: {"type":"TOOL_CALL_START","toolCallId":"call_1","toolCallName":"stop_vm","metadata":{"aidy":{"seq":41,"op":"stop_vm","title":"Stop server","effect":"update"}}}
id: 42data: {"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=42aidy 重放该 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 参考和事件参考。