voltagent/i18n/README-cn-bsc.md at main · chrisisagile/voltagent

AI Agent 工程平台

English | 繁體中文 | 简体中文 | 日本語 | 한국어

首页 | 文档 | 示例

⭐ 喜欢我们的项目吗？给我们一个星标 ⬆️

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

开源 TypeScript 框架 – Memory、RAG、Guardrails、Tools、MCP、Voice、Workflow 等。
VoltOps 控制台 Cloud Self-Hosted – 可观测性、自动化、部署、评估、安全护栏、提示词等。

以完全的代码控制构建代理，并以生产就绪的可视化和操作来发布它们。

核心 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，用于 Claude、Cursor 或 Windsurf 等 AI 驱动的编码助手。这允许 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: "A helpful assistant that can check weather and help with various tasks",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
  memory,
});

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

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

npm run dev

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

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

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

您的代理现在正在运行！要与其互动：

打开控制台：点击终端输出中的 VoltOps LLM 可观测性平台链接（或复制并粘贴到浏览器）。
找到您的代理：在 VoltOps LLM 可观测性平台页面上，您应该会看到列出的代理（例如"my-agent"）。
打开代理详情：点击代理名称。
开始聊天：在代理详情页面上，点击右下角的聊天图标以打开聊天窗口。
发送消息：输入"你好"之类的消息并按 Enter。

step-3-test.mp4

运行您的第一个工作流

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

费用批准工作流演示了具有暂停/恢复功能的人机协作自动化：

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

export const expenseApprovalWorkflow = createWorkflowChain({
  id: "expense-approval",
  name: "Expense Approval Workflow",
  purpose: "Process expense reports with manager approval for high amounts",

  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("Manager approval required", {
          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：

workflow.mp4

前往工作流页面：启动服务器后，直接前往工作流页面。
选择您的项目：使用项目选择器选择您的项目（例如"my-agent-app"）。
查找并运行：您将看到列出的 "Expense Approval Workflow"。点击它，然后点击 "Run" 按钮。

提供输入：工作流期望包含费用详情的 JSON 对象。尝试小额费用以进行自动批准：

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

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

示例

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

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