Skip to content
/
Tier B A6 Multi-agent orchestrator

VoltAgent

voltagent · voltagent/voltagent · ★ 9.2k · last commit 2026-05-25

Primitive shape 1 total
MCP tools 1
00

Summary

VoltAgent — Summary

VoltAgent is a TypeScript/JavaScript AI agent engineering platform (9k+ stars) combining an open-source framework (@voltagent/core v2.7.5) with an optional cloud observability console (VoltOps). The framework is a monorepo of 35+ npm packages covering agents, workflows, memory, RAG, guardrails, voice, MCP, A2A, AG-UI, and server adapters (Hono, Elysia). Agents are defined as typed class instances with Zod-validated tools, lifecycle hooks, memory adapters, guardrails, and model provider bindings; a supervisor/sub-agent pattern allows hierarchical teams. The workflow engine provides declarative multi-step automation without custom control flow. Memory adapters support LibSQL/Turso (persistent SQLite), Postgres, Cloudflare D1, Supabase, and Voltagent's managed service. Guardrails intercept agent input/output at runtime with built-in PII, prompt injection, profanity, and max-length guards. The create-voltagent-app CLI scaffolds new projects in seconds, and VoltOps Console at console.voltagent.dev provides real-time agent monitoring, evals, and prompt management. Compared to the seeds, VoltAgent is closest to claude-flow in scope (TypeScript, npm-package, multi-agent, MCP bundled) but targets web-native TypeScript runtimes (Cloudflare Workers, Deno, Bun, Node) with a first-class cloud ops console.

01

Overview

VoltAgent — Overview

Origin

Built by the VoltAgent team (voltagent_dev on X). First public release in 2025. Positioned as the TypeScript answer to the Python-dominated agent SDK space.

Philosophy

From the README:

"VoltAgent is an end-to-end AI Agent Engineering Platform that consists of two main parts: Open-Source TypeScript Framework — Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow, and more. VoltOps Console — Observability, Automation, Deployment, Evals, Guardrails, Prompts, and more."

"Build agents with full code control and ship them with production-ready visibility and operations."

The dual-track philosophy: keep the framework open-source (so developers have full control), but provide a cloud console for the operational layer. Separation of concerns between agent logic and agent observability.

Design pillars

  1. Typed roles: agents defined with typed roles, tools, memory, model providers
  2. Declarative workflows: multi-step automations without custom control flow
  3. Supervisor + sub-agents: hierarchical teams with routing
  4. Provider-agnostic: Vercel AI SDK underpins model calls; swap providers via config
  5. Lifecycle hooks: AgentHooks interface for pre/post tool call events
  6. Guardrails as first-class: InputGuardrail/OutputGuardrail with built-in and composable rules
  7. Resumable streaming: clients reconnect to in-flight streams after refresh

Key quote

"Swap between OpenAI, Anthropic, Google, or other providers by changing config, not rewriting agent logic."

This is the core promise: provider-agnostic architecture via Vercel AI SDK's unified model interface.

VoltOps Console

Cloud-hosted at console.voltagent.dev. Features: agent monitoring, conversation history, tool call trace, eval experiments, guardrail management, prompt versioning. Self-hostable version available.

02

Architecture

VoltAgent — Architecture

Distribution

  • Type: npm-package (monorepo of 35+ packages)
  • Primary package: @voltagent/core v2.7.5
  • Install: npm install @voltagent/core or npm create voltagent-app@latest
  • Required runtime: Node.js ≥ 18 (also Deno, Bun, Cloudflare Workers)
  • License: MIT

Monorepo packages

