VoltAgent 深度学习笔记 / VoltAgent Deep Learning Notes

学习时间 | Learning Date: 2024-XX-XX

项目地址 | Project: https://github.com/VoltAgent/voltagent

本地路径 | Local Path: ./voltagent/

核心定位 | Core Focus: AI Agent Engineering Platform

一、项目概述 / Project Overview

1.1 框架定位 / Framework Positioning

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

开源 TypeScript 框架 (@voltagent/core) - 包含 Memory、RAG、Guardrails、Tools、MCP、Voice、Workflow 等

VoltOps Console (Cloud/Self-Hosted) - 可观测性、自动化、部署、Evals、Guardrails、Prompts 管理

┌─────────────────────────────────────────────────────────────────┐
│                        VoltAgent Platform                         │
├─────────────────────────────┬───────────────────────────────────┤
│     Open Source Framework   │        VoltOps Console             │
├─────────────────────────────┼───────────────────────────────────┤
│  @voltagent/core            │  Cloud / Self-Hosted              │
│  ├─ Agent Orchestration     │  ├─ Observability & Tracing       │
│  ├─ Memory Management        │  ├─ Automation & Triggers          │
│  ├─ Tool Registry           │  ├─ Deployment                     │
│  ├─ MCP Support             │  ├─ Evals                         │
│  ├─ Workflow Engine         │  ├─ Guardrails                     │
│  ├─ RAG & Retrieval         │  └─ Prompt Management             │
│  └─ Voice Support           │                                    │
└─────────────────────────────┴───────────────────────────────────┘
1.2 核心特性 / Core Features


特性 Feature 描述 Description

Agent Agent 使用类型化角色、工具、内存和模型提供者定义代理 Define agents with typed roles, tools, memory, and model providers
Workflow Workflow Engine 声明式多步骤自动化 Declarative multi-step automation
Supervisors Supervisors & Sub-Agents 在主管运行时下运行专门的代理团队 Run teams of specialized agents under supervisor runtime
Tools/MCP Tool Registry & MCP 生命周期钩子和取消的 Zod 类型化工具 Zod-typed tools with lifecycle hooks and cancellation
Memory Memory 持久的内存适配器 Durable memory adapters
RAG RAG 检索增强生成 Retrieval Augmented Generation
Voice Voice 文本转语音和语音转文本 Text-to-speech and speech-to-text
Guardrails Guardrails 输入/输出拦截和验证 Input/output interception and validation
Evals Evals 代理评估套件 Agent evaluation suites

1.3 与竞品对比 / Comparison with Competitors


框架 Framework 优势 Advantages

LangChain LangChain 生态丰富 Rich ecosystem
LangGraph LangGraph 状态机模式 State machine pattern
VoltAgent VoltAgent TypeScript 原生、完整工程平台、VoltOps Console 集成 TypeScript native, full engineering platform, VoltOps Console integration



二、核心架构 / Core Architecture

2.1 目录结构 / Directory Structure


voltagent/
├── packages/                    # 核心包
│   ├── core/                   # 主框架
│   │   └── src/
│   │       ├── agent/          # Agent 核心实现
│   │       ├── memory/         # 内存管理
│   │       ├── tool/           # 工具系统
│   │       ├── workflow/       # 工作流引擎
│   │       ├── mcp/            # MCP 支持
│   │       ├── voice/          # 语音支持
│   │       ├── observability/  # 可观测性
│   │       └── ...
│   ├── cli/                    # CLI 工具
│   ├── libsql/                 # LibSQL 集成
│   ├── postgres/               # PostgreSQL 集成
│   └── ...
├── examples/                   # 示例实现 (90+)
├── docs/                       # 文档
└── i18n/                       # 国际化
2.2 核心模块架构图 / Core Module Architecture

ascii
                          ┌─────────────────────────┐
                          │       VoltAgent         │
                          │     (Main Entry)         │
                          └───────────┬─────────────┘
                                      │
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
    ┌─────▼─────┐              ┌──────▼──────┐           ┌──────▼──────┐
    │   Agent    │              │   Workflow   │           │  Observa-   │
    │            │              │    Engine    │           │   bility    │
    ├────────────┤              ├─────────────┤           ├─────────────┤
    │ - Tools    │              │ - andThen    │           │ - Tracing   │
    │ - Memory   │              │ - andAgent   │           │ - Logging   │
    │ - Guardrails│              │ - andBranch  │           │ - Metrics   │
    │ - Middleware│              │ - suspend()   │           └─────────────┘
    └────────────┘              └──────────────┘
          │
    ┌─────┴─────┐              ┌──────────────┐
    │   Model    │              │   MCP Client  │
    │  Provider  │              │              │
    │  Registry   │              │ - Tools     │
    └────────────┘              │ - Resources  │
                                 │ - Prompts    │
                                 └──────────────┘
