[RFC] useXChat AgentProvider：模型无关的 Agent 事件接入

[kimteayon]

[RFC] useXChat AgentProvider：模型无关的 Agent 事件接入

• RFC 状态：Draft
• 实现状态：Experimental
• 日期：2026-08-03
• 目标包：@ant-design/x-sdk
• 参考讨论：RFC #1005 useAgUIChat 智能体对话

Summary

本 RFC 提议在 @ant-design/x-sdk 中增加模型、Agent Runtime 和传输协议无关的 AgentProvider，将 AG-UI、OpenAI Compatible、Anthropic 风格事件、私有 SSE、WebSocket、本地 Runtime 和录制 Fixture 等不同输入统一转换为 AgentEvent。

React 侧继续使用现有入口：

const { messages, agentState, onRequest, abort, isRequesting } = useXChat({ provider });

不新增 useAgUIChat 或 useAgent，也不向 useXChat 增加 agentUrl、mode、transport、store 等配置。Provider 是唯一接入入口，并在内部绑定 Transport；useXChat 负责 React 生命周期与状态订阅；Headless Agent Core 负责事件校验、归约与重放。

Model / Agent Runtime / Recorded Fixture
  -> AgentProvider（绑定 Transport）
  -> AgentEvent
  -> AgentStore
  -> useXChat
  -> messages + agentState

Motivation

Discussion #1005 提出了将 AG-UI 与 Ant Design X 对话能力集成的需求，主要解决两个问题：

1. Agent 生态协议碎片化。LangChain、CrewAI、模型 SDK 与私有 Runtime 使用不同的事件和传输格式。
2. 前端集成成本高。每种 Runtime 都需要单独处理流式消息、工具调用、状态同步和错误生命周期。

该方向成立，但直接增加 useAgUIChat({ agentUrl, transport, tools }) 会把 Hook 与单一协议、网络地址、工具执行策略绑定，并形成与 useXChat 平行的消息状态体系。随着第二种 Agent 协议进入，调用方仍需要切换 Hook 和 UI 状态逻辑。

本 RFC 将问题拆成三个稳定边界：

• Provider 适配外部 Runtime 语义。
• Agent Event Core 统一状态语义。
• useXChat 保持唯一 React 接入入口。

AG-UI 因此是可实现的 AgentProvider 之一，而不是 Agent Core 的唯一协议。

Goals

• 用可判别的 TypeScript 事件表达 Run、消息、推理、工具、审批、任务和 Artifact 生命周期。
• 支持 SSE、WebSocket、本地 Runtime、录制 Fixture 以及后续 Transport，而不修改事件模型。
• 让不同 Provider 归约到同一个可序列化、可重放的 AgentState。
• 让前端通过 useXChat({ provider }) 同时获得兼容消息和完整结构化状态。
• 保持现有 ChatProvider、XRequest、useXChat 调用和消息组件兼容。
• 通过显式协议版本和能力声明做运行时校验，不从模型名或 Provider 名推断能力。
• 为 AG-UI、OpenAI Compatible 和私有 Runtime 提供一致的扩展边界。

Non-goals

• 不在 Core 中定义模型请求参数或封装完整模型 SDK。
• 不在 Reducer 中执行工具、审批或任务副作用。
• 不在第一阶段实现持久化、断线恢复、网络重试或跨标签页同步。
• 不新增正式的 Tool、Approval、Task 或 Artifact React 组件。
• 不承诺不同 Runtime 的原始字段完全同构；无法标准化的数据保留在命名空间扩展或 meta 中。
• 不在两个结构不同的参考 Provider 验证前冻结稳定 API。

Terminology

名称	定义
ChatProvider	将普通流式响应转换为扁平聊天消息的存量 Provider
AgentProvider	将 Runtime Chunk 转换为标准 Agent Event 的适配器
Transport	将 Provider 请求执行为 AsyncIterable<Chunk> 的传输层
AgentEvent	带协议版本、Run 归属和顺序的标准事件
AgentStore	消费 Agent Event 并维护 AgentState 的 Headless Store
Run	一次 onRequest 对应的完整 Agent 执行
Entity	Run 下的消息、推理、工具、审批、任务或 Artifact

