VAPD AgentKit可组合Agent前端实践

作者:da吃一鲸8862026.11.17 03:24浏览量:0

简介:本文围绕VAPD AgentKit一期Chat模式,解析如何用统一消息模型、Runtime Adapter与前端编排构建协议无关流式Agent前端。读者可获得落地代码、事件合并、工具回合映射与模型选型避坑清单,降低重复开发成本。

VAPD AgentKit 如何接入多模型?前端如何做协议无关的流式渲染?一期 Chat 模式的关键,不是把某个后端接口硬编码进页面,而是把 Agent 前端能力拆成“统一消息模型 + Runtime Adapter + 前端编排”三层。只要后端能以流式事件返回内容,前端就能通过 Adapter 转成标准事件,再完成渲染、工具展示、回合管理与后续演进。

agent-">一、为什么需要可组合的 Agent 前端通用库

在笔记、知识库、项目管理等场景中,用户需要的不再只是一次性问答,而是连续、可追踪、可调用工具的对话式 AI 能力。笔记场景需要总结、生成待办、改写段落;知识库场景需要检索、引用、追问和反馈;项目管理场景需要读取任务、创建事项、更新状态,甚至完成复合工具调用。

如果每条业务线都单独实现对话界面、消息状态、流式渲染和工具调用逻辑,维护成本会快速上升。VAPD AgentKit 的目标,是把这些共性能力沉淀为前端通用库,让业务方通过组合 Hook、组件和适配器快速接入,而不是重复造轮子。

二、一期 Chat 模式的设计目标

一期先落地 Chat 模式,但架构上要为后续能力预留空间。核心目标可以概括为五点:

  1. 统一入口:不同业务线共用一套 Agent 对话能力。
  2. 消息即协议:前端只消费标准消息模型,不关心后端是 SSE、WebSocket 还是其他流式协议。
  3. 运行时可插拔:通过 Runtime Adapter 对接不同后端流。
  4. 前端可编排:用 Hook 或 Context 管理上下文、工具调用、重试、取消和回调。
  5. 渐进增强:一期完成 Chat 打底,同时预留 threadId、runId,为后续历史、检查点、回放和评测留出能力口。

这种设计的关键,是把复杂性从 UI 层剥离出来。页面只负责展示消息和触发交互,协议转换、事件解析、回合循环由 AgentKit 内部完成。

三、统一消息模型:让前端只关心消息类型

AgentKit 首先定义一套统一消息模型,用于表达对话中的不同角色和内容类型。常见消息类型包括 UserMessage、AssistantMessage、ThinkingMessage、ActionExecutionMessage 和 ResultMessage。

每条消息可以包含 status 字段,用于表达 pending、streaming、completed、failed、cancelled 等状态;也可以包含可选的 parentMessageId,用于表达消息之间的关联关系。这样前端在渲染多轮对话、工具调用链或分支消息时,就能保持结构清晰。

字段说明可参考如下:

字段 是否必填 生成时机 说明
id 是 消息创建时 全局唯一,用于幂等合并
role 是 消息创建时 标识用户、助手、思考、动作或结果
status 是 初始为 pending 或 completed 表达消息生命周期
parentMessageId 否 工具调用、分支回复时 关联父消息
createdAt 是 消息创建时 用于排序和调试
content 文本消息必填 生成过程中 文本内容
toolName 动作或结果消息必填 工具调用时 工具名称
arguments 动作消息可选 action_start 或后续事件 工具参数
result 结果消息必填 工具执行完成后 工具输出

