企业官网建设流程全解析

用 Vista.js 打造你的第一个 AI Agent：多模型、工具调用与会话记忆完整教程

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista

Vista.js 是一个面向现代 Web 的全栈框架，其内置的AI Agent 能力（vista/ai模块）让你无需引入任何第三方 Agent SDK，就能快速构建支持多模型切换、工具调用与会话记忆的智能体。本文面向新手，用最简单的路径带你从零跑通第一个 AI Agent，并理解它背后的每一步机制。🤖

一、Vista.js AI Agent 是什么？为什么值得用？

Vista.js 的 Agent 能力直接内置在核心包里，入口是 packages/vista/src/ai/ 目录。它把构建一个"能干活的 AI"所需的三块拼图一次性给你：

• 多模型接入：一行字符串即可切换 OpenAI、Anthropic、Gemini、Ollama 等供应商
• 工具调用（Tool Calling）：让 Agent 执行查天气、搜知识库、调接口等真实操作
• 会话记忆（Memory）：同一用户的多轮对话自动"记得上文"

官方文档对这部分有清晰说明，建议常备：packages/vista/docs/ai.md。

二、多模型支持：用一行字符串切换大模型

创建 Agent 时，model字段采用供应商:模型名的格式，解析逻辑位于 packages/vista/src/ai/providers/base.ts，常见写法如下：

两个新手友好的小技巧：

• 省略供应商前缀也没关系：框架会根据gpt-、claude-、gemini-等前缀自动猜测供应商。
• 没有 API Key 也能开发：用mock:echo或自定义的模拟模型即可完整调试 Agent 流程，正式环境再换成真实模型。官方 RAG 演示就是这种思路，参见 apps/vista-rag-demo/lib/rag-agent.ts。

三、创建你的第一个 AI Agent：agent() 函数全解

调用agent()函数即可创建一个 Agent 实例，核心逻辑在 packages/vista/src/ai/agent.ts。它接收一个配置对象，最常用的选项如下：

一个最小的客服 Agent 配置示例（官方文档中的同款写法）：

import { agent, tool } from 'vista/ai'; export const supportAgent = agent({ name: 'support', model: 'openai:gpt-4o', systemPrompt: 'You are a helpful AI assistant for support.', tools: [ tool({ name: 'ping', description: 'Check agent connectivity', execute: async () => ({ status: 'ok' }), }), ], memory: true, });

💡 提示：框架还提供了vista g agent support命令可以自动生成 Agent 模块文件，省去手动搭建结构的麻烦。

四、给 Agent 装上"手和脚"：工具调用机制

工具调用是让 AI 从"只会聊天"变成"能办事"的关键。通过tool()函数定义工具（见 packages/vista/src/ai/tool.ts），只需提供四样东西：

1. name：工具名，例如search_knowledge_base
2. description：给模型看的用途说明，写得越清楚，模型调用得越准
3. parameters：JSON Schema 描述入参（可省略）
4. execute：真正执行任务的函数，支持返回 Promise

工具调用的运行循环

当 Agent 运行时，框架会自动完成这套循环（实现在 agent.ts 的 run 方法）：

• 第 1 步：模型判断需要查资料 → 发出tool-call
• 第 2 步：框架执行对应工具，把结果作为tool消息写回对话
• 第 3 步：模型基于工具结果继续推理，直到给出最终答案

每一步都会被maxSteps上限保护，防止无限循环；执行失败也不会中断，而是把错误信息反馈给模型让它自行纠正。更妙的是.asTool()方法（agent.ts），可以把一个 Agent 整体包装成另一个 Agent 的工具，轻松实现多 Agent 协作。

五、会话记忆：让 Agent 记住"我们聊过什么"

把memory设为true，框架就会使用内置的InMemoryStore（见 packages/vista/src/ai/memory.ts）。你只需在每次请求中传入同一个sessionId，Agent 就会自动：

• 按sessionId读取历史对话，拼接进本轮上下文
• 本轮结束后自动保存最新对话历史

默认每个会话最多保留100 条消息，也支持设置ttlMs让会话过期自动清理。这套机制让你用极低的成本获得"多轮对话"体验，无需自己手写状态管理。

六、流式输出 + React 组件：把 Agent 接入前端

真实产品里，用户希望"边生成边看到"。Vista.js 把这条链路也做好了：

• 服务端：调用agent.stream()，再用toDataStreamResponse()把流式结果转成标准 SSE 响应（stream.ts），直接 return 给 API 路由即可
• 前端：使用vista/ai/react导出的useAgentHook（use-agent.ts），一次性获得messages、input、handleSubmit、isLoading、stop（中途停止）、reload（重新生成）等状态与方法，解析 SSE、更新界面这些脏活全由它代劳

完整的前端示例可以参考官方 RAG 演示应用的聊天组件：apps/vista-rag-demo/app/ai-playground/chat-box.tsx。

七、完整案例：一个无需 API Key 的 RAG 知识库助手

仓库自带的 apps/vista-rag-demo/ 是一个"开箱即演示"的完整样例，值得逐行读一读：

• lib/rag-agent.ts：用agent()组装 Agent，挂上"搜索知识库"工具，maxSteps: 4
• lib/rag-knowledge.ts：内置演示用文档数据
• app/api/rag-chat/：流式 API 路由
• app/ai-playground/：带流式渲染的聊天页面

它完美展示了本文讲到的全部要素：多模型（用自定义 mock 模型）+ 工具调用（检索知识库）+ 流式输出，是新手理解 Agent 全流程的最佳参照。

八、快速上手清单 ✅

1. 在配置model前，先确认对应的环境变量（API Key）已设置
2. 用mock:echo或 Ollama 本地模型先跑通流程，再切到付费模型
3. 工具description写得越清晰，模型调用越准确
4. 需要多轮对话时开启memory: true并固定sessionId
5. 前端统一使用useAgentHook，避免手搓 SSE 解析

至此，你已经掌握了用 Vista.js 构建 AI Agent 的核心三板斧——多模型、工具调用、会话记忆。从官方文档 packages/vista/docs/ai.md 出发，再参考 RAG 演示应用，你的第一个生产级 AI Agent 很快就能上线。✨

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista