⭐ 喜欢我们的工作吗？请给我们点个赞吧 ⬆️

VoltAgent 是一个端到端的 AI 智能体工程平台，主要由两部分组成：

• 开源 TypeScript 框架：内存、RAG、护栏、工具、MCP、语音、工作流等。
• VoltOps 控制台 云端 自托管：可观测性、自动化、部署、评估、护栏、提示词等。

通过该平台，您可以完全掌控代码来构建智能体，并以生产就绪的方式进行部署和运维。

核心 TypeScript 框架

借助这个开源框架，您可以在连接任何 AI 提供商的同时，构建具备记忆、工具和多步工作流的智能体。您还可以创建复杂的多智能体系统，让各个专业智能体在主管的协调下协同工作。

• 核心运行时 (@voltagent/core)：在一个地方定义具有类型化角色、工具、记忆和模型提供商的智能体，使一切井然有序。
• 工作流引擎：以声明式方式描述多步骤自动化流程，而无需手动拼接自定义控制流。
• 主管与子智能体：在主管运行时下运行一组专业智能体，由主管负责任务分配并保持同步。
• 工具注册表 和 MCP：交付带有生命周期钩子和取消功能的 Zod 类型化工具，并可无需额外胶水代码即可连接到 Model Context Protocol 服务器。
• LLM 兼容性：只需更改配置即可在 OpenAI、Anthropic、Google 等提供商之间切换，而无需重写智能体逻辑。
• 记忆：附加持久化的记忆适配器，使智能体能够在多次运行中记住重要上下文。
• 可恢复流式传输：允许客户端在刷新后重新连接到正在进行的流，并继续接收相同的响应。
• 检索与 RAG：接入检索智能体，从您的数据源中提取事实，并在模型回答之前对响应进行接地处理（RAG）。
• VoltAgent 知识库：使用托管的 RAG 服务进行文档摄取、分块、嵌入和搜索。
• 语音：通过 OpenAI、ElevenLabs 或自定义语音提供商为智能体添加文本转语音和语音转文本功能。
• 护栏：在运行时拦截并验证智能体的输入或输出，以执行内容政策和安全规则。
• 评估：在工作流中同时运行智能体评估套件，以衡量和改进智能体的行为。

MCP 服务器 (@voltagent/mcp-docs-server)

您可以使用 MCP 服务器 @voltagent/mcp-docs-server 来教会您的 LLM 如何使用 VoltAgent 构建 AI 驱动的编码助手，例如 Claude、Cursor 或 Windsurf。这样，AI 助手就可以在您编写代码时直接访问 VoltAgent 的文档、示例和变更日志。

📖 如何设置 MCP 文档服务器

⚡ 快速入门

使用 create-voltagent-app CLI 工具，几秒钟内即可创建一个新的 VoltAgent 项目：

npm create voltagent-app@latest

该命令会引导您完成设置。

您将在 src/index.ts 中看到启动代码，其中现在注册了一个代理以及位于 src/workflows/index.ts 中的完整工作流示例。

import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";

// 创建日志实例
const logger = createPinoLogger({
  name: "my-agent-app",
  level: "info",
});

// 可选的持久化内存（移除以使用默认的内存中存储）
const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

// 项目中的一个简单通用代理。
const agent = new Agent({
  name: "my-agent",
  instructions: "一个可以帮助查询天气并处理各种任务的助手",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
  memory,
});

// 使用您的代理和工作流初始化 VoltAgent
new VoltAgent({
  agents: {
    agent,
  },
  workflows: {
    expenseApprovalWorkflow,
  },
  server: honoServer(),
  logger,
});

之后，导航到您的项目并运行：

npm run dev

运行开发命令时，tsx 将编译并运行您的代码。您应该会在终端中看到 VoltAgent 服务器启动消息：

══════════════════════════════════════════════════
VOLTAGENT 服务器已成功启动
══════════════════════════════════════════════════
✓ HTTP 服务器：http://localhost:3141

使用 VoltOps 控制台测试您的代理：https://console.voltagent.dev
══════════════════════════════════════════════════

您的代理现已运行！要与之交互：

1. 打开控制台：点击终端输出中的 VoltOps LLM 可观测性平台 链接（或将其复制粘贴到浏览器中）。
2. 查找您的代理：在 VoltOps LLM 可观测性平台页面上，您应能看到您的代理（例如“my-agent”）。
3. 打开代理详情：点击您的代理名称。
4. 开始聊天：在代理详情页面上，点击右下角的聊天图标以打开聊天窗口。
5. 发送消息：输入类似“Hello”的消息并按 Enter 键。