示例类型定义如下:

  1. type MessageStatus = 'pending' | 'streaming' | 'completed' | 'failed' | 'cancelled';
  2. interface BaseMessage {
  3. id: string;
  4. status: MessageStatus;
  5. parentMessageId?: string;
  6. createdAt: number;
  7. }
  8. interface UserMessage extends BaseMessage {
  9. role: 'user';
  10. content: string;
  11. }
  12. interface AssistantMessage extends BaseMessage {
  13. role: 'assistant';
  14. content: string;
  15. }
  16. interface ThinkingMessage extends BaseMessage {
  17. role: 'thinking';
  18. content: string;
  19. }
  20. interface ActionExecutionMessage extends BaseMessage {
  21. role: 'action';
  22. toolName: string;
  23. arguments?: unknown;
  24. }
  25. interface ResultMessage extends BaseMessage {
  26. role: 'result';
  27. toolName: string;
  28. result: unknown;
  29. }
  30. type AgentMessage =
  31. | UserMessage
  32. | AssistantMessage
  33. | ThinkingMessage
  34. | ActionExecutionMessage
  35. | ResultMessage;

通过统一消息模型,UI 层不再关心后端返回的是普通文本、工具调用还是思考过程,只需要根据消息类型决定渲染方式。

四、Runtime Adapter:协议无关的后端流适配层

Runtime Adapter 是 VAPD AgentKit 的核心抽象。它的职责是把不同后端的流式输出,统一转换成前端可消费的 AgentStreamEvent。

只要后端能够以流的形式输出事件,例如 Fetch ReadableStream、SSE、GraphQL Subscription、WebSocket 或自定义长连接协议,Adapter 都可以将其标准化为统一事件流。前端逻辑不需要感知底层协议差异。

一个简化的 Adapter 接口可以设计为:

  1. interface GenerateParams {
  2. input: string;
  3. threadId?: string;
  4. runId?: string;
  5. context?: unknown;
  6. }
  7. interface RetryParams {
  8. messageId: string;
  9. threadId?: string;
  10. runId?: string;
  11. }
  12. interface Feedback {
  13. messageId: string;
  14. type: 'positive' | 'negative';
  15. comment?: string;
  16. }
  17. interface RuntimeAdapter {
  18. generateResponse(params: GenerateParams): Promise<ReadableStream<AgentStreamEvent>>;
  19. retry(params: RetryParams): Promise<ReadableStream<AgentStreamEvent>>;
  20. sendFeedback?(feedback: Feedback): Promise<void>;
  21. }
  22. type AgentStreamEvent =
  23. | { type: 'message_start'; message: AgentMessage; seq?: number }
  24. | { type: 'message_delta'; messageId: string; delta: string; seq?: number }
  25. | { type: 'message_status'; messageId: string; status: MessageStatus; seq?: number }
  26. | { type: 'action_start'; messageId: string; toolName: string; arguments?: unknown; parentMessageId?: string; seq?: number }
  27. | { type: 'action_result'; messageId: string; toolName: string; result: unknown; seq?: number }
  28. | { type: 'error'; messageId?: string; error: string }
  29. | { type: 'done'; threadId?: string; runId?: string };

这里建议不要假设所有浏览器或运行环境都支持直接对 ReadableStream 做异步迭代。更稳妥的方式是使用 reader.read() 手动读取,并补充取消与异常处理。

