VoltAgent

一句话定位

一个开源 TypeScript AI Agent 工程平台：以 @voltagent/core 为内核，把 Agent、Tool(Zod)、Memory、RAG、Workflow、Guardrails、Voice、MCP/A2A 都建在 Vercel AI SDK (ai@6) 之上，全栈原生基于 OpenTelemetry 做 LLM 可观测——任何执行都生成 span/trace，配套自托管/云的 VoltOps Console 做实时追踪、评估与运维。卖点是”全代码可控的 agent + 生产级可见性”。

设计理念 / 顶层架构

VoltAgent 不自己造推理循环，而是当 Vercel AI SDK 的”工程化外壳”：Agent 把 generateText/streamText/generateObject/streamObject 包起来，注入 system prompt、tools、memory、guardrails、middleware、subagent、hooks 与 OpenTelemetry trace context，对外暴露统一的、可观测的 agent 运行时。设计取舍：

• 建在 AI SDK 之上而非重造：model: openai("gpt-4o-mini") 直接是 AI SDK 的 LanguageModel；多步工具循环交给 AI SDK 的 stopWhen: stepCountIs(maxSteps)（packages/core/src/agent/agent.ts:1383）。VoltAgent 只在外层加 span、guardrail、middleware、memory 持久化。
• monorepo + 适配器分包：pnpm/lerna/nx workspace，~40 个包。packages/core 是骨架（agent/tool/memory/observability/workflow/mcp/retriever/voice/eval…），storage/vector/sandbox/provider/server 全部拆成独立适配器包（libsql/postgres/supabase/cloudflare-d1/sandbox-e2b/sandbox-daytona/server-hono/server-elysia/anthropic-ai/google-ai/groq-ai/voice/scorers/evals/langfuse-exporter…）。
• 观测是一等公民：@voltagent/core 直接依赖一整套 @opentelemetry/*；observability 用 3 个自定义 SpanProcessor（WebSocket 实时、LocalStorage 本地存、LazyRemoteExport→OTLP/VoltOps）把每次 agent/tool/workflow 调用变成可检索的 trace（packages/core/src/observability/node/volt-agent-observability.ts:124）。
• 入口 API 双层：new Agent({...}) 定义单个 agent；new VoltAgent({ agents, workflows, server, logger, observability }) 是顶层应用容器，负责注册表、全局 memory/observability、graceful shutdown 与起 HTTP server（packages/core/src/voltagent.ts:33）。

最小示例（取自 README，TypeScript）：

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 { weatherTool } from "./tools";

const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that can check weather",
  model: openai("gpt-4o-mini"),       // 直接是 Vercel AI SDK 的 LanguageModel
  tools: [weatherTool],               // Zod 定义的 createTool
  memory: new Memory({                // 可插拔存储适配器
    storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
  }),
});

// 顶层容器：注册 agent/workflow，起 server，自动接 OpenTelemetry 观测
new VoltAgent({
  agents: { agent },
  server: honoServer(),               // http://localhost:3141，可连 VoltOps Console
  logger: createPinoLogger({ name: "my-agent-app" }),
});

组件实现（横向逐项，无则标 N/A）

设计权衡与特性

• “AI SDK 之上的工程平台” vs 自造内核：与自己实现 ReAct 循环的框架（如 smolagents）不同，VoltAgent 把推理循环完全交给 Vercel AI SDK（stepCountIs），自己专注 span/trace、guardrail、memory、subagent、server。好处是模型/工具调用语义与 AI SDK 完全一致、provider 覆盖广；代价是与 ai@6 强绑定，升级要跟随其 breaking change。
• 可观测性是真正的差异点：不是事后加 logging，而是 @voltagent/core 直接 hard-depend 一整套 @opentelemetry/*，每个 agent/tool/workflow 调用都是 OTel span，三路 processor（实时 WS / 本地存 / OTLP 远端）零配置开箱。这让它天然对接 VoltOps Console 与任意 OTLP 后端（Langfuse exporter 现成），是它相对多数 TS agent 框架最强的卖点。
• 平台 + 框架双形态：开源 framework（本仓库）+ VoltOps Console（云/自托管，做 observability/evals/guardrails/prompt builder/deploy）。框架可独立用，但很多运维能力指向 Console。
• 与 mastra 高度同生态位：同为 TS、同建于 Vercel AI SDK、同有 agent/workflow/memory/RAG/voice/eval 全家桶；差异在 VoltAgent 把 OpenTelemetry 观测做成内核一等公民并配 VoltOps，Mastra 则更偏 workflow-graph 与自带 playground。
• PlanAgent 是 Claude-Code 风格的彩蛋：planagent/ 提供 write_todos 规划 + 内存文件系统 + 通用子 agent + 工具结果驱逐(context 控制)，启用 workspace 时默认 maxSteps 直接拉到 100，面向”长程多步自治任务”。
• 坑/注意：①LICENSE 文件名为 LICENCE(英式拼写)，内容确为 MIT（README/各 package.json 一致）；②peerDependencies 要求 ai@^6 与 zod ^3.25||^4，与旧版 AI SDK 不兼容；③observability 默认会尝试连 VoltOps（serverless 下自动从 VoltOpsClient 推导 OTLP endpoint），离线/隐私场景需显式配置或关闭远端导出。

关联

• component-taxonomy · observability-eval · multi-agent-orchestration · model-abstraction
• 同生态位(TS + Vercel AI SDK 全家桶)：mastra · 源码：agents-example/voltagent/