Package Purpose
@voltagent/core Agent class, routing, state, scheduling, MCP, tools, workflows
@cloudflare/ai-chat Persistent messages, resumable streaming
@cloudflare/think Opinionated chat agent base with agentic loop
@voltagent/libsql LibSQL/Turso memory adapter
@voltagent/postgres PostgreSQL memory adapter
@voltagent/rag RAG pipeline
@voltagent/voice STT/TTS/VAD pipeline
@voltagent/evals Evaluation harness
@voltagent/logger Pino-based logging
@voltagent/server-hono Hono HTTP server adapter
@voltagent/docs-mcp MCP docs server
@voltagent/sdk Client SDK
create-voltagent-app Project scaffolding CLI
@voltagent/anthropic-ai Anthropic provider adapter
@voltagent/google-ai Google provider adapter
@voltagent/groq-ai Groq provider adapter
@voltagent/langfuse-exporter Langfuse observability exporter
@voltagent/vercel-ai-exporter Vercel AI SDK exporter
@voltagent/sandbox-e2b E2B sandbox integration
@voltagent/sandbox-daytona Daytona sandbox integration

Build system

pnpm workspace + Nx + Lerna + Biome (linting/formatting).

Key TypeScript types (from packages/core/src/agent/index.ts)

Agent           // Main agent class
AgentHooks      // Lifecycle hook interface
InputGuardrail  // Input safety gate
OutputGuardrail // Output safety gate
GuardrailContext
WorkflowCallback

Default server port

3141 (from README startup message)

Target runtimes

Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge

03

Components

VoltAgent — Components

CLI tools

Name Purpose
create-voltagent-app Interactive project scaffolding CLI
@voltagent/docs-mcp MCP server exposing VoltAgent docs to AI coding assistants

Core framework classes

Name Module Purpose
Agent @voltagent/core Single agent definition: model, tools, memory, guardrails, hooks
VoltAgent @voltagent/core Application container: registers agents, workflows, server
Memory @voltagent/core Memory manager with pluggable storage adapters
AgentHooks @voltagent/core Lifecycle hook interface (pre/post tool call)
InputGuardrail @voltagent/core Input safety gate with action + severity
OutputGuardrail @voltagent/core Output safety gate
GuardrailContext @voltagent/core Context passed to guardrail functions
WorkflowCallback @voltagent/core Workflow execution callback

Built-in guardrails

Guardrail Purpose
createSensitiveNumberGuardrail Block/redact SSN, credit card numbers
createEmailRedactorGuardrail Redact email addresses
createPhoneNumberGuardrail Block/redact phone numbers
createProfanityGuardrail Block profane output
createMaxLengthGuardrail Enforce max response length
createProfanityInputGuardrail Block profane input
createPIIInputGuardrail Block PII in input
createPromptInjectionGuardrail Block injection attacks
createInputLengthGuardrail Enforce max input length
createHTMLSanitizerInputGuardrail Strip HTML from input
createDefaultInputSafetyGuardrails Composite default input safety
createDefaultPIIGuardrails Composite PII protection
createDefaultSafetyGuardrails Composite safety guardrails

Memory adapters

@voltagent/libsql (SQLite/Turso), @voltagent/postgres, @voltagent/cloudflare-d1, @voltagent/supabase, @voltagent/voltagent-memory (managed).

No shipped MCP servers (except docs)

@voltagent/docs-mcp exposes VoltAgent's own documentation. No general-purpose tool MCP server.

05

Prompts

VoltAgent — Prompts

Agent instructions pattern (from README)

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,
});

Technique: Static string system prompt. instructions maps directly to the LLM system message.

Tool definition with Zod schema

const weatherTool = {
  name: "get_weather",
  description: "Get the current weather for a location",
  parameters: z.object({
    location: z.string().describe("City name"),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  }),
  execute: async ({ location, unit }) => {
    // implementation
  },
};

Technique: Zod schema-driven tool definition. The schema is serialized to JSON Schema for the LLM's tool-use API. .describe() on each field drives the LLM's parameter documentation.

Guardrail prompt (DESIGN.md excerpt, verbatim)

From .claude/ and DESIGN.md in the repo:

Tools use Zod validation + lifecycle hooks. Agents route tasks to sub-agents.
The @callable() decorator marks methods as RPC-accessible from the frontend.