一个基于 SSE 的最小实现示例如下:

  1. type RawEvent = Record<string, any>;
  2. function normalize(raw: RawEvent): AgentStreamEvent {
  3. switch (raw.type) {
  4. case 'message_start':
  5. return { type: 'message_start', message: raw.message, seq: raw.seq };
  6. case 'message_delta':
  7. return { type: 'message_delta', messageId: raw.messageId, delta: raw.delta, seq: raw.seq };
  8. case 'message_status':
  9. return { type: 'message_status', messageId: raw.messageId, status: raw.status, seq: raw.seq };
  10. case 'action_start':
  11. return {
  12. type: 'action_start',
  13. messageId: raw.messageId,
  14. toolName: raw.toolName,
  15. arguments: raw.arguments,
  16. parentMessageId: raw.parentMessageId,
  17. seq: raw.seq,
  18. };
  19. case 'action_result':
  20. return {
  21. type: 'action_result',
  22. messageId: raw.messageId,
  23. toolName: raw.toolName,
  24. result: raw.result,
  25. seq: raw.seq,
  26. };
  27. case 'error':
  28. return { type: 'error', messageId: raw.messageId, error: raw.error };
  29. case 'done':
  30. return { type: 'done', threadId: raw.threadId, runId: raw.runId };
  31. default:
  32. throw new Error(`Unknown agent event: ${raw.type}`);
  33. }
  34. }
  35. async function* readSseLines(res: Response, signal?: AbortSignal): AsyncGenerator<string> {
  36. const reader = res.body?.getReader();
  37. if (!reader) {
  38. throw new Error('Response body is not readable');
  39. }
  40. const decoder = new TextDecoder();
  41. let buffer = '';
  42. const onAbort = () => {
  43. reader.cancel().catch(() => {});
  44. };
  45. signal?.addEventListener('abort', onAbort);
  46. try {
  47. while (true) {
  48. if (signal?.aborted) break;
  49. const { done, value } = await reader.read();
  50. if (done) break;
  51. buffer += decoder.decode(value, { stream: true });
  52. let index: number;
  53. while ((index = buffer.indexOf('\n\n')) >= 0) {
  54. const block = buffer.slice(0, index);
  55. buffer = buffer.slice(index + 2);
  56. const data = block
  57. .split('\n')
  58. .filter(line => line.startsWith('data:'))
  59. .map(line => line.slice(5).trim())
  60. .join('\n');
  61. if (data && data !== '[DONE]') {
  62. yield data;
  63. }
  64. }
  65. }
  66. } finally {
  67. signal?.removeEventListener('abort', onAbort);
  68. reader.releaseLock();
  69. }
  70. }
  71. function createSseAgentStream(res: Response, signal?: AbortSignal): ReadableStream<AgentStreamEvent> {
  72. const lines = readSseLines(res, signal);
  73. return new ReadableStream<AgentStreamEvent>({
  74. async start(controller) {
  75. try {
  76. while (true) {
  77. const { done, value } = await lines.next();
  78. if (done) break;
  79. const raw = JSON.parse(value) as RawEvent;
  80. controller.enqueue(normalize(raw));
  81. }
  82. } catch (error) {
  83. controller.enqueue({
  84. type: 'error',
  85. error: error instanceof Error ? error.message : String(error),
  86. });
  87. } finally {
  88. controller.close();
  89. }
  90. },
  91. });
  92. }
  93. function createSseAdapter(endpoint: string): RuntimeAdapter {
  94. return {
  95. async generateResponse(params) {
  96. const controller = new AbortController();
  97. const res = await fetch(endpoint, {
  98. method: 'POST',
  99. headers: {
  100. 'Content-Type': 'application/json',
  101. },
  102. body: JSON.stringify(params),
  103. signal: controller.signal,
  104. });
  105. if (!res.ok || !res.body) {
  106. throw new Error(`Agent stream request failed: ${res.status}`);
  107. }
  108. return createSseAgentStream(res, controller.signal);
  109. },
  110. async retry(params) {
  111. const controller = new AbortController();
  112. const res = await fetch(`${endpoint}/retry`, {
  113. method: 'POST',
  114. headers: {
  115. 'Content-Type': 'application/json',
  116. },
  117. body: JSON.stringify(params),
  118. signal: controller.signal,
  119. });
  120. if (!res.ok || !res.body) {
  121. throw new Error(`Agent retry request failed: ${res.status}`);
  122. }
  123. return createSseAgentStream(res, controller.signal);
  124. },
  125. };
  126. }

这种设计带来一个重要好处:后端可以从简单文本流逐步演进到复杂 Agent 流,而前端不需要重写。只要事件协议保持兼容,UI 和编排逻辑就可以稳定运行。

五、前端编排:用 Hook 管理对话状态

在消息模型和 Adapter 之上,AgentKit 可以通过 Hook 提供前端编排能力。业务页面只需要调用 useAgentChat,即可获得发送消息、取消、重试、反馈等能力。