Detailed Design

1. 模块归属

packages/x-sdk/src/
├── agent/                              # 纯事件与状态核心
│   ├── protocol/                       # 事件类型、运行时校验、事件工厂
│   ├── reducer/                        # 状态归约、selectors、事件重放
│   ├── store/                          # Headless Store
│   └── index.ts                        # experimentalAgent 命名空间出口
├── chat-providers/                     # 所有 Provider 接入能力
│   ├── AgentProvider.ts                # Provider 与 Transport 契约
│   ├── runAgentProvider.ts             # Provider 执行边界
│   ├── testing/
│   │   └── validateAgentProviderEvents.ts
│   └── index.ts
└── x-chat/
    ├── agentRuntime.ts                 # useXChat 内部 Agent 桥接
    └── index.ts                        # 唯一公共 React Hook

依赖方向为：

agent <- chat-providers <- x-chat

约束如下：

• agent 不引用 Provider、Transport、React 或具体模型 SDK。
• chat-providers 依赖 Agent Protocol，负责 Runtime 适配与执行。
• x-chat 组合 Provider 和 Store，处理 React 生命周期。
• 不创建 agent/providers，因为 Provider 属于外部数据接入，不属于状态核心。

2. AgentProvider

interface AgentProvider<Input, Request, Chunk, Context = unknown> {
  readonly id: string;
  readonly protocol: {
    readonly name: 'agent-event';
    readonly version: '0.1';
  };
  readonly capabilities: AgentProviderCapabilities;
  readonly transport: AgentTransport<Request, Chunk>;

  createContext(options: AgentProviderContextOptions): Context;
  start(input: Input, context: Context): readonly AgentEvent[];
  prepareRequest(input: Input, context: Context): Request;
  transformChunk(chunk: Chunk, context: Context): readonly AgentEvent[];
  flush(context: Context): readonly AgentEvent[];
  transformError(error: unknown, context: Context): readonly AgentEvent[];
}

Provider 负责：

• 将 onRequest 输入转换为 Runtime 请求。
• 持有一种 Transport，并声明其类型。
• 维护单次 Run 内跨 Chunk 的解析上下文。
• 将一个 Chunk 转换为零到多个标准事件。
• 将 Runtime 错误和 Abort 转换为标准失败或取消事件。
• 在 Run 终止前关闭所有活动实体。

Provider 不负责：

• React 渲染或组件状态。
• 维护第二套消息 Reducer。
• 在核心层执行工具或自动批准操作。
• 根据模型名称决定事件语义。

protocol 是 useXChat 识别 AgentProvider 的显式判别字段。id 仅用于日志和元数据，不能参与能力判断。

3. Transport

type AgentTransportKind =
  | 'sse'
  | 'websocket'
  | 'async-iterable'
  | `${string}.${string}`;

interface AgentTransport<Request, Chunk> {
  readonly kind: AgentTransportKind;
  open(request: Request, signal: AbortSignal): AsyncIterable<Chunk>;
}

Transport 只负责执行请求并产生 Chunk，不理解消息、工具或 Run 语义。它保持独立接口以便组合和测试，但在 Provider 构造时绑定，不作为 useXChat 的第二个配置项。

自定义 Transport 使用命名空间标识，例如 company.websocket，避免与后续内置类型冲突。

4. Provider 能力声明

interface AgentProviderCapabilities {
  eventTypes: readonly AgentEventType[];
  transports: readonly AgentTransportKind[];
  extensions?: Readonly<Record<`${string}.${string}`, unknown>>;
}

Runner 在运行时验证：

• Provider 协议版本是否受支持。
• 当前 Transport 是否已声明。
• 每个输出事件是否结构合法。
• 事件是否属于当前 Session 和 Run。
• 事件类型是否已在能力列表中声明。

5. Agent Event Protocol