2.3 包依赖关系 / Package Dependencies

json
// @voltagent/core 核心依赖
{
  "dependencies": {
    "@ai-sdk/openai": "^3.0.0",
    "@ai-sdk/anthropic": "^3.0.0",
    "@ai-sdk/google": "^3.0.0",
    "@modelcontextprotocol/sdk": "^1.12.1",
    "@opentelemetry/api": "^1.9.0",
    "ai": "^6.0.0",
    "zod": "^3.25.76"
  }
}


三、Agent 设计 / Agent Design

3.1 创建 Agent / Creating an Agent

typescript
import { Agent, Memory, VoltAgent } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";

// 创建持久化内存
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"),  // 支持 OpenAI, Anthropic, Google 等
  tools: [weatherTool],
  memory,
});

// 初始化 VoltAgent
new VoltAgent({
  agents: { agent },
  server: honoServer(),
  logger,
});
3.2 Agent 配置选项 / Agent Configuration Options


typescript
interface AgentOptions {
  // 必需
  name: string;                    // Agent 名称
  model: LanguageModel;            // 语言模型
  
  // 可选
  instructions?: string | DynamicInstructions;
  tools?: Tool[];
  memory?: Memory;
  inputGuardrails?: InputGuardrail[];
  outputGuardrails?: OutputGuardrail[];
  hooks?: AgentHooks;
  workspace?: Workspace;
  subagents?: SubAgentConfig[];
}
3.3 动态指令 / Dynamic Instructions

typescript
const agent = new Agent({
  name: "Dynamic Agent",
  instructions: async ({ prompts, userId }) => {
    // 从 VoltOps 获取提示
    const prompt = await prompts.getPrompt({
      promptName: "support-agent",
      version: 4,
    });
    return prompt;
  },
  model: openai("gpt-4o-mini"),
});


四、工具系统 / Tool System

4.1 创建工具 / Creating Tools

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

// 定义天气查询工具
export const weatherTool = createTool({
  name: "getWeather",
  description: "Get the current weather in a given location",
  
  parameters: z.object({
    city: z.string().describe("The city to get weather for"),
    unit: z.enum(["celsius", "fahrenheit"]).optional(),
  }),
  
  execute: async ({ city, unit }) => {
    const temp = await fetchWeather(city);
    return The weather in ${city} is ${temp}°${unit === "celsius" ? "C" : "F"};
  },
  
  // 生命周期钩子
  hooks: {
    onStart: async ({ tool, args }) => {
      console.log(Calling ${tool.name} with args:, args);
    },
    onEnd: async ({ tool, output }) => {
      console.log(${tool.name} returned:, output);
    },
  },
});
4.2 工具生命周期 / Tool Lifecycle


ascii
┌─────────────────────────────────────────────────────────────┐
│                    Tool Lifecycle                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   User Input ──► Tool Selection ──► onStart Hook            │
│                      │                    │                  │
│                      ▼                    ▼                  │
│               ┌─────────────┐      Execute Tool              │
│               │   Zod       │            │                  │
│               │  Validation │            ▼                  │
│               └─────────────┘      onEnd Hook                │
│                      │                    │                  │
│                      ▼                    ▼                  │
│               Tool Result ──► Return to Agent                │
│                                                              │
└─────────────────────────────────────────────────────────────┘
4.3 MCP 工具 / MCP Tools

typescript
import { MCPClient } from "@voltagent/core";

// 连接到 MCP 服务器
const mcpClient = new MCPClient({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"],
});

const agent = new Agent({
  name: "MCP Agent",
  model: openai("gpt-4o-mini"),
  tools: mcpClient.tools(),
});


五、内存系统 / Memory System

5.1 Memory 架构 / Memory Architecture