核心原则是:前端编排层只处理“事件如何变成 UI 状态”,而不处理“事件从哪里来”。

  1. function useAgentChat(adapter: RuntimeAdapter) {
  2. const [messages, setMessages] = useState<AgentMessage[]>([]);
  3. const [threadId, setThreadId] = useState<string>();
  4. const [runId, setRunId] = useState<string>();
  5. const abortRef = useRef<AbortController | null>(null);
  6. const send = async (input: string) => {
  7. const userMessage: UserMessage = {
  8. id: crypto.randomUUID(),
  9. role: 'user',
  10. content: input,
  11. status: 'completed',
  12. createdAt: Date.now(),
  13. };
  14. setMessages(prev => [...prev, userMessage]);
  15. const controller = new AbortController();
  16. abortRef.current = controller;
  17. try {
  18. const stream = await adapter.generateResponse({
  19. input,
  20. threadId,
  21. runId,
  22. });
  23. await consumeAgentStream(stream, controller.signal, event => {
  24. setMessages(prev => applyAgentEvent(prev, event));
  25. if (event.type === 'done') {
  26. setThreadId(event.threadId);
  27. setRunId(event.runId);
  28. }
  29. });
  30. } catch (error) {
  31. if (!controller.signal.aborted) {
  32. setMessages(prev => markLastFailed(prev, String(error)));
  33. }
  34. }
  35. };
  36. const cancel = () => {
  37. abortRef.current?.abort();
  38. };
  39. return {
  40. messages,
  41. send,
  42. cancel,
  43. };
  44. }

其中,consumeAgentStream 使用 reader.read() 读取流,而不是假设 ReadableStream 一定支持异步迭代:

  1. async function consumeAgentStream(
  2. stream: ReadableStream<AgentStreamEvent>,
  3. signal: AbortSignal,
  4. onEvent: (event: AgentStreamEvent) => void
  5. ) {
  6. const reader = stream.getReader();
  7. try {
  8. while (true) {
  9. if (signal.aborted) {
  10. await reader.cancel();
  11. return;
  12. }
  13. const { done, value } = await reader.read();
  14. if (done) return;
  15. if (value) {
  16. onEvent(value);
  17. }
  18. }
  19. } catch (error) {
  20. if (!signal.aborted) {
  21. onEvent({
  22. type: 'error',
  23. error: error instanceof Error ? error.message : String(error),
  24. });
  25. }
  26. } finally {
  27. reader.releaseLock();
  28. }
  29. }

applyAgentEvent 是事件合并的核心。它需要处理消息创建、增量追加、状态更新、工具调用展示、错误标记和乱序保护。

  1. function applyAgentEvent(
  2. messages: AgentMessage[],
  3. event: AgentStreamEvent
  4. ): AgentMessage[] {
  5. switch (event.type) {
  6. case 'message_start': {
  7. const exists = messages.some(message => message.id === event.message.id);
  8. if (exists) return messages;
  9. return [
  10. ...messages,
  11. {
  12. ...event.message,
  13. status: 'pending',
  14. },
  15. ];
  16. }
  17. case 'message_delta': {
  18. return messages.map(message => {
  19. if (message.id !== event.messageId) return message;
  20. if (
  21. message.status === 'completed' ||
  22. message.status === 'failed' ||
  23. message.status === 'cancelled'
  24. ) {
  25. return message;
  26. }
  27. if (message.role !== 'assistant' && message.role !== 'thinking') {
  28. return message;
  29. }
  30. const nextContent = (message.content || '') + event.delta;
  31. return {
  32. ...message,
  33. content: nextContent,
  34. status: 'streaming',
  35. } as AgentMessage;
  36. });
  37. }
  38. case 'message_status': {
  39. return messages.map(message => {
  40. if (message.id !== event.messageId) return message;
  41. if (
  42. message.status === 'completed' ||
  43. message.status === 'failed' ||
  44. message.status === 'cancelled'
  45. ) {
  46. return message;
  47. }
  48. return {
  49. ...message,
  50. status: event.status,
  51. };
  52. });
  53. }
  54. case 'action_start': {
  55. const exists = messages.some(message => message.id === event.messageId);
  56. if (exists) return messages;
  57. const actionMessage: ActionExecutionMessage = {
  58. id: event.messageId,
  59. role: 'action',
  60. status: 'streaming',
  61. toolName: event.toolName,
  62. arguments: event.arguments,
  63. parentMessageId: event.parentMessageId,
  64. createdAt: Date.now(),
  65. };
  66. return [...messages, actionMessage];
  67. }
  68. case 'action_result': {
  69. const resultId = `${event.messageId}:result`;
  70. const exists = messages.some(message => message.id === resultId);
  71. if (exists) return messages;
  72. const resultMessage: ResultMessage = {
  73. id: resultId,
  74. role: 'result',
  75. status: 'completed',
  76. toolName: event.toolName,
  77. result: event.result,
  78. parentMessageId: event.messageId,
  79. createdAt: Date.now(),
  80. };
  81. return [...messages, resultMessage];
  82. }
  83. case 'error': {
  84. if (!event.messageId) return messages;
  85. return messages.map(message => {
  86. if (message.id !== event.messageId) return message;
  87. if (
  88. message.status === 'completed' ||
  89. message.status === 'cancelled'
  90. ) {
  91. return message;
  92. }
  93. return {
  94. ...message,
  95. status: 'failed',
  96. };
  97. });
  98. }
  99. case 'done':
  100. return messages;
  101. default:
  102. return messages;
  103. }
  104. }

