iTool.AgentKernel.AGUI 4.0.0

iTool.AgentKernel.AGUI

AG-UI 协议适配层：把 AgentKernel 的持久会话（IAgentBusinessClient）投射为标准 AG-UI SSE 事件流，使 CopilotKit 及任何 AG-UI 前端可以直接对接，替代 Workspace 自研的 AgentUI 跨端契约。

适配层只做协议翻译。会话、授权、工具准入、持久化仍全部属于 Kernel 与业务宿主。

事件源与协议

• 协议类型与序列化来自官方 AGUI.Abstractions 1.0.0（不从 0 发明协议）。
• 事件源是 durable 事件账本：每个 AG-UI 事件携带 Kernel journal 的 sequence， 断线可用 Last-Event-ID 头重连续传（标准 AG-UI 前端不具备该能力，此处为附加收益）。
• 前端重试发送同一 message.id 的用户消息时，由 Kernel 的 AgentInputReceipt 输入幂等去重，不会产生重复 run。

事件映射

运行编排

• 首次出现且 Kernel 中无注册 → CreateAsync 后 RunMessageStreamingAsync； 已存在的 thread → FollowUpStreamingAsync（受会话的 FollowUpMode 约束）。
• RunAgentInput.resume（AG-UI interrupt 恢复）→ 有 pending 交互时经 AnswerQuestionAsync 绑定原 interaction id 提交，再从 LastSequence 续流； 无交互的中断（余额等待等）直接续流重入。
• Last-Event-ID 头 → 仅 WatchAsync(afterSequence)，不重复发起业务 run。

扩展点（客户端预留接口）

前端声明的工具（RunAgentInput.tools）当前一律不进入 Kernel：Kernel 工具由宿主 预授权（见生产验收 AK-M3/AK-M5）。Admit 语义为预留扩展位。

接入

builder.Services.AddAgentKernelOrleans(...);      // 已有
builder.Services.AddAgentKernelAGUI(o => o.DefaultConfigurationReference = "workspace-default");

app.MapAgentKernelAGUI("/agui")
   .RequireAuthorization();                        // 认证归属宿主，适配层不设身份
app.MapAgentKernelAGUICommand("/agui/command");     // cancel 原生；其余路由到 IAGUICommandHandler

控制命令（POST /agui/command）

{threadId, command, payload}：

• cancel：原生映射 CancelAsync；Kernel 稳定异常翻译为 {status:"rejected", reason:稳定码}。 会话配置按 Kernel 契约冻结（配置身份哈希），switch-model 只对新建会话生效。
• 其余命令按 IAGUICommandHandler.Commands 匹配；无命中返回 404 unknown_command。

跨 run 命令（forwardedProps）

• {"command":"edit-last","targetMessageId":"..."} → EditLastMessageStreamingAsync， 取最后一条 user 消息为修订文本。
• {"model":"..."} → 透传给 IAGUISessionResolver，会话创建时绑定模型。

断线重连

SSE 帧携带 Kernel journal 序列；断线后带 Last-Event-ID: <sequence> 重发即从该游标 回放/续播，不重复发起业务 run。run 边界按事件 kind 判定 （completed/canceled/failed/user_input_requested/balance_required）——重放事件上的 status 是实时值，不作为边界依据。

CopilotKit 前端

import { CopilotKit } from "@copilotkit/react-core";

<CopilotKit runtimeUrl="https://host/agui">
  {/* CopilotChat / useCoAgent ... */}
</CopilotKit>

注意：CopilotKit 前端重试会重发全量 messages；适配层只取最后一条 user 消息， 历史以 Kernel/DASP 为准，消息 id 即幂等键，因此重放安全。

红线

1. 不在适配层引入新的授权/工具语义；跨端契约的复杂度只收敛在这一层。
2. 协议随 AGUI.Abstractions 版本走；升级时事件映射表由测试锁死 （见 tests/iTool.AgentKernel.AGUI.Tests）。