每个事件使用统一信封：

interface AgentEventEnvelope<Type, Payload> {
  protocolVersion: '0.1';
  type: Type;
  eventId: string;
  sessionId: string;
  runId: string;
  sequence: number;
  timestamp: number;
  parentId?: string;
  payload: Payload;
  meta?: Readonly<Record<string, unknown>>;
}

字段约束：

• eventId 在 Run 内唯一，并与 runId 组成幂等键。
• sequence 在同一 Run 内严格递增。
• sessionId 和 runId 必须与当前执行一致。
• payload 按 type 进行运行时校验。
• Provider、模型、Trace 和原始字段只进入 meta，不改变核心状态机。

标准事件族：

事件族	生命周期
Run	run.started -> run.completed/failed/cancelled
Message	message.started -> message.delta -> message.completed/failed/cancelled
Reasoning	reasoning.started -> reasoning.delta -> reasoning.completed/failed/cancelled
Tool	tool.requested -> tool.arguments_delta -> tool.running -> tool.completed/failed/cancelled
Approval	approval.requested -> approval.resolved
Task	task.created -> task.updated -> task.completed/failed/cancelled
Artifact	artifact.created -> artifact.updated -> artifact.completed/failed

每个 Run 必须恰好包含一个 run.started 和一个 Run 终态事件。实体增量和终态事件必须位于对应开始事件之后，Run 终止后不得继续更新实体。

消息内容允许纯文本或结构化 Part：

type AgentMessageContent = string | readonly AgentContentPart[];

type AgentContentPart =
  | { type: 'text'; text: string }
  | { type: 'image'; url?: string; data?: unknown; mediaType?: string }
  | { type: 'file'; url?: string; data?: unknown; mediaType?: string; name?: string }
  | { type: `${string}.${string}`; data: unknown };

核心层不得为了兼容纯文本 UI 而丢失结构化内容。

6. AG-UI 适配方式

AG-UI Provider 读取 AG-UI 事件，并按语义转换为标准 Agent Event。以下为非规范性示意：

AG-UI 语义	Agent Event
Run 开始、完成、错误	run.started/completed/failed
文本消息开始、增量、结束	message.started/delta/completed
工具调用开始、参数增量、结果	tool.requested/arguments_delta/completed
Step 或活动进度	视语义转换为 task.* 或命名空间扩展
State Snapshot / Delta	第一阶段保留在扩展数据，稳定映射另立 RFC
Custom Event	映射到命名空间扩展或 meta，不得伪造标准事件语义

AG-UI 的连接地址、请求头和 Transport 配置由 AgUIAgentProvider 的构造参数管理，不进入 useXChat：

const provider = new AgUIAgentProvider({
  transport: new AgUISSETransport({
    url: '/api/agent',
    headers: { Authorization: `Bearer ${token}` },
  }),
});

const chat = useXChat({ provider });

这使同一 UI 可以在 AG-UI、其他标准协议和私有 Runtime 之间切换，而不更换 Hook。

7. useXChat API

AgentProvider 使用独立的 TypeScript 重载，但运行时入口保持不变：

interface AgentXChatConfig<Input, Request, Chunk, Context, ParsedMessage> {
  provider: AgentProvider<Input, Request, Chunk, Context>;
  conversationKey?: string;
  defaultMessages?:
    | DefaultMessageInfo<AgentMessageState>[]
    | ((info: { conversationKey?: string }) =>
        | DefaultMessageInfo<AgentMessageState>[]
        | Promise<DefaultMessageInfo<AgentMessageState>[]>);
  parser?: (message: AgentMessageState) => ParsedMessage | ParsedMessage[];
}

使用方式：

const {
  messages,
  parsedMessages,
  agentState,
  onRequest,
  onReload,
  abort,
  isRequesting,
} = useXChat({
  provider,
  conversationKey: 'conversation-1',
});

onRequest({ prompt: '分析这份报告' });

返回值语义：