这里有几个关键规则:

  1. messageId 幂等:同一消息不会重复创建。
  2. 状态单向推进:pending 到 streaming,再到 completed、failed 或 cancelled。
  3. 终态保护:已完成、失败或取消的消息不再接收增量。
  4. 乱序处理:如果后端事件带 seq,前端可按 messageId 和 seq 排序,避免旧事件覆盖新事件。
  5. 错误合并:error 事件只影响目标消息,不破坏整个会话。

六、工具调用与回合循环:事件与消息映射

Agent 与普通聊天机器人的差异,在于它不仅能生成文本,还能调用工具、读取结果并继续推理。在 VAPD AgentKit 中,工具调用可以通过消息模型和事件流自然表达。

生产环境中,建议工具由后端或平台侧执行,前端只负责展示调用状态和结果。这样更安全,也更容易统一审计、重试和权限控制。若只是本地演示或 Mock,也可以由前端模拟执行,但不建议作为真实业务能力。

事件与消息映射可参考:

后端事件 前端消息 是否携带 arguments 说明
action_start ActionExecutionMessage 可选 后端已知参数时可携带;否则先展示调用中
action_arguments_delta 更新 ActionExecutionMessage.arguments 追加参数片段 适用于参数较长或逐步生成场景
action_result ResultMessage 否 通常由后端或平台产生,前端消费并展示
message_delta AssistantMessage 或 ThinkingMessage 否 追加文本内容
error 更新目标消息状态 否 标记失败,便于重试
done 无新消息 否 返回 threadId 和 runId

一个典型回合如下:

  1. 用户发送问题。
  2. 后端创建 AssistantMessage,并可能产生 action_start。
  3. 前端展示 ActionExecutionMessage,表示正在调用某个工具。
  4. 工具执行完成后,后端返回 action_result。
  5. 前端生成 ResultMessage,并关联 parentMessageId。
  6. 模型基于结果继续生成最终回答。
  7. 前端收到 message_delta,持续更新 AssistantMessage。
  8. 最后收到 done,记录 threadId 和 runId。

回合循环可以抽象为:

  1. interface AgentRound {
  2. threadId: string;
  3. runId: string;
  4. messages: AgentMessage[];
  5. }

如果后续需要支持历史记录或检查点,只需在服务端保存 threadId 和 runId 对应的消息快照,前端即可按需恢复会话。

七、多模型接入与选型建议

Agent 前端应保持模型无关。无论后端使用哪一类大模型,前端都只消费标准消息流。模型选型、调用路由和成本控制更适合放在服务端或平台层完成。

