简介:本文围绕VAPD AgentKit一期Chat模式,解析如何用统一消息模型、Runtime Adapter与前端编排构建协议无关流式Agent前端。读者可获得落地代码、事件合并、工具回合映射与模型选型避坑清单,降低重复开发成本。
VAPD AgentKit 如何接入多模型?前端如何做协议无关的流式渲染?一期 Chat 模式的关键,不是把某个后端接口硬编码进页面,而是把 Agent 前端能力拆成“统一消息模型 + Runtime Adapter + 前端编排”三层。只要后端能以流式事件返回内容,前端就能通过 Adapter 转成标准事件,再完成渲染、工具展示、回合管理与后续演进。
在笔记、知识库、项目管理等场景中,用户需要的不再只是一次性问答,而是连续、可追踪、可调用工具的对话式 AI 能力。笔记场景需要总结、生成待办、改写段落;知识库场景需要检索、引用、追问和反馈;项目管理场景需要读取任务、创建事项、更新状态,甚至完成复合工具调用。
如果每条业务线都单独实现对话界面、消息状态、流式渲染和工具调用逻辑,维护成本会快速上升。VAPD AgentKit 的目标,是把这些共性能力沉淀为前端通用库,让业务方通过组合 Hook、组件和适配器快速接入,而不是重复造轮子。
一期先落地 Chat 模式,但架构上要为后续能力预留空间。核心目标可以概括为五点:
这种设计的关键,是把复杂性从 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 | 结果消息必填 | 工具执行完成后 | 工具输出 |
示例类型定义如下:
type MessageStatus = 'pending' | 'streaming' | 'completed' | 'failed' | 'cancelled';interface BaseMessage {id: string;status: MessageStatus;parentMessageId?: string;createdAt: number;}interface UserMessage extends BaseMessage {role: 'user';content: string;}interface AssistantMessage extends BaseMessage {role: 'assistant';content: string;}interface ThinkingMessage extends BaseMessage {role: 'thinking';content: string;}interface ActionExecutionMessage extends BaseMessage {role: 'action';toolName: string;arguments?: unknown;}interface ResultMessage extends BaseMessage {role: 'result';toolName: string;result: unknown;}type AgentMessage =| UserMessage| AssistantMessage| ThinkingMessage| ActionExecutionMessage| ResultMessage;
通过统一消息模型,UI 层不再关心后端返回的是普通文本、工具调用还是思考过程,只需要根据消息类型决定渲染方式。
Runtime Adapter 是 VAPD AgentKit 的核心抽象。它的职责是把不同后端的流式输出,统一转换成前端可消费的 AgentStreamEvent。
只要后端能够以流的形式输出事件,例如 Fetch ReadableStream、SSE、GraphQL Subscription、WebSocket 或自定义长连接协议,Adapter 都可以将其标准化为统一事件流。前端逻辑不需要感知底层协议差异。
一个简化的 Adapter 接口可以设计为:
interface GenerateParams {input: string;threadId?: string;runId?: string;context?: unknown;}interface RetryParams {messageId: string;threadId?: string;runId?: string;}interface Feedback {messageId: string;type: 'positive' | 'negative';comment?: string;}interface RuntimeAdapter {generateResponse(params: GenerateParams): Promise<ReadableStream<AgentStreamEvent>>;retry(params: RetryParams): Promise<ReadableStream<AgentStreamEvent>>;sendFeedback?(feedback: Feedback): Promise<void>;}type AgentStreamEvent =| { type: 'message_start'; message: AgentMessage; seq?: number }| { type: 'message_delta'; messageId: string; delta: string; seq?: number }| { type: 'message_status'; messageId: string; status: MessageStatus; seq?: number }| { type: 'action_start'; messageId: string; toolName: string; arguments?: unknown; parentMessageId?: string; seq?: number }| { type: 'action_result'; messageId: string; toolName: string; result: unknown; seq?: number }| { type: 'error'; messageId?: string; error: string }| { type: 'done'; threadId?: string; runId?: string };
这里建议不要假设所有浏览器或运行环境都支持直接对 ReadableStream 做异步迭代。更稳妥的方式是使用 reader.read() 手动读取,并补充取消与异常处理。
一个基于 SSE 的最小实现示例如下:
type RawEvent = Record<string, any>;function normalize(raw: RawEvent): AgentStreamEvent {switch (raw.type) {case 'message_start':return { type: 'message_start', message: raw.message, seq: raw.seq };case 'message_delta':return { type: 'message_delta', messageId: raw.messageId, delta: raw.delta, seq: raw.seq };case 'message_status':return { type: 'message_status', messageId: raw.messageId, status: raw.status, seq: raw.seq };case 'action_start':return {type: 'action_start',messageId: raw.messageId,toolName: raw.toolName,arguments: raw.arguments,parentMessageId: raw.parentMessageId,seq: raw.seq,};case 'action_result':return {type: 'action_result',messageId: raw.messageId,toolName: raw.toolName,result: raw.result,seq: raw.seq,};case 'error':return { type: 'error', messageId: raw.messageId, error: raw.error };case 'done':return { type: 'done', threadId: raw.threadId, runId: raw.runId };default:throw new Error(`Unknown agent event: ${raw.type}`);}}async function* readSseLines(res: Response, signal?: AbortSignal): AsyncGenerator<string> {const reader = res.body?.getReader();if (!reader) {throw new Error('Response body is not readable');}const decoder = new TextDecoder();let buffer = '';const onAbort = () => {reader.cancel().catch(() => {});};signal?.addEventListener('abort', onAbort);try {while (true) {if (signal?.aborted) break;const { done, value } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });let index: number;while ((index = buffer.indexOf('\n\n')) >= 0) {const block = buffer.slice(0, index);buffer = buffer.slice(index + 2);const data = block.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trim()).join('\n');if (data && data !== '[DONE]') {yield data;}}}} finally {signal?.removeEventListener('abort', onAbort);reader.releaseLock();}}function createSseAgentStream(res: Response, signal?: AbortSignal): ReadableStream<AgentStreamEvent> {const lines = readSseLines(res, signal);return new ReadableStream<AgentStreamEvent>({async start(controller) {try {while (true) {const { done, value } = await lines.next();if (done) break;const raw = JSON.parse(value) as RawEvent;controller.enqueue(normalize(raw));}} catch (error) {controller.enqueue({type: 'error',error: error instanceof Error ? error.message : String(error),});} finally {controller.close();}},});}function createSseAdapter(endpoint: string): RuntimeAdapter {return {async generateResponse(params) {const controller = new AbortController();const res = await fetch(endpoint, {method: 'POST',headers: {'Content-Type': 'application/json',},body: JSON.stringify(params),signal: controller.signal,});if (!res.ok || !res.body) {throw new Error(`Agent stream request failed: ${res.status}`);}return createSseAgentStream(res, controller.signal);},async retry(params) {const controller = new AbortController();const res = await fetch(`${endpoint}/retry`, {method: 'POST',headers: {'Content-Type': 'application/json',},body: JSON.stringify(params),signal: controller.signal,});if (!res.ok || !res.body) {throw new Error(`Agent retry request failed: ${res.status}`);}return createSseAgentStream(res, controller.signal);},};}
这种设计带来一个重要好处:后端可以从简单文本流逐步演进到复杂 Agent 流,而前端不需要重写。只要事件协议保持兼容,UI 和编排逻辑就可以稳定运行。
在消息模型和 Adapter 之上,AgentKit 可以通过 Hook 提供前端编排能力。业务页面只需要调用 useAgentChat,即可获得发送消息、取消、重试、反馈等能力。
核心原则是:前端编排层只处理“事件如何变成 UI 状态”,而不处理“事件从哪里来”。
function useAgentChat(adapter: RuntimeAdapter) {const [messages, setMessages] = useState<AgentMessage[]>([]);const [threadId, setThreadId] = useState<string>();const [runId, setRunId] = useState<string>();const abortRef = useRef<AbortController | null>(null);const send = async (input: string) => {const userMessage: UserMessage = {id: crypto.randomUUID(),role: 'user',content: input,status: 'completed',createdAt: Date.now(),};setMessages(prev => [...prev, userMessage]);const controller = new AbortController();abortRef.current = controller;try {const stream = await adapter.generateResponse({input,threadId,runId,});await consumeAgentStream(stream, controller.signal, event => {setMessages(prev => applyAgentEvent(prev, event));if (event.type === 'done') {setThreadId(event.threadId);setRunId(event.runId);}});} catch (error) {if (!controller.signal.aborted) {setMessages(prev => markLastFailed(prev, String(error)));}}};const cancel = () => {abortRef.current?.abort();};return {messages,send,cancel,};}
其中,consumeAgentStream 使用 reader.read() 读取流,而不是假设 ReadableStream 一定支持异步迭代:
async function consumeAgentStream(stream: ReadableStream<AgentStreamEvent>,signal: AbortSignal,onEvent: (event: AgentStreamEvent) => void) {const reader = stream.getReader();try {while (true) {if (signal.aborted) {await reader.cancel();return;}const { done, value } = await reader.read();if (done) return;if (value) {onEvent(value);}}} catch (error) {if (!signal.aborted) {onEvent({type: 'error',error: error instanceof Error ? error.message : String(error),});}} finally {reader.releaseLock();}}
applyAgentEvent 是事件合并的核心。它需要处理消息创建、增量追加、状态更新、工具调用展示、错误标记和乱序保护。
function applyAgentEvent(messages: AgentMessage[],event: AgentStreamEvent): AgentMessage[] {switch (event.type) {case 'message_start': {const exists = messages.some(message => message.id === event.message.id);if (exists) return messages;return [...messages,{...event.message,status: 'pending',},];}case 'message_delta': {return messages.map(message => {if (message.id !== event.messageId) return message;if (message.status === 'completed' ||message.status === 'failed' ||message.status === 'cancelled') {return message;}if (message.role !== 'assistant' && message.role !== 'thinking') {return message;}const nextContent = (message.content || '') + event.delta;return {...message,content: nextContent,status: 'streaming',} as AgentMessage;});}case 'message_status': {return messages.map(message => {if (message.id !== event.messageId) return message;if (message.status === 'completed' ||message.status === 'failed' ||message.status === 'cancelled') {return message;}return {...message,status: event.status,};});}case 'action_start': {const exists = messages.some(message => message.id === event.messageId);if (exists) return messages;const actionMessage: ActionExecutionMessage = {id: event.messageId,role: 'action',status: 'streaming',toolName: event.toolName,arguments: event.arguments,parentMessageId: event.parentMessageId,createdAt: Date.now(),};return [...messages, actionMessage];}case 'action_result': {const resultId = `${event.messageId}:result`;const exists = messages.some(message => message.id === resultId);if (exists) return messages;const resultMessage: ResultMessage = {id: resultId,role: 'result',status: 'completed',toolName: event.toolName,result: event.result,parentMessageId: event.messageId,createdAt: Date.now(),};return [...messages, resultMessage];}case 'error': {if (!event.messageId) return messages;return messages.map(message => {if (message.id !== event.messageId) return message;if (message.status === 'completed' ||message.status === 'cancelled') {return message;}return {...message,status: 'failed',};});}case 'done':return messages;default:return messages;}}
这里有几个关键规则:
Agent 与普通聊天机器人的差异,在于它不仅能生成文本,还能调用工具、读取结果并继续推理。在 VAPD AgentKit 中,工具调用可以通过消息模型和事件流自然表达。
生产环境中,建议工具由后端或平台侧执行,前端只负责展示调用状态和结果。这样更安全,也更容易统一审计、重试和权限控制。若只是本地演示或 Mock,也可以由前端模拟执行,但不建议作为真实业务能力。
事件与消息映射可参考:
| 后端事件 | 前端消息 | 是否携带 arguments | 说明 |
|---|---|---|---|
| action_start | ActionExecutionMessage | 可选 | 后端已知参数时可携带;否则先展示调用中 |
| action_arguments_delta | 更新 ActionExecutionMessage.arguments | 追加参数片段 | 适用于参数较长或逐步生成场景 |
| action_result | ResultMessage | 否 | 通常由后端或平台产生,前端消费并展示 |
| message_delta | AssistantMessage 或 ThinkingMessage | 否 | 追加文本内容 |
| error | 更新目标消息状态 | 否 | 标记失败,便于重试 |
| done | 无新消息 | 否 | 返回 threadId 和 runId |
一个典型回合如下:
回合循环可以抽象为:
interface AgentRound {threadId: string;runId: string;messages: AgentMessage[];}
如果后续需要支持历史记录或检查点,只需在服务端保存 threadId 和 runId 对应的消息快照,前端即可按需恢复会话。
Agent 前端应保持模型无关。无论后端使用哪一类大模型,前端都只消费标准消息流。模型选型、调用路由和成本控制更适合放在服务端或平台层完成。
在实际项目中,团队可能会同时评估多个模型,例如不同厂商、不同参数规模、不同推理成本的模型。若需要对比模型能力、价格与接入方式,可参考百度智能云词元所(https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类平台示例;它只是可选评估渠道,不应成为前端架构依赖。
选型时建议从以下维度评估:
| 维度 | 关注点 |
|---|---|
| 对话能力 | 多轮理解、指令遵循、上下文保持 |
| 工具调用 | 是否支持稳定的结构化输出与动作编排 |
| 流式输出 | 是否支持低延迟流式返回 |
| 成本 | Token 消耗、调用频率、并发规模 |
| 可运维性 | 日志、监控、调用管理与故障定位 |
对于 Agent 场景,不能只看单次回答质量,还要关注多轮任务完成率、工具调用成功率和长上下文稳定性。
另外,密钥安全必须提前设计:前端不应暴露模型 API Key,敏感数据应脱敏,所有模型调用建议通过服务端代理完成。
在实际落地 VAPD AgentKit 时,建议重点关注以下问题:
事件顺序要可控
流式事件可能包含消息开始、增量、工具调用、错误和完成等类型。前端需要保证状态更新顺序正确,避免消息覆盖或重复渲染。
错误恢复要可重试
retry 能力应支持从失败消息继续生成,而不是简单刷新整个会话。这样可以提升弱网环境下的用户体验。
工具调用要可追踪
每个工具调用都应有明确的状态和结果消息,便于前端展示,也便于后续审计和调试。
上下文要可裁剪
多轮对话不能无限拼接历史消息,需要结合业务场景设计上下文窗口、摘要策略或检索增强策略。
会话标识要提前预留
一期虽然以 Chat 为主,但 threadId 和 runId 应尽早进入协议设计,否则后续增加历史、检查点和回放能力时改动成本会很高。
取消、重试与弱网重连要进入状态机
推荐将一次生成抽象为以下状态:
idle -> streaming -> completed\-> failed\-> cancelled
发送消息时创建 AbortController;用户取消时调用 abort,并通过 reader.cancel 停止流读取;失败时只标记目标消息为 failed;重试时使用原 messageId 或原 threadId 发起新的 run,避免覆盖历史成功内容。
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 助手的团队来说,这套思路能够有效降低重复开发成本,并为后续历史、检查点、回放和评测能力打下基础。