运行您的第一个工作流

您的新项目还包含一个强大的工作流引擎。

费用审批工作流展示了带暂停/恢复功能的人工介入自动化流程：

import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

export const expenseApprovalWorkflow = createWorkflowChain({
  id: "expense-approval",
  name: "费用审批工作流",
  purpose: "处理需要经理批准的大额费用报销单",

  input: z.object({
    employeeId: z.string(),
    amount: z.number(),
    category: z.string(),
    description: z.string(),
  }),
  result: z.object({
    status: z.enum(["approved", "rejected"]),
    approvedBy: z.string(),
    finalAmount: z.number(),
  }),
})
  // 步骤1：验证费用并检查是否需要审批
  .andThen({
    id: "check-approval-needed",
    resumeSchema: z.object({
      approved: z.boolean(),
      managerId: z.string(),
      comments: z.string().optional(),
      adjustedAmount: z.number().optional(),
    }),
    execute: async ({ data, suspend, resumeData }) => {
      // 如果我们是从经理的决定处恢复
      if (resumeData) {
        return {
          ...data,
          approved: resumeData.approved,
          approvedBy: resumeData.managerId,
          finalAmount: resumeData.adjustedAmount || data.amount,
        };
      }

      // 检查是否需要经理批准（超过500美元的费用）
      if (data.amount > 500) {
        await suspend("需要经理批准", {
          employeeId: data.employeeId,
          requestedAmount: data.amount,
        });
      }

      // 自动批准小额费用
      return {
        ...data,
        approved: true,
        approvedBy: "system",
        finalAmount: data.amount,
      };
    },
  })
  // 步骤2：处理最终决定
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });

您可以直接从 VoltOps 控制台测试预建的 expenseApprovalWorkflow：

1. 前往工作流页面：启动服务器后，直接访问 工作流页面。
2. 选择您的项目：使用项目选择器选择您的项目（例如“my-agent-app”）。
3. 查找并运行：您将看到列出的“费用审批工作流”。点击它，然后点击“运行”按钮。
4. 提供输入：工作流期望一个包含费用详情的 JSON 对象。尝试一笔小额费用以实现自动批准：

   {
     "employeeId": "EMP-123",
     "amount": 250,
     "category": "office-supplies",
     "description": "新的笔记本电脑鼠标和键盘"
   }
   

5. 查看结果：执行完成后，您可以检查每一步的详细日志，并在控制台中直接查看最终输出。

示例

更多示例，请访问我们的 示例仓库。

• Airtable 代理 - 使用 VoltOps 操作对新记录作出反应，并将更新写回 Airtable。
• Slack 代理 - 响应频道消息，并通过 VoltOps Slack 操作进行回复。
• 带有 VoltAgent 的 ChatGPT 应用 - 在 MCP 上部署 VoltAgent，并连接到 ChatGPT 应用。
• WhatsApp 订单代理 - 构建一个 WhatsApp 聊天机器人，通过自然对话处理食物订单。(源代码)
• YouTube 到博客代理 - 使用带有 MCP 工具的监督代理，将 YouTube 视频转换为 Markdown 博客文章。(源代码)
• AI 广告生成器代理 - 使用 BrowserBase Stagehand 和 Google Gemini AI 生成 Instagram 广告。(源代码)
• AI 食谱生成器代理 - 根据食材和偏好创建个性化烹饪建议。(源代码 | 视频)
• AI 研究助理代理 - 多代理研究工作流，用于生成综合报告。(源代码 | 视频)

VoltOps 控制台：LLM 可观测性、自动化与部署

VoltOps 控制台是 VoltAgent 的平台端，提供可观测性、自动化和部署功能，使您能够通过实时执行跟踪、性能指标和可视化仪表板，在生产环境中监控和调试代理。

🎬 试用在线演示

📖 VoltOps 文档

🚀 VoltOps 平台

可观测性与追踪

通过详细的追踪记录和性能指标，深入洞察代理的执行流程。

仪表板

全面了解所有代理、工作流以及系统性能指标。

日志

跟踪每次代理交互和工作流步骤的详细执行日志。

内存管理

检查和管理代理的内存、上下文和对话历史。

追踪记录

分析完整的执行追踪记录，以理解代理行为并优化性能。

提示词构建器

直接在控制台中设计、测试和优化提示词。

部署

通过一键式 GitHub 集成和托管基础设施，将您的代理部署到生产环境。

📖 VoltOps 部署文档

触发器与操作

使用 Webhook、计划任务和自定义触发器自动执行代理工作流，以响应外部事件。