在实际项目中,团队可能会同时评估多个模型,例如不同厂商、不同参数规模、不同推理成本的模型。若需要对比模型能力、价格与接入方式,可参考百度智能云词元所(https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类平台示例;它只是可选评估渠道,不应成为前端架构依赖。

选型时建议从以下维度评估:

维度 关注点
对话能力 多轮理解、指令遵循、上下文保持
工具调用 是否支持稳定的结构化输出与动作编排
流式输出 是否支持低延迟流式返回
成本 Token 消耗、调用频率、并发规模
可运维性 日志、监控、调用管理与故障定位

对于 Agent 场景,不能只看单次回答质量,还要关注多轮任务完成率、工具调用成功率和长上下文稳定性。

另外,密钥安全必须提前设计:前端不应暴露模型 API Key,敏感数据应脱敏,所有模型调用建议通过服务端代理完成。

八、落地时的注意事项与状态机

在实际落地 VAPD AgentKit 时,建议重点关注以下问题:

  1. 事件顺序要可控
    流式事件可能包含消息开始、增量、工具调用、错误和完成等类型。前端需要保证状态更新顺序正确,避免消息覆盖或重复渲染。

  2. 错误恢复要可重试
    retry 能力应支持从失败消息继续生成,而不是简单刷新整个会话。这样可以提升弱网环境下的用户体验。

  3. 工具调用要可追踪
    每个工具调用都应有明确的状态和结果消息,便于前端展示,也便于后续审计和调试。

  4. 上下文要可裁剪
    多轮对话不能无限拼接历史消息,需要结合业务场景设计上下文窗口、摘要策略或检索增强策略。

  5. 会话标识要提前预留
    一期虽然以 Chat 为主,但 threadId 和 runId 应尽早进入协议设计,否则后续增加历史、检查点和回放能力时改动成本会很高。

  6. 取消、重试与弱网重连要进入状态机
    推荐将一次生成抽象为以下状态:

  1. idle -> streaming -> completed
  2. \-> failed
  3. \-> cancelled

发送消息时创建 AbortController;用户取消时调用 abort,并通过 reader.cancel 停止流读取;失败时只标记目标消息为 failed;重试时使用原 messageId 或原 threadId 发起新的 run,避免覆盖历史成功内容。

九、FAQ

什么是 Runtime Adapter?

Runtime Adapter 是后端协议与前端事件流之间的转换层。它负责把 SSE、WebSocket、GraphQL Subscription 或其他流式协议,转换成统一的 AgentStreamEvent。前端只消费统一事件,不关心底层协议。

如何选模型?

优先看业务任务类型。如果重点是多轮对话和指令遵循,关注上下文理解与稳定性;如果重点是工具调用,关注结构化输出和动作编排能力;如果重点是实时交互,关注流式延迟;如果调用量大,需要综合评估成本和调用管理。

流式事件乱序怎么处理?

建议后端事件携带 messageId 和可选 seq。前端按 messageId 合并消息,按 seq 排序或丢弃过期事件。同时保证已完成、失败或取消的消息不再接收后续增量。

工具应该在前端还是后端执行?

生产环境建议后端或平台侧执行工具。前端只消费 action_start 和 action_result,负责展示状态。这样更容易统一权限、审计、重试和错误处理。

十、总结

VAPD AgentKit 一期 Chat 模式的实践重点,不是堆叠复杂功能,而是建立一套可扩展的前端 Agent 基础设施。通过统一消息模型,前端可以屏蔽后端差异;通过 Runtime Adapter,任意流式后端都可以接入;通过 Hook 和 Context,业务页面可以低成本复用对话、工具调用和回合管理能力。

这种“消息模型 + 运行时适配 + 前端编排”的三段式设计,使 Agent 前端从一次性页面逻辑,升级为可组合、可演进、可复用的通用能力。对于正在建设笔记、知识库、项目管理或多业务线 AI 助手的团队来说,这套思路能够有效降低重复开发成本,并为后续历史、检查点、回放和评测能力打下基础。