Technique: Code-comment-as-architecture-doc style. The design files serve as prompts for AI coding assistants working on the codebase.

CLAUDE.md / AGENTS.md

VoltAgent ships CLAUDE.md and AGENTS.md at the repo root. These target AI coding assistants (Claude Code, Codex) working on VoltAgent's own codebase — a meta-layer of prompting for framework developers.

09

Uniqueness

VoltAgent — Uniqueness

Differs from seeds

Most similar to claude-flow (both are TypeScript npm monorepos for multi-agent systems with MCP support), but VoltAgent uses the Vercel AI SDK as its model abstraction layer, making it provider-neutral from day one — while claude-flow is deeply Claude-oriented. VoltAgent uniquely ships 13 built-in composable guardrail functions (PII, profanity, injection, HTML sanitizer) with severity levels, which no seed provides. The VoltOps console is a cloud-hosted LLM observability platform analogous to LangSmith but built for VoltAgent specifically. Unlike openspec or taskmaster-ai (cursor-first), VoltAgent is runtime-first (runs as HTTP server) and IDE-agnostic.

Positioning

VoltAgent positions itself as the TypeScript-native LangChain alternative — bringing typed contracts, Zod validation, and provider-agnostic model calls to the Node.js ecosystem with a first-class ops console. The guardrails system is production-grade with composable safety primitives not found in any seed.

Distinctive features

  1. 13 built-in guardrails: typed, composable safety functions with severity levels and action types (block, redact, warn) — unique in this batch
  2. Resumable streaming: clients reconnect to in-flight streams by run ID — no other framework in the batch addresses this
  3. 35+ npm packages: most granular monorepo structure; each capability is separately installable
  4. VoltOps Console: cloud ops dashboard integrated at startup (console link in terminal output)
  5. E2B + Daytona sandboxes: code execution isolation via dedicated adapter packages

