VoltAgent — 这是什么 · 全景 · 阅读地图

30 秒导读: VoltAgent 是一个 TypeScript 的 AI Agent 工程平台。它让你用代码(而非低代码画布)完整地定义一个带记忆、工具、子代理、工作流的 agent,连接任意大模型,然后把它当成一个普通 Node/Serverless 服务跑起来——外加一个叫 VoltOps Console 的配套控制台做追踪、调试和运维。本章只讲"它是什么、大盘怎么转、该按什么顺序读后面六章",不钻代码细节。

1. 这是什么(零基础也能懂)

一句话定义: VoltAgent = 一个开源 TypeScript 框架(@voltagent/core 及一圈周边包)+ 一个云端/自托管的观测运维台(VoltOps Console)。你用它写代码搭 AI agent,而不是拖拽。

解决什么问题 / 给谁用。 假设你是一名 TypeScript 工程师,想做一个"会聊天、会查天气、会记住用户、必要时把活派给专门的子 agent、还能跑多步审批流程"的 AI 助手,并且要能在生产里看到它每一步在干嘛。裸调用大模型 SDK 你得自己拼:系统提示怎么组装、对话历史存哪、工具怎么暴露给模型、多个 agent 怎么协作、出错怎么重试、每一步怎么上报追踪。VoltAgent 把这些都做成了标准部件,你只管声明。

它能做什么(功能清单):

能力	一句话
Agent 核心	用一处配置定义角色/指令/模型/工具/记忆
工具 + MCP	给模型装 Zod 类型化的"手脚",或接入 Model Context Protocol 外部工具服务器
记忆	短期对话缓冲 + 可持久化(LibSQL/Postgres/Supabase…)+ 工作记忆 + 语义检索
子代理 / Supervisor	一个主管 agent 把子任务委派给专门的子 agent
Workflow 引擎	声明式多步编排,支持人在环路的 suspend/resume
护栏 Guardrail	运行时拦截、校验、改写输入/输出
可观测性	内置 OpenTelemetry,一切执行成为可追踪的 span
模型无关	换 provider 只改 config(OpenAI / Anthropic / Google / Groq…)

用起来什么样。 一条命令起项目,然后 src/index.ts 就是"组装现场"——new Agent({...}) 定义一个 agent,new VoltAgent({...}) 把它挂上服务器跑起来:

npm create voltagent-app@latest   # 脚手架,来自 packages/create-voltagent-app
npm run dev                        # tsx 编译并启动,默认 http://localhost:3141

// 示意,源自 README.md 快速开始;真实入口是你项目里的 src/index.ts
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "./tools";

// 1) 可选的持久化记忆(不给就用内存)
const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

// 2) 定义一个 agent:名字、指令、模型、工具、记忆全在一处
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that can check weather",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
  memory,
});

// 3) 交给 VoltAgent 编排器,挂上 HTTP 服务器,自动启动
new VoltAgent({
  agents: { agent },
  server: honoServer(),
});

一句话直觉 / 类比。 把 Agent 想成"一个岗位说明书 + 一个大脑接口"——指令是岗位职责,model 是接哪颗大脑,tools/memory/subAgents 是发给它的工具箱、笔记本、和可以打电话求助的同事。而 VoltAgent 类是"办公室经理":它把所有岗位登记造册、拉起前台(HTTP 服务器)、接上监控摄像头(observability),让整个团队能对外接活。

本节到此为止,不出现底层实现;想知道"一次生成到底怎么跑"看 01-agent-runtime.md。

2. 顶层全景(它大概怎么转)

2.1 两层结构:框架 + 控制台

VoltAgent 官方定位是"端到端 AI Agent 工程平台",分两块(README.md:39-44):

开源框架(本参考主要解剖的对象)——跑在你自己进程里的 TypeScript 库,负责 agent 的一切运行逻辑。
VoltOps Console——独立的云端/自托管控制台,负责观测、追踪、Prompt 管理、评测、部署。框架通过 VoltOpsClient(packages/core/src/voltops/client.ts:75)与它对话。