字段	AgentProvider 模式
messages	AgentMessageState 到 MessageInfo[] 的兼容投影
parsedMessages	经过 parser 转换的组件展示模型
agentState	完整的 Runs、推理、工具、审批、任务和 Artifact 状态
isRequesting	是否存在 running Run
abort	取消当前 Run，并由 Provider 产生取消事件
onReload	使用调用方传入的请求参数开始新 Run，不回写旧 Run

requestPlaceholder 和 requestFallback 仅属于存量 ChatProvider。AgentProvider 的 loading、失败和取消状态必须由事件表达。

setMessages、setMessage 和 removeMessage 只修改兼容消息层，不伪造 Agent Event，也不直接修改 agentState。

8. useXChat 内部流程

provider.protocol.name === 'agent-event'
  -> 按 conversationKey 创建或复用 AgentStore
  -> 生成 runId 和 AbortController
  -> runAgentProvider({ provider, input, run, onEvent: store.dispatch })
  -> AgentState 投影为 MessageInfo[]
  -> React 订阅 messages、agentState、isRequesting

其他 Provider
  -> 保持现有 AbstractChatProvider + XRequest 流程

AgentProvider 判别依赖 protocol.name，不使用 instanceof、类名、模型名或方法形状，避免跨包实例和自定义实现失效。

9. AgentState 与 Headless Store

AgentState 包含：

字段	内容
sessions	Session 元信息
runs	Run 输入、输出、状态、错误与 usage
messages	用户、助手、系统和工具消息
reasoning	推理内容、摘要与状态
toolCalls	工具名称、参数、结果与状态
approvals	审批风险、数据和决策
tasks	任务描述、进度和结果
artifacts	Artifact 内容、版本和媒体类型
issues	Reducer 记录的协议问题

Reducer 与 Store 遵循以下不变量：

• 重放相同的 runId + eventId 必须幂等。
• 新事件的 sequence 不得小于或等于已处理事件。
• 相同 Entity ID 在不同 Run 中互不影响，实体键为 runId + entityId。
• 状态保持普通可序列化数据，Reducer 不执行 I/O。
• record 模式记录协议问题并继续处理。
• strict 模式在第一个协议问题处抛出。
• strict batch 先在临时快照归约，失败时不提交状态且不通知订阅者。

10. 错误与取消

错误来源分为三类：

1. Transport 或 Runtime 错误：交给 provider.transformError，转换为实体失败事件和 run.failed。
2. Abort：使用同一个 AbortSignal 覆盖用户取消和组件卸载，转换为实体取消事件和 run.cancelled。
3. Event Consumer 或 Store 错误：原样传回调用方，不再次交给 Provider 转换，避免把前端消费错误伪装成 Runtime 错误。

Provider 输出 Run 终态前必须关闭所有仍活动的消息、推理、工具或任务实体。

11. Provider 契约测试

import { validateAgentProviderEvents } from '@ant-design/x-sdk';

const issues = validateAgentProviderEvents(provider.capabilities, events);
expect(issues).toEqual([]);

校验器覆盖：

• Event 信封和 payload 结构。
• 能力声明与实际事件类型。
• Event ID 唯一性和 sequence 顺序。
• Session 与 Run 归属。
• 恰好一个 run.started 和一个 Run 终态。
• Reducer 生命周期不变量。
• Run 终止后不存在活动子实体。

AG-UI、OpenAI Compatible、Anthropic 风格和私有 Runtime Provider 应运行同一套 Fixture 契约测试。语义等价的 Fixture 应归约为等价的 AgentState。

Example Usage

以下示例使用本地 AsyncIterable 模拟 Runtime，不依赖 API Key、Mock Server 或网络：

class LocalTransport implements AgentTransport<Request, Chunk> {
  readonly kind = 'demo.async-iterable' as const;

  async *open(request: Request, signal: AbortSignal) {
    for (const chunk of createFixtureChunks(request)) {
      if (signal.aborted) throw signal.reason;
      yield chunk;
    }
  }
}