Observable failure modes

  1. Cloud console dependency: the "test your agents" link goes to a cloud service; self-hosting requires additional setup
  2. Vercel AI SDK version coupling: @ai-sdk/* packages at ^3.0.0 may have breaking changes that cascade across all 20+ provider adapters
  3. No built-in git automation: no automatic commits, PRs, or worktrees
  4. Memory compaction: not explicitly handled; long conversations may degrade performance
  5. Port 3141: hardcoded default port may conflict with other dev servers
04

Workflow

VoltAgent — Workflow

Quick start

const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
  memory,
});

new VoltAgent({
  agents: { agent },
  workflows: { expenseApprovalWorkflow },
  server: honoServer(),
});
Phase Artifact
1. Define Agent with model + tools + memory Agent object
2. Register in VoltAgent container Running HTTP server on port 3141
3. Client sends request via HTTP or chat interface Agent receives message
4. Agent executes (tool calls, LLM calls) Run events stream
5. Response streamed back Final result

Supervisor + sub-agents

const supervisor = new Agent({
  name: "supervisor",
  subAgents: [specialistA, specialistB],
  model: openai("gpt-4o"),
});

Supervisor routes tasks to appropriate sub-agents based on capability.

Workflow (declarative)

const expenseApprovalWorkflow = workflow({
  steps: [
    extractExpenseData,
    validatePolicy,
    requireApproval,  // human-in-the-loop gate
    processPayment,
  ]
});
Phase Artifact
1. Define workflow with step sequence Workflow definition
2. Register workflow in VoltAgent Active workflow
3. Trigger workflow Workflow run
4. Steps execute sequentially with durable state Step results

Approval gates

  1. Human-in-the-loop via workflow requireApproval step (pauses and waits for confirmation)
  2. Guardrail violations can block execution

Resumable streaming

If client disconnects, reconnecting to the same run ID resumes the stream from where it was interrupted.

06

Memory Context

VoltAgent — Memory & Context

Memory architecture

const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

const agent = new Agent({ ..., memory });

Memory is a pluggable adapter system. The Memory class wraps any StorageAdapter.

Storage adapters

Adapter Backend Persistence
Default In-memory Session only
LibSQLMemoryAdapter SQLite (file or Turso cloud) Project
PostgresMemoryAdapter PostgreSQL Global
CloudflareD1Adapter Cloudflare D1 Global
SupabaseAdapter Supabase PostgreSQL Global
VoltAgent managed Cloud API Global

Default state file

.voltagent/memory.db (LibSQL SQLite, per-project).

Context injection

Memory is automatically injected into each agent run's message history. The agent receives recent conversation turns as context. Memory size limits are handled by the adapter.

Cross-session handoff

Yes — LibSQL adapter persists across process restarts. Session ID is stable; reconnecting to the same agent instance reloads history.

Resumable streaming state

Separate from memory: in-flight stream state is stored in the agent's runtime. Clients reconnect by stream ID and receive buffered events.

Workflow durable state

Workflow step results are persisted so that if a step fails and is retried, earlier step outputs are not re-computed.

07

Orchestration

VoltAgent — Orchestration

Multi-agent

Yes. Supervisor + sub-agents pattern; the supervisor routes tasks to sub-agents and synthesizes results.

Orchestration pattern

hierarchical — supervisor coordinates sub-agents. Workflow engine supports sequential steps with parallel fan-out within a step.

Max concurrent agents

Unknown (limited by Node.js event loop and provider rate limits).

Isolation mechanism

None in the core framework. @voltagent/sandbox-e2b and @voltagent/sandbox-daytona provide E2B and Daytona sandbox adapters for isolated code execution.

Multi-model

Yes. Agents can have different model providers:

const plannerAgent = new Agent({ model: openai("gpt-4o") });
const executorAgent = new Agent({ model: anthropic("claude-haiku-4-5") });

No predefined role mapping; user assigns models per agent.

Execution mode

interactive-loop — VoltAgent runs as an HTTP server; each request triggers an agent run.

Crash recovery

Workflow step results are durable; failed steps can be retried without re-executing earlier steps.

Context compaction

Not explicitly documented. Memory adapters handle storage limits but no explicit compaction strategy in the README.

Consensus

None.

Prompt chaining

Yes — workflow steps form an explicit chain: each step's output is passed to the next step's input.

Streaming output

Yes — EventEmitter-based event stream with VoltOps console integration. ResumableStreamingAdapter allows clients to reconnect.

MCP integration

Agents connect as MCP clients. @voltagent/core includes @modelcontextprotocol/sdk as a dependency. @voltagent/docs-mcp exposes VoltAgent docs as an MCP server.

08

Ui Cli Surface

VoltAgent — UI & CLI Surface

CLI binary

create-voltagent-app — project scaffolding CLI.

npm create voltagent-app@latest

Interactive setup: project name, model provider selection, feature selection (memory, workflows, etc.).

Local developer server

VoltAgent starts an HTTP server on port 3141 by default. The terminal output shows:

══════════════════════════════════════════════════
VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
✓ HTTP Server: http://localhost:3141
Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════

VoltOps Console (cloud)

URL: console.voltagent.dev Type: cloud web dashboard (self-hostable) Features:

  • Real-time agent monitoring
  • Conversation history + replay
  • Tool call trace view
  • Eval experiments
  • Guardrail management
  • Prompt versioning
  • Agent registry

IDE integration

  • CLAUDE.md — instructions for Claude Code working on VoltAgent codebase
  • AGENTS.md — instructions for Codex/OpenAI agents
  • .cursor/ — Cursor IDE settings
  • @voltagent/docs-mcp — MCP server exposing VoltAgent docs to Claude Code, Cursor, Windsurf

Observability

  • OpenTelemetry: @voltagent/langfuse-exporter, @voltagent/vercel-ai-exporter
  • VoltOps: cloud-native tracing and evals
  • Pino logging: @voltagent/logger

Voice interface

@voltagent/voice package provides STT, TTS, VAD, streaming, SFU utilities. Compatible with OpenAI TTS/STT and ElevenLabs.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…