typescript
// 基础内存配置
const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./memory.db" }),
  embedding: "openai/text-embedding-3-small",  // 可选：嵌入模型
  vector: new LibSQLVectorAdapter(),              // 可选：向量存储
  workingMemory: {                                // 可选：工作内存
    scope: "conversation",
    maxTokens: 4000,
  },
  generateTitle: true,                           // 自动生成会话标题
});
5.2 内存操作 / Memory Operations

typescript
// 保存消息
await memory.addMessage(message, userId, conversationId);

// 获取消息
const messages = await memory.getMessages(userId, conversationId, {
  limit: 50,
  cursor: "some-cursor",
});

// 语义搜索
const results = await memory.search({
  userId,
  conversationId,
  query: "What was discussed about pricing?",
  limit: 10,
});

// 清除会话
await memory.clearMessages(userId, conversationId);
5.3 工作内存 / Working Memory


typescript
// 工作内存配置
const memory = new Memory({
  storage: new LibSQLMemoryAdapter(),
  workingMemory: {
    scope: "conversation",           // "conversation" | "agent" | "global"
    maxTokens: 4000,
    includeSystemContext: true,
  },
});

// 在 Agent 中自动使用
const agent = new Agent({
  name: "Assistant",
  model: openai("gpt-4o-mini"),
  memory,
});


六、工作流引擎 / Workflow Engine

6.1 创建工作流 / Creating Workflows

typescript
import { createWorkflow, andThen, andAgent, andBranch } from "@voltagent/core";
import { z } from "zod";

// 定义订单处理工作流
const orderWorkflow = createWorkflow(
  {
    id: "order-processing",
    name: "Order Processing Workflow",
    purpose: "Process orders with fraud detection",
    
    // 输入/输出类型定义
    input: z.object({
      orderId: z.string(),
      customerId: z.string(),
      amount: z.number(),
    }),
    result: z.object({
      orderId: z.string(),
      status: z.enum(["approved", "rejected"]),
    }),
  },
  
  // 步骤 1: 验证订单
  andThen({
    id: "validate-order",
    execute: async ({ data, setWorkflowState }) => {
      const isValid = data.amount > 0;
      setWorkflowState({ validatedAt: new Date().toISOString() });
      return { ...data, isValid };
    },
  }),
  
  // 步骤 2: AI 代理分析
  andAgent(
    async ({ data }) => 分析此订单的风险等级...,
    analysisAgent,
    {
      schema: z.object({
        riskLevel: z.enum(["low", "medium", "high"]),
        reasoning: z.string(),
      }),
    }
  ),
  
  // 步骤 3: 条件分支
  andBranch({
    id: "final-decision",
    branches: [
      {
        condition: ({ data }) => data.riskLevel === "high",
        step: andThen({
          id: "reject",
          execute: async ({ data }) => ({ ...data, status: "rejected" }),
        }),
      },
      {
        condition: ({ data }) => data.riskLevel === "low",
        step: andThen({
          id: "approve",
          execute: async ({ data }) => ({ ...data, status: "approved" }),
        }),
      },
    ],
  }),
);
6.2 工作流步骤类型 / Workflow Step Types



方法 Method 描述 Description

andThen andThen 执行同步/异步函数 Execute sync/async function
andAgent andAgent 调用 AI 代理 Call AI agent
andBranch andBranch 条件分支 Conditional branching
andForEach andForEach 并行遍历数组 Parallel array iteration
andMap andMap 映射转换数据 Map transform data
andDoWhile andDoWhile 条件循环 Conditional loop
andDoUntil andDoUntil 直到条件循环 Until condition loop
andSleep andSleep 延迟等待 Delay/wait
andGuardrail andGuardrail 执行防护栏 Execute guardrail
andTap andTap 日志/副作用 Log/side effects

6.3 暂停与恢复 / Suspend and Resume

typescript
const expenseWorkflow = createWorkflow(
  {
    id: "expense-approval",
    input: z.object({ amount: z.number() }),
    result: z.object({ status: z.enum(["approved", "rejected"]) }),
  },
  andThen({
    id: "check-approval",
    resumeSchema: z.object({
      approved: z.boolean(),
      managerId: z.string(),
    }),
    execute: async ({ data, suspend, resumeData }) => {
      // 如果是被恢复的流程
      if (resumeData) {
        return { status: resumeData.approved ? "approved" : "rejected" };
      }
      
      // 需要人工审批
      if (data.amount > 500) {
        await suspend("Manager approval required", {
          amount: data.amount,
          employeeId: "EMP-123",
        });
      }
      
      return { status: "approved" };
    },
  }),
);