class LocalAgentProvider implements AgentProvider<Input, Request, Chunk, Context> {
  readonly id = 'local-agent';
  readonly protocol = { name: 'agent-event', version: '0.1' } as const;
  readonly capabilities = {
    eventTypes: [
      'run.started',
      'run.completed',
      'run.failed',
      'run.cancelled',
      'message.started',
      'message.delta',
      'message.completed',
    ],
    transports: ['demo.async-iterable'],
  } as const;
  readonly transport = new LocalTransport();

  // createContext、start、prepareRequest、transformChunk、flush、transformError
  // 只负责将 Runtime 输入和 Chunk 转换为标准事件。
}

const provider = new LocalAgentProvider();

function Chat() {
  const { messages, agentState, onRequest, abort, isRequesting } = useXChat({ provider });

  return (
    <>
      <Bubble.List items={messages} />
      <Sender
        loading={isRequesting}
        onSubmit={(prompt) => onRequest({ prompt })}
        onCancel={abort}
      />
      <ToolPanel toolCalls={agentState.toolCalls} />
    </>
  );
}

完整可运行示例位于 packages/x/docs/x-sdk/demos/x-chat/agent-provider.tsx，覆盖消息、推理、工具、成功、失败和取消流程。

Backward Compatibility

现有调用不变：

const chat = useXChat({
  provider: existingChatProvider,
  requestPlaceholder,
  requestFallback,
});

兼容策略：

• AgentProvider 不继承 AbstractChatProvider，避免将多实体事件压缩为单条消息 Chunk。
• useXChat 通过 TypeScript 重载保留普通 ChatProvider 的类型推导。
• 普通 ChatProvider 模式下 agentState 为 undefined。
• AgentProvider 模式继续返回 messages，现有 Bubble 等消息组件无需理解完整事件协议。
• 第一阶段的 defaultMessages 仅初始化兼容消息层；完整 Agent 会话恢复另立持久化 RFC。
• 实验 API 通过 experimentalAgent 和实验性文档标签提示不稳定性。

Alternatives Considered

A. 新增 useAgUIChat

优点是与 #1005 草案和 AG-UI 概念直接对应。缺点是产生第二套 Hook、消息状态和错误处理 API，并将 Ant Design X 的 Agent 能力绑定到单一协议。

结论：不采用。AG-UI 通过 AgUIAgentProvider 接入现有 useXChat。

B. 新增通用 useAgent

优点是 Agent API 与普通聊天完全隔离。缺点是前端切换 Provider 时必须更换 Hook，消息组件和会话管理也需要重复装配。

结论：第一阶段不采用。只有当 Agent 交互出现无法由 useXChat 表达的稳定能力时再重新评估。

C. 在 useXChat 增加 mode、agent、transport 或 store

优点是底层对象显式。缺点是 Provider 与 Hook 同时承担能力判断，形成多种等价配置，并把 Runtime 细节泄漏到 UI。

结论：不采用。Hook 顶层仅保留 provider 作为执行入口。

D. 让 AgentProvider 继承 AbstractChatProvider

优点是复用现有类层级。缺点是 ChatProvider 的核心抽象是单消息转换，无法无损表达推理、工具、审批、任务和 Artifact 的独立生命周期。

结论：不采用。两类 Provider 共享 useXChat 入口，不共享错误的继承关系。

E. 将 Provider 放入 agent/ 目录

优点是名称集中。缺点是纯事件 Core 将开始依赖网络和 Runtime 接入概念，且与现有 chat-providers 形成重复归属。

结论：不采用。Provider、runner 和契约测试归入 chat-providers；协议、Reducer 和 Store 归入 agent。

Security and Privacy

• Core 不自动执行工具或审批，副作用必须由应用层显式实现。
• meta、错误详情、工具参数和 Artifact 可能包含敏感数据，日志与持久化实现不得默认上传这些字段。
• Provider 负责认证信息与请求头；认证配置不进入事件状态。
• 取消操作必须向 Transport 传递 AbortSignal，避免用户停止后 Runtime 仍持续产生前端副作用。
• 自定义结构化 Part 和扩展键必须使用命名空间，消费者默认忽略未知扩展。