本章之后的六章讲的都是框架内部;VoltOps 只在第 6 章作为"生产化那一层"出现。

2.2 顶层图:编排器持有什么,Agent 挂着什么

怎么读这张图:上半部是 VoltAgent 编排器(packages/core/src/voltagent.ts:33),它只做"登记 + 拉起服务 + 装监控";真正干活的是下半部的 Agent 核心(packages/core/src/agent/agent.ts:1011),它周围挂着六大子系统。箭头 = "持有/使用"。

                        你的 src/index.ts
                     new VoltAgent({ agents, workflows, server, ... })
                                  │
        ┌─────────────────────────▼──────────────────────────┐
        │            VoltAgent 编排器 (voltagent.ts)           │
        │  · AgentRegistry      (登记所有 agent)              │
        │  · WorkflowRegistry   (登记所有 workflow)           │
        │  · observability      (全局 OpenTelemetry provider) │
        │  · VoltOpsClient      (连 VoltOps 控制台,可选)     │
        │  · server provider    (Hono/Elysia HTTP,可选)      │
        │  · MCP / A2A / Trigger 注册表                        │
        └─────────────────────────┬──────────────────────────┘
                                   │ 登记 & 提供全局默认
                                   ▼
        ┌───────────────────────────────────────────────────┐
        │                Agent 核心 (agent.ts)               │
        │   generateText / streamText / generateObject …     │
        └───────────────────────────────────────────────────┘
             │       │        │         │         │        │
        ┌────▼──┐ ┌──▼───┐ ┌──▼────┐ ┌──▼─────┐ ┌─▼─────┐ ┌▼──────────┐
        │ Tool  │ │Memory│ │SubAgent│ │Workflow│ │Guard- │ │Observa-   │
        │ + MCP │ │      │ │Super-  │ │(旁挂于 │ │rail   │ │bility     │
        │       │ │      │ │visor   │ │编排器) │ │       │ │(贯穿全程) │
        └───┬───┘ └──┬───┘ └───┬────┘ └────────┘ └───────┘ └───────────┘
            │        │         │
            ▼        ▼         ▼
        大模型     存储适配器   其它 Agent
       (AI SDK)  (LibSQL 等)  (委派任务)

2.3 部件一句话职责

部件	干什么	在哪(文件:符号)
VoltAgent 编排器	登记 agent/workflow、拉起服务器、装全局 observability/VoltOps	`voltagent.ts:33` `VoltAgent`
AgentRegistry	全局单例,存所有 agent 与全局默认(memory/observability/VoltOps)	`registries/agent-registry.ts:19` `AgentRegistry`
Agent 核心	一次生成的全部逻辑:组装提示、调模型、跑工具循环、落记忆	`agent/agent.ts:1011` `Agent`
Tool / MCP	把 Zod 类型化工具与 MCP 外部工具暴露给模型	`tool/index.ts:311` `createTool`,`mcp/registry/index.ts:43` `MCPConfiguration`
Memory	对话历史的缓冲 + 持久化 + 工作记忆 + 语义检索	`memory/index.ts:76` `Memory`
SubAgent / Supervisor	主管把任务委派给专门子 agent	`agent/subagent/index.ts:55` `SubAgentManager`
Workflow	声明式多步流程,支持暂停/恢复	`workflow/chain.ts:1089` `createWorkflowChain`,`workflow/registry.ts:42` `WorkflowRegistry`
Guardrail	运行时校验/改写输入输出	`agent/guardrail.ts`(`InputGuardrail`/`OutputGuardrail`)
Observability	全程 OpenTelemetry 追踪	`observability/index.ts:23` `createVoltAgentObservability`
VoltOpsClient	与 VoltOps 控制台通信(追踪上报、远端 Prompt)	`voltops/client.ts:75` `VoltOpsClient`

2.4 编排器构造时到底做了什么

VoltAgent 的构造函数是一条"登记 + 拉起"流水线(voltagent.ts:58-276),关键几步:

