README-cn-traditional.md

May 29, 2026 · View on GitHub

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。

運行您的第一個工作流程

您的新專案還包括一個強大的工作流程引擎。

費用批准工作流程演示了具有暫停/恢復功能的人機協作自動化：

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：

前往工作流程頁面：啟動伺服器後，直接前往工作流程頁面。
選擇您的專案：使用專案選擇器選擇您的專案（例如「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 研究助手代理 - 用於生成全面報告的多代理研究工作流程。(原始碼 | 視訊)