Performance

• 文本增量在 Reducer 内按 Entity 更新，不要求重新解析 Provider 原始 Chunk。
• Store 的成功 batch 只通知一次订阅者。
• State 保持可序列化，便于后续引入快照、回放和 DevTools。
• 大型 Artifact 的外部存储和引用策略不在本阶段解决；实现不得假设所有 Artifact 都适合长期保留在内存。

Testing Strategy

1. Protocol：校验合法与畸形 payload、版本、结构化消息 Part。
2. Reducer：覆盖所有实体生命周期、幂等、sequence、跨 Run 隔离和终态后更新。
3. Store：覆盖 record/strict、原子 batch、订阅通知与 destroy。
4. Runner：覆盖 Transport、Abort、Provider 错误、协议错误和 Consumer 错误。
5. Provider Contract：至少两个结构不同的 Fixture 通过同一套校验。
6. React：覆盖普通 ChatProvider 无回归、AgentProvider 消息投影、会话切换、Reload 和 Unmount Abort。
7. Demo：覆盖正常、失败、取消、推理、工具、流式消息、Run 状态和协议问题计数。
8. 工程门禁：TypeScript、Biome、Remark、ESM/CJS/UMD 构建、API diff、Dekko 和 size-limit。

Rollout Plan

Phase 1: Experimental Core

• 以 experimentalAgent 暴露 Protocol、Reducer 和 Store。
• 从 chat-providers 顶层导出 AgentProvider、Transport、runner 和契约校验器。
• 在 useXChat 中增加 AgentProvider 重载与内部桥接。
• 发布离线 Runtime Demo 和双语文档。

Phase 2: Reference Providers

• 实现或验证 AG-UI Provider。
• 实现至少一个结构不同的 Provider，例如 OpenAI Compatible 或 Anthropic 风格事件。
• 使用等价 Fixture 比较最终 AgentState。

Phase 3: Stabilization

• 根据参考 Provider 调整协议缺口。
• 评估 State Snapshot/Delta、持久化和断线恢复 RFC。
• 完成包体积、公开导出和迁移评审后决定是否移出 experimental。

稳定 API 必须同时满足：

1. 两个结构不同的参考 Provider 通过契约测试。
2. 一个官方 Agent UI Demo 在不切换 Hook 的情况下切换 Provider。
3. 现有 ChatProvider 与 useXChat 测试无回归。
4. 文档、API diff、包体积和构建门禁通过。

Open Questions

1. AG-UI State Snapshot / Delta 应进入标准事件族，还是先通过命名空间扩展保留？
2. Tool 与 Approval 的应用层执行接口是否需要单独 RFC，还是继续由业务代码订阅状态处理？
3. 完整 AgentState 的持久化、恢复和协议升级如何设计？
4. 多个并行 Run 是否允许共享一个 conversationKey，abort() 应取消当前 Run 还是全部活动 Run？
5. Artifact 大内容应内联、引用外部 URL，还是由可插拔存储管理？
6. Provider 扩展事件在 DevTools、日志和 UI 中采用何种默认展示策略？

Decision Summary

• 前端唯一入口：useXChat({ provider })。
• Runtime 唯一适配点：AgentProvider。
• Transport 是独立接口，但由 Provider 持有。
• Agent Core 只包含 Protocol、Reducer 和 Store。
• Provider 能力归入现有 chat-providers。
• AG-UI 是参考 Provider，不是核心唯一协议。
• experimentalAgent 只暴露不稳定的事件与状态核心。
• 第一阶段不新增 Hook，不自动执行工具，不实现持久化和断线恢复。

References

• Ant Design X Discussion #1005: useAgUIChat 智能体对话
• AG-UI Protocol
• packages/x/docs/x-sdk/agent-provider.zh-CN.md
• packages/x/docs/x-sdk/use-x-chat.zh-CN.md
• docs/roadmap/phase-1-breakdown.zh-CN.md