拿到三个全局单例注册表:AgentRegistry / WorkflowRegistry / TriggerRegistry(voltagent.ts:59-61)。
把你传的 memory/observability/voltOpsClient 设为全局默认,好让每个 agent 不用各自重复配(voltagent.ts:69-124)。
同步登记所有 agent,这样构造完立刻能 getAgent()(voltagent.ts:134 registerAgents)。
在 finalizeInit() 里登记 workflow/trigger、用 options.server(...) 工厂造出服务器实例、并自动 startServer()(voltagent.ts:136-211)。
全过程用一个 ready Promise 包住;失败不崩,标 degraded 并记 initError(voltagent.ts:214-275)——生产友好。

一句话:编排器本身不"思考",它只是把部件接线、把前台开起来。 思考发生在 Agent。

2.5 主线走一遍(高层,不进代码)

追一次 agent.streamText("今天北京天气?") 从输入到输出,高层经过这些部件(细节见 01-agent-runtime.md):

输入 string/messages
   │
   ▼
① 建 OperationContext + 根 span        ← Observability 开始记账
   │
   ▼
② 输入 Middleware → 输入 Guardrail      ← 可拦截/改写/放行
   │
   ▼
③ prepareExecution:                     (agent.ts:3760)
     · getSystemMessage 组装系统提示     ← 指令(可动态/远端 Prompt)+ 记忆
     · 从 Memory 拉对话历史进缓冲
     · prepareTools 把工具+MCP+子代理工具交给模型
   │
   ▼
④ 调 AI SDK streamText({model,messages,tools,...})   (agent.ts:2041)
     └─ 多步循环:模型要调工具 → 执行 → onStepFinish → 回灌 → 再问模型
   │
   ▼
⑤ 输出 Guardrail → onFinish            ← 校验最终输出
   │
   ▼
⑥ 把新对话写回 Memory,结束 span        ← 持久化 + 追踪落账
   │
   ▼
输出:文本流 / 结构化对象 + fullStream(含工具事件)

其中 ③④ 是核心;子代理其实是"一种特殊工具"——主管把子 agent 包装成工具交给模型调用(见 04-subagents-supervisor.md)。Workflow 则是另一条入口:它不经过单次 streamText,而是由 WorkflowRegistry 驱动多步执行,步与步之间可 suspend/resume(见 05-workflow-engine.md)。

3. 阅读地图(六章,建议顺序)

后面六章由浅入深。若你只想读一章:想懂"一次生成"读第 1 章;想加工具读第 2 章;想让 agent 有记性读第 3 章;想搭多 agent 读第 4 章;想做流程编排读第 5 章;想上生产读第 6 章。

顺序	章节	一句话
1	01-agent-runtime.md	一次 `streamText`/`generateText` 的完整生命周期:上下文、提示组装、多步工具循环、重试/降级、落记忆
2	02-tools-and-mcp.md	工具系统与 MCP:`createTool` 的 Zod 类型化定义、生命周期钩子/取消、`MCPConfiguration` 接入外部工具服务器
3	03-memory.md	记忆子系统:`ConversationBuffer` 短期缓冲、存储适配器持久化、工作记忆(working memory)、语义检索(RAG)
4	04-subagents-supervisor.md	子代理与 Supervisor:`SubAgentManager` 把子 agent 包成工具、任务委派、bail 提前终止、流事件透传
5	05-workflow-engine.md	Workflow 引擎:`createWorkflowChain` 声明式链、`.andThen` 步骤、`suspend/resume` 人在环路
6	06-observability-guardrails-voltops.md	生产化那层:OpenTelemetry 追踪、Guardrail 护栏、VoltOps Console 与 `VoltOpsClient`

4. 巧妙之处清单(每条链到对应章)

这些是读完能带走的设计精华,细节各归各章:

