将工具调用、Agent 回合循环、事件流与 UI 交互组合在一起并为后续历史与检查点能力预留 threadId/runId。1分钟看图掌握核心观点一、背景与目标业务诉求笔记、知识库、项目管理三类场景都需要“对话式”AI 能力并逐步演进到多轮、工具调用、上下文增强与可追溯。统一入口不希望每条业务线重复造轮子期待用同一套可组合 Hook 即插即用。一期范围先完成 Chat 模式打底但保留可扩展的“多消息一回合”“工具调用”“历史/检查点”能力。在产品体验上我们遵循主流 Agent 设计范式消息驱动、工具调用、上下文注入、可回放、可评测并结合过往的实现风格将复杂性交由“消息模型 运行时适配 前端编排”三段式来解耦。二、设计原则消息即协议把后端回传的事件统一解码为前端消息模型UI 只消费消息不关心来源细节。运行时可插拔只要后端能以“流”的形式输出SSE、GraphQL、WebSocket、Fetch ReadableStream 等均可Adapter 都会转为相同的 AgentStreamEvent前端逻辑零差异。前端可编排用 Hook/Context 管理上下文、工具、重试/变体、回调形成稳定的胶水层。渐进增强一期只做 Chat但保留 threadId/runId为“历史/检查点/回放/评测”留出Agent能力口。三、架构总览只列出 Chat 模式强相关的核心模块更多细节见项目架构文档① 统一消息模型覆盖 UserMessage、AssistantMessage、Thinking-Message、ActionExecution-Message、ResultMessage 等类型含 status 与可选 parentMessageId可扩展图片、状态消息。② Runtime Adapter 接口generateResponse(params) / retry(params) 返回 ReadableStreamAgentStreamEventsendFeedback 统一正/负反馈。可对接多种后端“流”内置 VAPD 适配示例也可扩展 GraphQL/WebSocket/自定义 Fetch 流无论来源如何都会标准化为 AgentStreamEvent。③ 前端编排OrchestrationAgentKit 作为 Provider 暴露上下文统一注入 runtime、actions、上下文树、消息与加载状态、重载完成回调等。useAgentChat 组合 useChat提供 append-Message、reloadMessages、stop-Generation、threadId、runId 等能力。useChat 串接 Runtime 流式事件处理工具调用与 Agent 循环并维护 AbortController。④ Vue UI 组件Chat 容器封装输入/消息区/操作/建议项借助 useCopilotChatLogic 与 Core 同步。四、事件流与消息模型把一切都还原成消息后端返回的是“事件”前端消费的是“消息”。我们把差异收敛在 Adapter 层增量累加把分片 token 聚合为 Thinking-Message / AssistantMessage。工具事件tool_call → ActionExecution-Messagetool_result → ResultMessage。统一标识维护 threadId会话与 runId本轮 loop为历史/检查点铺路。精确收束依据服务端“回合结束”信号或本地规则准确结束本轮流。上层只看到标准的 AgentStreamEventexport type AgentStreamEvent { threadId?: string | null runId?: string | null messages?: Message[] guardrailsFailureReason?: string }UI 组件无须关心消息从哪里来只负责渲染消息序列。五、Agent 回合循环loop与工具调用toolsChat 模式不仅是“生成一条回复”而是“一轮内可能包含多条消息”思考、工具调用、结果回注、继续生成……我们把“回合循环”放在 useChat 中集中处理串接流式事件按顺序追加消息捕获 ActionExecutionMessage 触发前端工具 handler并把结果回注为 ResultMessage当一轮结束返回最终 AssistantMessage 并可进入下一轮在“重载/变体”场景中保留既有候选并追加新候选形成多变体集合。与传输方式无关只要后端发出等价事件Adapter 统一映射工具消息即可完整往返。工具调用的前端形态useAgentAction为了让“工具”在页面内即可声明与注册我们提供了 useAgentAction描述name/description/parameters处理handler(args) 返回值会被打包成 ResultMessage 回注对话可选渲染render 可将工具调用或结果以内嵌卡片形式展示不影响文本流幂等同一执行 ID 只会触发一次 handler去重。与运行时的关系Adapter 负责把后端的工具事件统一映射为前端消息UI 不需要关注具体协议与传输方式。六、UI 交互与建议SuggestionsChat 作为容器暴露了消息渲染插槽与输入区控制默认行为渲染 Thinking、Assistant、User、Error 等消息类型支持复制、停止、重新生成、建议点击useCopilotChatLogic 负责把 Core 能力useAgentChat与 UI 事件连起来并提供节流后的建议刷新入口。七、最小上手3 步把 Chat 接入到任一页面// 1) 在根组件用 AgentKit 包裹并选择 Runtime // App.vue template AgentKit :runtimeruntime MyChat / /AgentKit /template script langts import { AgentKit, VapdRuntimeAdapter } from vapd-agentkit/vue-core exportdefault { components: { AgentKit }, setup() { const runtime new VapdRuntimeAdapter({ // 可选自定义 url/headers/agentId/appId/extendParams }) return { runtime } } } /script // 2) 页面里直接用 Chat或自定义渲染 template AgentChat :labels{ placeholder: 问点什么 } / /template script setup langts import { AgentChat } from vapd-agentkit/vue-ui /script // 3) 可选注册工具供模型调用 // 任一组件 setup 中 import { useAgentContext } from vapd-agentkit/vue-core const ctx useAgentContext() ctx.setAction(searchDocs, { name: searchDocs, description: 搜索知识库, parameters: [{ name: q, type: string }], handler: async ({ q }) { const result await fetch(/api/search?q${encodeURIComponent(q)}).then(r r.json()) return { hits: result.items } } })八、与业务的契合笔记/知识库/项目管理前端可把当前选中文段/标签/页面结构通过 addContext 合并入 agentArgs无需更改 Runtime。知识库agent文档/集成流程智能Agent未来规划把检索与聚合能力抽象为 FrontendAction回注 ResultMessage让 Agent 循环自动推进。九、面向知识库问答与集成流程智能的演进设想知识库问答 AgentRAG支持互联网检索结合站内知识完成回答提供关键字检索、内容获取与语义检索向量后续将支持直接帮你编辑、 新增文档等操作让 AI 准确看到你正在关注的内容与你的上下文保持一致帮助你更高效地思考、写作与创造。2. 集成流程自动配置添加节点配置节点验证节点一句话帮你完成流程配置面向非开发同学解决流程编排困难和语法复杂的问题支持从自然语言自动生成流程与节点参数节点配置表单化参数智能补全与校验自动化验证每一步并给出修复建议支持逐步验证与仿真运行输出日志与每步结果检查。十、下一步需完善
