我们围绕三大业务场景统一了一套可组合的 AI Agent 能力。这篇文章聚焦一期「Chat 模式」落地：强调 Runtime Adapter 的“协议无关、面向任意后端流”特性——只要后端能够以流式输出事件，前端即可通过统一的 Adapter 转为标准消息模型进行渲染与编排。我们以“统一消息模型 + Runtime Adapter + 前端编排”的方式。将工具调用、Agent 回合循环、事件流与 UI 交互组合在一起，并为后续历史与检查点能力预留 threadId/runId。

1 分钟看图找到关键观点 👇

一、背景与目标

• 业务诉求：笔记、知识库、项目管理三类场景都需要“对话式”AI 能力，并逐步演进到多轮、工具调用、上下文提高与可追溯。
• 使用者痛点：业务线经常需要重新造轮子；缺乏统一入口导致前后端耦合度高；功能迭代慢，
• 统一入口：不希望每条业务线重复造轮子；期待用同一套可组合 Hook 即插即用。
• 一期范围：先完成 Chat 模式打底，但保留可 的“多消息一回合”“工具调用”“历史/检查点”能力。

在产品体验上，我们遵循主流 Agent 设计范式。并结合过往的实现风格，将复杂由“消息模型 + 运行时适配 + 前端编排”三段式来解耦。

二、设计原则

• 消息即协议：把后端回传的事件统一解码为前端消息模型。UI 只消费消息，不关心来源细节。
• User Pain Point: 开发者常因协议差异导致大量条件分支，代码膨胀。
• 运行时可插拔：只要后端能以“流”的形式输出。Adapter 都会转为相同的 AgentStreamEvent，前端逻辑零差异。
• User Pain Point: 流式协议切换成本高，难以快速集成新后端。
• 前端可编排：用 Hook/Context 管理上下文、工具、重试/变体、回调，形成稳定的胶水层。
• User Pain Point: 工具调用和重试逻辑散落各处，难以维护和复用。
• 渐进提高：I期只做 Chat。但保留 threadId/runId，为“历史/检查点/回放/评测”留出Agent能力口。其实，

三、架构总览

① 统一消息模型

• Covers UserMessage。AssistantMessage,Thinking-Message,ActionExecution-Message,ResultMessage 等类型，含 status 与可选 parentMessageId，可 图片及状态消息。

② Runtime Adapter 接口

• `generateResponse / retry` 返回 ReadableStream，`sendFeedback` 统一正/负反馈。
• 支持多种后端 “流”：内置 VAPD 示例，也可 GraphQL/WebSocket/自定义 Fetch 流；无论来源如何，都标准化为 AgentStreamEvent。不过，

③ 前端编排

• `AgentKit` 作为 Provider 暴露上下文。 统一注入 runtime、actions、自定义树结构还有加载状态等。
• `useAgentChat` 组合 `useChat`，提供 `appendMessage`,`reloadMessages`,`stopGeneration`,`threadId`,`runId` 等能力.
• `useChat` 串接 Runtime 流事件，处理工具调用与 Agent 循环。并维护 AbortController.

④ Vue UI 组件

• `Chat` 容器封装输入区 / 消息区 / 操作 / 建议项，并通过 `` 与 Core 同步.

四、事件流与消息模型：把一切都还原成消息

后端返回的是 “事件”，前端消费的是 “消息”。我们把差异收敛在 Adapter 层：

• 增量累加将分片 token 聚合为 Thinking‑Message / AssistantMessage.

export type AgentStreamEvent = {
threadId?: string | null
runId?这方面，string | null
messages?: Message
guardrailsFailureReason?怎么说呢，: string
}

工具事件toolcall → ActionExecution‑Message;toolresult → ResultMessage.

统一标识维护 threadId与 runId。为历史/检查点铺路.

精确收束依据服务端 “回合结束” 信号或本地规则准确结束本轮流.

五、“Agent 回合循环” 与 工具调用

Chat 模式不仅是生成单条回复，而是一轮内可能包含多条信息：思考→工具调用→结果返回→继续生成…，我们将 “回合循环” 集中处理于 useChat 中：

// useChat 内部实现示例
function useChat {
const stream = runtime.generateResponse
stream.on => {
// 按顺序追加 message
if {
// 调用前端 tool handler
const result = await handler
// 把结果回注为 ResultMessage
appendResult
}
if {
// 最终返回 AssistantMessage 并准备下一轮
}
})
}

串接流式事件并按顺序追加。

捕获 ActionExecutionMessage 并触发前端工具 handler，再将结果包成 ResultMessage 回注。

当一轮结束时返回最终 AssistantMessage 并准备下一轮；

在重载/变体场景中保留既有候选并追加新候选，实现多变体集合。

与传输方式无关：只要后端发出等价事件，Adapter 均映射完成。

*User Pain Point:* 工具执行结果往往需要手动包装或触发外部 API，导致开发成本高且易错。

6. 工具调用的前端形态：useAgentAction

为了让“工具”在页面内即可声明与注册，我们提供了 useAgentAction：

import { useAgentContext } from '@vapd-agentkit/vue-core'

const ctx = useAgentContext ctx.setAction('searchDocs'。{ name这方面，'searchDocs',description: '搜索知识库',parameters:,handler: async => { const result = await fetch}`).n) return { hits: result.items } } })

描述：name / description / parameters;

处理：handler 返回值打包成 ResultMessage 回注对话;

可选渲染：render 可将工具调用或结果以内嵌卡片形式展示;

幂等性：同一执行 ID 只触发一次 handler;

Adapter 把后台 tool event 映射为 front‑end message;UI 无需关注协议或传输方式.

User Pain Point:- 开发者经常需手动同步 Tool 定义和 UI 渲染逻辑，使得跨团队协作困难。

七 UI 交互 & 建议

'Chat' 为容器暴露了信息渲染插槽和输入区控制，以默认行为如下：

 * 渲染 Thinking 、Assistant 、User 、Error 等信息类型;*
支持复制 、停止 、重新生成 、建议点击;说起来，*
`useCopilotChatLogic` 将 Core 能力 与 UI 事件绑定。并提供节流后的建议刷新入口。

---

八 最小上手 —— 在任意页面接入 Chat

。

---