七、Guardrails 防护系统 / Guardrails System

7.1 输入防护 / Input Guardrails

typescript
import { createInputGuardrail } from "@voltagent/core";

// 敏感信息检测
const piiGuardrail = createInputGuardrail({
  name: "pii-detector",
  handler: async ({ input }) => {
    const piiPatterns = [
      /\b\d{3}-\d{2}-\d{4}\b/,  // SSN
      /\b\d{16}\b/,               // Credit card
    ];
    
    for (const pattern of piiPatterns) {
      if (pattern.test(input)) {
        return {
          pass: false,
          action: "block",
          message: "Sensitive information detected",
        };
      }
    }
    
    return { pass: true };
  },
});

const agent = new Agent({
  name: "Secure Agent",
  model: openai("gpt-4o-mini"),
  inputGuardrails: [piiGuardrail],
});
7.2 输出防护 / Output Guardrails


typescript
import { createOutputGuardrail } from "@voltagent/core";

// 恶意内容过滤
const profanityGuardrail = createOutputGuardrail({
  name: "profanity-filter",
  handler: async ({ output }) => {
    const cleaned = output.replace(/badword1|badword2/gi, "***");
    return {
      pass: true,
      action: "modify",
      modifiedOutput: cleaned,
    };
  },
});

// 使用默认防护
import { createDefaultSafetyGuardrails } from "@voltagent/core";

const agent = new Agent({
  name: "Safe Agent",
  model: openai("gpt-4o-mini"),
  outputGuardrails: [
    ...createDefaultSafetyGuardrails(),
    profanityGuardrail,
  ],
});


八、中间件系统 / Middleware System

8.1 中间件定义 / Middleware Definition

typescript
import { createInputMiddleware, createOutputMiddleware } from "@voltagent/core";

// 输入中间件
const loggingMiddleware = createInputMiddleware({
  name: "request-logger",
  handler: async ({ input, continue: continueFn }) => {
    console.log("Request:", input);
    const result = await continueFn(input);
    console.log("Response:", result);
    return result;
  },
});

// 输出中间件
const metricsMiddleware = createOutputMiddleware({
  name: "metrics",
  handler: async ({ output, continue: continueFn }) => {
    const start = Date.now();
    const result = await continueFn(output);
    const duration = Date.now() - start;
    metrics.record("response_time", duration);
    return result;
  },
});


九、模型提供商 / Model Providers

9.1 支持的提供商 / Supported Providers

typescript
// OpenAI
import { openai } from "@ai-sdk/openai";
const model = openai("gpt-4o");

// Anthropic
import { anthropic } from "@ai-sdk/anthropic";
const model = anthropic("claude-3-5-sonnet-latest");

// Google
import { google } from "@ai-sdk/google";
const model = google("gemini-1.5-pro");

// 等等...
// Azure, Amazon Bedrock, Cohere, Groq, Mistral, Perplexity, XAI 等
9.2 模型注册表 / Model Registry


typescript
// 在 VoltAgent 中配置模型
const agent = new Agent({
  name: "Multi-Model Agent",
  model: "openai/gpt-4o-mini",  // 字符串格式: "provider/model"
});


十、可观测性 / Observability

10.1 追踪配置 / Tracing Configuration

typescript
import { VoltAgentObservability, trace } from "@voltagent/core";

// 配置可观测性
const observability = new VoltAgentObservability({
  serviceName: "my-agent-service",
  spanProcessor: new WebSocketSpanProcessor(),
});

// 在 Agent 中使用
const agent = new Agent({
  name: "Traced Agent",
  model: openai("gpt-4o-mini"),
  hooks: {
    onFinish: async ({ agentName, response }) => {
      trace.getTracer("agent").startSpan("response-handler");
    },
  },
});


十一、文档规范 / Documentation Standards

11.1 AGENTS.md

VoltAgent 使用 AGENTS.md 作为 AI 代理的开发规范文档：

markdown
VoltAgent

VoltAgent is an open-source TypeScript framework for building and orchestrating AI agents.

Overview

View docs/structure.md for repository structure
View docs/tooling.md for development tools
View docs/testing.md for testing guidelines

Validating Changes