子代理即工具。 多 agent 协作不另造机制,而是把子 agent 包装成一个"可被模型调用的工具",复用同一套工具循环。省掉一整套编排代码 → 04。
单一全局 observability provider。 整个应用只有一个 OpenTelemetry provider,由编排器建好放进 AgentRegistry,所有 agent/workflow 共用,trace 自然串成一棵树 → 06、voltagent.ts:114-124。
模型调用零 maxRetries、自己接管重试/降级。 交给 AI SDK 时强制 maxRetries: 0(agent.ts:2051),把重试、模型 fallback、有无输出的恢复判断全握在自己手里,才能精确打点与埋 span。→ 01。
中间件/护栏可重试且可推测执行。 输入侧支持 middleware 重试循环与"推测式"输入护栏(streamText 里的 speculativeInputGuardrail),在不牺牲流式延迟的前提下做校验 → 06。
构造不崩:ready + degraded。 初始化失败不抛死进程,而是标记降级并聚合错误(voltagent.ts:214-275),生产环境友好 → 本章 §2.4。
全局默认下沉。 memory/observability/voltOpsClient 在编排器一处设,自动灌给每个 agent(voltagent.ts:511-564),避免重复配置。
Workflow 的 suspend/resume。 步骤里 await suspend(...) 能把整条流程冻结,等外部(如经理审批)带 resumeData 回来再续跑 → 05、README.md:163-231。

5. 全库代码地图总表(主题 | 文件 | 符号)

一张跳转表:知道要看哪块时,用符号名 grep 比行号更抗漂移。路径相对克隆根 packages/core/src/(标注了包名的除外)。

主题	文件	关键符号
编排器主类	`voltagent.ts`	`VoltAgent`(:33)、`constructor`(:58)、`registerAgents`(:569)、`startServer`(:580)、`shutdown`(:728)
Agent 核心	`agent/agent.ts`	`Agent`(:1011)、`constructor`(:1068)、`generateText`(:1198)、`streamText`(:1729)、`generateObject`(:2848)、`streamObject`(:3188)
生成前置组装	`agent/agent.ts`	`prepareExecution`(:3760)、`getSystemMessage`(:5299)、`prepareTools`(:6299)、`createStepHandler`(:7390)
对话缓冲	`agent/conversation-buffer.ts`	`ConversationBuffer`(:62)
Agent 注册表	`registries/agent-registry.ts`	`AgentRegistry`(:19)
工具定义	`tool/index.ts`	`Tool`(:198)、`createTool`(:311)
工具管理	`tool/manager/ToolManager.ts`	`ToolManager`(:10);工具路由 `tool/routing/`
MCP 客户端/配置	`mcp/client/index.ts`、`mcp/registry/index.ts`	`MCPClient`(:46)、`MCPConfiguration`(:43)
记忆主类	`memory/index.ts`	`Memory`(:76);适配器 `memory/adapters/`
记忆管理	`memory/manager/memory-manager.ts`	`MemoryManager`(:28)
子代理	`agent/subagent/index.ts`	`SubAgentManager`(:55)
Workflow 链	`workflow/chain.ts`	`createWorkflowChain`(:1089)、`WorkflowChain`(:111)
Workflow 注册/暂停	`workflow/registry.ts`、`workflow/suspend-controller.ts`	`WorkflowRegistry`(:42)
护栏	`agent/guardrail.ts`、`agent/guardrails/defaults.ts`	`InputGuardrail` / `OutputGuardrail` 类型族
可观测性	`observability/index.ts`	`createVoltAgentObservability`(:23)
VoltOps 客户端	`voltops/client.ts`	`VoltOpsClient`(:75);Prompt `voltops/prompt-manager.ts`
快速开始 / 组装示例	`README.md`(克隆根)	`create-voltagent-app` 段、`src/index.ts` 示例(:87-127)

本章是全景与路由,刻意只讲"大盘",不钻任一机制的实现细节。每个子系统的真章在对应分章里,均带 file:line + 符号名的真源码引用。

1. 这是什么(零基础也能懂)​

2. 顶层全景(它大概怎么转)​

2.1 两层结构:框架 + 控制台​

2.2 顶层图:编排器持有什么,Agent 挂着什么​

2.3 部件一句话职责​

2.4 编排器构造时到底做了什么​

2.5 主线走一遍(高层,不进代码)​

3. 阅读地图(六章,建议顺序)​

4. 巧妙之处清单(每条链到对应章)​

5. 全库代码地图总表(主题 | 文件 | 符号)​