跳到主要内容

数据截至 (上游 commit 35efe178d76b)

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:1013),它周围挂着六大子系统。箭头 = "持有/使用"。

                        你的 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/VoltOpsvoltagent.ts:33 VoltAgent
AgentRegistry全局单例,存所有 agent 与全局默认(memory/observability/VoltOps)registries/agent-registry.ts:19 AgentRegistry
Agent 核心一次生成的全部逻辑:组装提示、调模型、跑工具循环、落记忆agent/agent.ts:1013 Agent
Tool / MCP把 Zod 类型化工具与 MCP 外部工具暴露给模型tool/index.ts:347 createTool,mcp/registry/index.ts:43 MCPConfiguration
Memory对话历史的缓冲 + 持久化 + 工作记忆 + 语义检索memory/index.ts:76 Memory
SubAgent / Supervisor主管把任务委派给专门子 agentagent/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 章。

顺序章节一句话
101-agent-runtime.md一次 streamText/generateText 的完整生命周期:上下文、提示组装、多步工具循环、重试/降级、落记忆
202-tools-and-mcp.md工具系统与 MCP:createTool 的 Zod 类型化定义、生命周期钩子/取消、MCPConfiguration 接入外部工具服务器
303-memory.md记忆子系统:ConversationBuffer 短期缓冲、存储适配器持久化、工作记忆(working memory)、语义检索(RAG)
404-subagents-supervisor.md子代理与 Supervisor:SubAgentManager 把子 agent 包成工具、任务委派、bail 提前终止、流事件透传
505-workflow-engine.mdWorkflow 引擎:createWorkflowChain 声明式链、.andThen 步骤、suspend/resume 人在环路
606-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.tsVoltAgent(:33)、constructor(:58)、registerAgents(:569)、startServer(:580)、shutdown(:728)
Agent 核心agent/agent.tsAgent(:1011)、constructor(:1068)、generateText(:1198)、streamText(:1729)、generateObject(:2848)、streamObject(:3188)
生成前置组装agent/agent.tsprepareExecution(:3760)、getSystemMessage(:5299)、prepareTools(:6299)、createStepHandler(:7390)
对话缓冲agent/conversation-buffer.tsConversationBuffer(:62)
Agent 注册表registries/agent-registry.tsAgentRegistry(:19)
工具定义tool/index.tsTool(:198)、createTool(:311)
工具管理tool/manager/ToolManager.tsToolManager(:10);工具路由 tool/routing/
MCP 客户端/配置mcp/client/index.ts、mcp/registry/index.tsMCPClient(:46)、MCPConfiguration(:43)
记忆主类memory/index.tsMemory(:76);适配器 memory/adapters/
记忆管理memory/manager/memory-manager.tsMemoryManager(:28)
子代理agent/subagent/index.tsSubAgentManager(:55)
Workflow 链workflow/chain.tscreateWorkflowChain(:1089)、WorkflowChain(:111)
Workflow 注册/暂停workflow/registry.ts、workflow/suspend-controller.tsWorkflowRegistry(:42)
护栏agent/guardrail.ts、agent/guardrails/defaults.tsInputGuardrail / OutputGuardrail 类型族
可观测性observability/index.tscreateVoltAgentObservability(:23)
VoltOps 客户端voltops/client.tsVoltOpsClient(:75);Prompt voltops/prompt-manager.ts
快速开始 / 组装示例README.md(克隆根)create-voltagent-app 段、src/index.ts 示例(:87-127)

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