特性	Feature	描述	Description
Agent	Agent	使用类型化角色、工具、内存和模型提供者定义代理	Define agents with typed roles, tools, memory, and model providers
Workflow	Workflow Engine	声明式多步骤自动化	Declarative multi-step automation
Supervisors	Supervisors & Sub-Agents	在主管运行时下运行专门的代理团队	Run teams of specialized agents under supervisor runtime
Tools/MCP	Tool Registry & MCP	生命周期钩子和取消的 Zod 类型化工具	Zod-typed tools with lifecycle hooks and cancellation
Memory	Memory	持久的内存适配器	Durable memory adapters
RAG	RAG	检索增强生成	Retrieval Augmented Generation
Voice	Voice	文本转语音和语音转文本	Text-to-speech and speech-to-text
Guardrails	Guardrails	输入/输出拦截和验证	Input/output interception and validation
Evals	Evals	代理评估套件	Agent evaluation suites

框架	Framework	优势	Advantages
LangChain	LangChain	生态丰富	Rich ecosystem
LangGraph	LangGraph	状态机模式	State machine pattern
VoltAgent	VoltAgent	TypeScript 原生、完整工程平台、VoltOps Console 集成	TypeScript native, full engineering platform, VoltOps Console integration

方法	Method	描述	Description
`andThen`	andThen	执行同步/异步函数	Execute sync/async function
`andAgent`	andAgent	调用 AI 代理	Call AI agent
`andBranch`	andBranch	条件分支	Conditional branching
`andForEach`	andForEach	并行遍历数组	Parallel array iteration
`andMap`	andMap	映射转换数据	Map transform data
`andDoWhile`	andDoWhile	条件循环	Conditional loop
`andDoUntil`	andDoUntil	直到条件循环	Until condition loop
`andSleep`	andSleep	延迟等待	Delay/wait
`andGuardrail`	andGuardrail	执行防护栏	Execute guardrail
`andTap`	andTap	日志/副作用	Log/side effects

bash pnpm test:all # Run all tests pnpm build:all # Build all packages pnpm lint # Run linting checks

Important Notes for AI Agents

Always check existing patterns before implementing new features
Use the established registry patterns for agent and tool management
Maintain type safety - this is a TypeScript-first codebase
Follow the monorepo structure
Test your changes before committing

11.2 CHANGELOG.md

Package: @voltagent/core

2.0.10

Patch Changes

#934 
  Thanks @contributor!
  
  feat: Feature description with code examples

typescript // Example code const result = await agent.generate();

十二、快速开始 / Quick Start

12.1 安装 / Installation

创建新项目
npm create voltagent-app@latest

或手动安装
npm install @voltagent/core
12.2 开发流程 / Development Flow

bash
1. 克隆项目
git clone https://github.com/VoltAgent/voltagent.git
cd voltagent

2. 安装依赖
pnpm install

3. 开发
pnpm dev

4. 测试
pnpm test:all

5. 构建
pnpm build:all

6. 代码检查
pnpm lint
pnpm lint:fix

十三、学习总结 / Learning Summary

13.1 核心突破 / Core Breakthroughs

TypeScript 原生设计 - 完整的类型安全，从工具到工作流的端到端类型推导

模块化架构 - Agent、Memory、Tool、Workflow 等模块清晰分离，便于扩展

VoltOps Console 集成 - 提供生产级别的可观测性和运维能力

MCP 原生支持 - 与 Model Context Protocol 无缝集成

13.2 应用价值 / Application Value

场景	Scenario	适用性	Suitability
智能客服	Customer Service	⭐⭐⭐⭐⭐	非常适合
内容生成	Content Generation	⭐⭐⭐⭐⭐	非常适合
工作流自动化	Workflow Automation	⭐⭐⭐⭐⭐	非常适合
数据分析代理	Data Analysis Agents	⭐⭐⭐⭐	适合
多代理协作	Multi-Agent Collaboration	⭐⭐⭐⭐	适合

13.3 未来展望 / Future Outlook

继续完善 MCP 生态集成

增强多代理协作能力

扩展云端部署和托管能力

优化性能和资源消耗

参考资源 / References

官方文档: https://voltagent.dev/docs/

GitHub: https://github.com/VoltAgent/voltagent

示例代码: https://github.com/VoltAgent/voltagent/tree/main/examples

Discord: https://s.voltagent.dev/discord

npm: https://www.npmjs.com/package/@voltagent/core

本笔记由 AI 学习助手生成 | Generated by AI Learning Assistant

如需更新，请参考官方文档最新版本 | For updates, refer to the latest official documentation