监控

监控整个系统的代理健康状况、性能指标和资源使用情况。

安全护栏

设置安全边界和内容过滤器，以确保代理在定义的参数范围内运行。

评估

运行评估套件，以测试代理的行为、准确性和相对于基准的表现。

RAG（知识库）

通过内置的检索增强生成能力，将您的代理连接到知识源。

学习 VoltAgent

• 从交互式教程开始，学习构建 AI 代理的基础知识。
• 文档：深入了解指南、概念和教程。
• 示例：探索实际应用。
• 博客：阅读更多技术见解和最佳实践。

贡献

我们欢迎贡献！请参阅贡献指南（如有链接需补充）。如有任何问题或讨论，请加入我们的 Discord 服务器。

致谢 ♥️ 贡献者

非常感谢所有参与 VoltAgent 发展历程的人，无论您是开发了插件、提交了问题、拉取请求，还是仅仅在 Discord 或 GitHub Discussions 上帮助过他人。

VoltAgent 是一项社区协作项目，正是因为有像您们这样的人，它才能不断进步。

许可证

根据 MIT 许可证授权，版权 © 2026 年至今 VoltAgent。

VoltAgent 快速上手指南

VoltAgent 是一个端到端的 AI Agent 工程平台，包含开源 TypeScript 框架和 VoltOps 控制台。它支持记忆管理、RAG、工作流编排、多智能体协作等功能，帮助开发者构建可生产落地的 AI 应用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 18.x 或更高（推荐 20.x+）。
• 包管理器: npm, yarn, pnpm 或 bun。
• 代码编辑器: 推荐 VS Code。
• 网络环境: 能够访问 npm registry 和外部 AI 模型提供商（如 OpenAI）。

提示：国内开发者若遇到 npm 安装缓慢，可临时切换至国内镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

使用官方提供的 CLI 工具 create-voltagent-app 即可在几秒钟内初始化项目。

在终端执行以下命令：

npm create voltagent-app@latest

按照命令行提示完成项目命名和配置。安装完成后，进入项目目录：

cd <your-project-name>

项目已预置了基础的 Agent 代码和工作流示例（位于 src/index.ts 和 src/workflows/index.ts）。

基本使用

1. 启动开发服务器

在项目根目录下运行以下命令启动服务：

npm run dev

tsx 将自动编译并运行代码。当看到以下输出时，表示服务启动成功：

══════════════════════════════════════════════════
VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
✓ HTTP Server: http://localhost:3141

Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════

2. 与 Agent 交互

启动后，您可以通过 VoltOps 控制台直接与 Agent 对话：

1. 打开控制台：点击终端输出中的链接 (https://console.voltagent.dev) 或在浏览器中访问该地址。
2. 选择项目：在页面左上角选择您当前运行的项目（例如 my-agent-app）。
3. 进入详情：在列表中找到您的 Agent（如 my-agent），点击进入详情页。
4. 开始聊天：点击右下角的聊天图标，输入消息（例如 "Hello" 或 "今天天气如何"）并发送。

3. 运行工作流 (Workflow)

VoltAgent 内置了强大的工作流引擎。初始化项目包含一个“费用审批工作流”示例，演示了人机协作（Human-in-the-loop）和挂起/恢复功能。

测试步骤：

1. 在 VoltOps 控制台顶部导航栏点击 Workflows。
2. 找到 "Expense Approval Workflow" 并点击。
3. 点击 "Run" 按钮。
4. 在输入框中填入测试数据（JSON 格式）。尝试输入小于 500 的金额以触发自动审批：

   {
     "employeeId": "EMP-123",
     "amount": 250,
     "category": "office-supplies",
     "description": "New laptop mouse and keyboard"
   }
   

5. 点击执行，您可以在控制台中查看每一步的执行日志和最终结果。

核心代码结构参考

生成的 src/index.ts 展示了如何定义 Agent 和注册服务：

import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";

// 创建日志实例
const logger = createPinoLogger({
  name: "my-agent-app",
  level: "info",
});

// 可选：持久化记忆（移除则使用默认内存记忆）
const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

// 定义一个通用 Agent
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that can check weather and help with various tasks",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
  memory,
});

// 初始化 VoltAgent，注册 Agents 和 Workflows
new VoltAgent({
  agents: {
    agent,
  },
  workflows: {
    expenseApprovalWorkflow,
  },
  server: honoServer(),
  logger,
});

现在您已经成功运行了第一个 VoltAgent 应用。您可以前往 官方文档 探索更多高级功能，如 RAG、多智能体编排和自定义工具集成。