# VoltAgent: features, protocols, quickstart

## TL;DR

VoltAgent is an MIT-licensed TypeScript agent framework maintained by the VoltAgent team, with supervisor and sub-agent teams, a chained workflow engine, pluggable memory and MCP support. Its separate VoltOps Console sells tracing, evals and deployment on free and paid plans. It suits TypeScript developers who want agents served from their own HTTP server.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | TypeScript |
| License | MIT |
| Pricing model | [Open core](https://voltagent.dev/pricing/) |
| Orchestration pattern | Supervisor |
| GitHub stars | 10,705 (as of 2026-10-01) |
| GitHub forks | 1,151 |
| Last push | 2026-09-28 |
| Latest release | @voltagent/core@2.11.0 |
| Repository | [VoltAgent/voltagent](https://github.com/VoltAgent/voltagent) |
| Website | [voltagent.dev](https://voltagent.dev) |
| Documentation | [voltagent.dev](https://voltagent.dev/docs/) |
| Last verified | 2026-09-30 |

## Key features

- `Agent` class with instructions, tools, memory and a model given either as a provider object or a `provider/model` string, called through `generateText()` / `streamText()`. ([source](https://voltagent.dev/docs/agents/overview/))
- Supervisor agents: listing `subAgents` adds a `delegate_task` tool that can target one or several sub-agents in one call; `onHandoffComplete` can `bail()` to return a sub-agent's answer directly. ([source](https://voltagent.dev/docs/agents/sub-agents/))
- `createWorkflowChain()` workflows with steps such as `andThen`, `andAgent`, `andAll`, `andRace`, `andWhen` and `andForEach`. ([source](https://voltagent.dev/docs/workflows/overview/))
- Workflow `suspend()` / resume with typed resume schemas, restart from the last persisted checkpoint, and replay from a chosen step. ([source](https://voltagent.dev/docs/workflows/suspend-resume/))
- `Memory` with storage adapters (in-memory, LibSQL, Postgres, Supabase, Cloudflare D1 or VoltOps-hosted), plus optional semantic search and working memory. ([source](https://voltagent.dev/docs/agents/memory/overview/))
- Per-tool `needsApproval` (boolean or function) that stops execution until a user approves or denies the call. ([source](https://voltagent.dev/docs/agents/tools/))
- MCP client (`MCPConfiguration`) over stdio, streamable HTTP or SSE, and `@voltagent/mcp-server` to expose agents, tools and prompts. ([source](https://voltagent.dev/docs/agents/mcp/))
- `@voltagent/a2a-server` publishes agents as A2A endpoints with an agent card and JSON-RPC methods. ([source](https://voltagent.dev/docs/agents/a2a/a2a-server/))

## Architecture and orchestration pattern

Pattern: Supervisor.

A VoltAgent application registers agents and workflows on a `VoltAgent` instance, which serves them over HTTP through a server adapter such as `@voltagent/server-hono`. Agents run on the Vercel AI SDK; `@voltagent/core` 2.x declares `ai` 6.x as a peer dependency. Each agent is a model plus instructions, tools and optional memory.

Multi-agent coordination uses a supervisor. When an agent has `subAgents`, the framework adds a `delegate_task` tool and lists the sub-agents in the supervisor's system prompt. The supervisor's model picks the targets, the sub-agents run the task with their own tools, and results come back as an array for the supervisor to combine. Sub-agents can be supervisors themselves. Delegated messages are tagged so the supervisor's memory reads can leave them out.

Workflows are a separate, explicit path: a typed chain of steps that can call agents, branch, run in parallel or race, and pause with `suspend()`. Execution state is stored through a `Memory` adapter, which is what allows restart and replay. Conversation memory is keyed by user and conversation ID and defaults to an in-memory adapter unless LibSQL, Postgres or another adapter is configured.

### Human in the loop

A tool created with `needsApproval: true`, or with a function that decides per call, is not executed when the model calls it. The agent returns a tool part in the `approval-requested` state; the application shows it to a user and sends back an approval or denial, for example through the AI SDK `useChat` helper. Approved tools run on the next step, and a denial is passed to the model. Workspace tool policies can switch approval on for file writes and deletes.

In workflows, a step calls `suspend()` with a reason and optional data, then reads `resumeData` (validated by a `resumeSchema`) when the run is resumed. Runs can also be suspended from outside through a suspend controller, cancelled from the stream handle, or restarted from their last checkpoint. In supervisor setups, the `onHandoffComplete` hook sees each sub-agent result before the supervisor does.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://voltagent.dev/docs/agents/mcp/) | Client: `MCPConfiguration` connects agents to MCP servers over stdio, streamable HTTP or SSE; a separate `@voltagent/mcp-server` package exposes a VoltAgent project as an MCP server. |
| A2A | Yes (checked 2026-09-30) | [link](https://voltagent.dev/docs/agents/a2a/a2a-server/) | Server side only: `@voltagent/a2a-server` serves an agent card at `/.well-known/{serverId}/agent-card.json` and handles `message/send`, `message/stream`, `tasks/get` and `tasks/cancel`; no A2A client for calling remote agents is documented. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://voltagent.dev/docs/ui/copilotkit/) | First-party `@voltagent/ag-ui` package registers VoltAgent agents as an AG-UI endpoint for CopilotKit React components. |

## Best for

- TypeScript services that expose agents and workflows over their own HTTP server ([shortlist](https://multiagentguide.top/best/typescript.md))
- Keeping conversation memory in your own LibSQL or Postgres database ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Supervisor setups that fan a task out to several specialist sub-agents at once
- Workflows that wait for a manager's decision and resume with typed input

## Not for

- Python or JVM codebases; the framework is TypeScript only
- Agents that need to call remote A2A agents, since only the A2A server side is documented
- Projects that cannot move to AI SDK v6 packages, which VoltAgent 2.x expects

## Quickstart

```sh
npm create voltagent-app@latest
```

Install verified 2026-09-30 (temp dir, Node v22.22.3, macOS arm64: local `npm i @voltagent/core` (no -g) ok, `node -e "import('@voltagent/core').then(m=>console.log(typeof m.Agent))"` ok, @voltagent/core 2.11.0. This is the core package from the documented manual setup; the interactive `npm create voltagent-app@latest` scaffolder was not run. Packages came from the registry.npmmirror.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```ts
import { Agent, VoltAgent, createTool } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";
import { z } from "zod";

const refund = createTool({
  name: "issueRefund",
  description: "Refund an order",
  parameters: z.object({ orderId: z.string() }),
  needsApproval: true,
  execute: async ({ orderId }) => ({ ok: true, orderId }),
});
const billing = new Agent({ name: "billing", purpose: "Handles refunds and invoices",
  instructions: "Resolve billing requests.", model: "openai/gpt-4o-mini", tools: [refund] });
const triage = new Agent({ name: "triage", instructions: "Route requests to specialists.",
  model: "openai/gpt-4o-mini", subAgents: [billing] });

new VoltAgent({ agents: { triage, billing }, server: honoServer() });
```

### Common pitfalls

- The quick start asks for Node.js 20.19 or newer so the generated tsdown build resolves ESM correctly.
- A provider key such as `OPENAI_API_KEY` must be in `.env` if it was skipped during `create-voltagent-app`.
- 2.x aligns with AI SDK v6: upgrade `ai` to ^6 and `@ai-sdk/*` providers to ^3 alongside `@voltagent/*`; `generateObject` / `streamObject` are deprecated in favour of `generateText` / `streamText` with structured output.
- Memory defaults to an in-memory adapter, and `A2AServer` keeps tasks in memory unless you supply a task store.
- The dev server listens on port 3141 by default.

Official quickstart: https://voltagent.dev/docs/quick-start/

## Pros

- One `delegate_task` call can send the same task to several sub-agents, and results come back as a list. ([source](https://voltagent.dev/docs/agents/sub-agents/))
- `onHandoffComplete` with `bail()` can end a supervisor turn with a sub-agent's output, skipping a second supervisor pass. ([source](https://voltagent.dev/docs/agents/sub-agents/))
- Workflows can be restarted from the latest persisted checkpoint after a crash, and replayed from a specific step. ([source](https://voltagent.dev/docs/workflows/suspend-resume/))
- AG-UI support ships as a first-party package, so CopilotKit frontends connect without a community bridge. ([source](https://voltagent.dev/docs/ui/copilotkit/))
- The repository is MIT-licensed as a whole. ([source](https://github.com/VoltAgent/voltagent/blob/main/LICENCE))

## Cons

- The docs label the Workflows API as preview and warn that breaking changes may follow. ([source](https://voltagent.dev/docs/workflows/overview/))
- A2A support is server-side only, and `A2AServer` keeps task state in memory unless you implement a task store. ([source](https://voltagent.dev/docs/agents/a2a/a2a-server/))
- Upgrading to 2.x means moving AI SDK packages to v6 and replacing `generateObject` / `streamObject` calls. ([source](https://voltagent.dev/docs/getting-started/migration-guide/))
- Tracing, evals and deployment live in the separate VoltOps Console; its free Developer plan is limited to 250 traces a month, with paid plans above that. ([source](https://voltagent.dev/pricing/))

## Alternatives

- [Mastra](https://multiagentguide.top/tools/mastra.md) ([VoltAgent vs Mastra](https://multiagentguide.top/compare/mastra-vs-voltagent.md))
- [OpenAI Agents SDK (JavaScript/TypeScript)](https://multiagentguide.top/tools/openai-agents-js.md)
- [LangGraph.js](https://multiagentguide.top/tools/langgraphjs.md)
- [KaibanJS](https://multiagentguide.top/tools/kaibanjs.md)
- [AgentKit by Inngest](https://multiagentguide.top/tools/inngest-agentkit.md)

## FAQ

### Does VoltAgent support MCP?

Yes. `MCPConfiguration` connects agents to MCP servers over stdio, streamable HTTP or SSE, and `@voltagent/mcp-server` exposes a VoltAgent project to MCP clients.

### Is VoltAgent free?

The framework is MIT-licensed. The VoltOps Console for observability, evals and deployment has a free Developer plan, paid plans and an Enterprise option with self-hosted deployment.

### What language is VoltAgent?

TypeScript. The quick start asks for Node.js 20.19 or newer, and version 2.x expects AI SDK v6 packages.

### Does VoltAgent support A2A and AG-UI?

It can serve agents over A2A through `@voltagent/a2a-server`; no A2A client is documented. For AG-UI, the `@voltagent/ag-ui` package connects agents to CopilotKit.

### How do VoltAgent agents work together?

A supervisor agent lists `subAgents` and receives a `delegate_task` tool. Its model decides which sub-agents get a task and then combines their results.

## Sources

- [VoltAgent GitHub repository](https://github.com/VoltAgent/voltagent)
- [VoltAgent README](https://github.com/VoltAgent/voltagent/blob/main/README.md)
- [VoltAgent LICENCE (MIT)](https://github.com/VoltAgent/voltagent/blob/main/LICENCE)
- [VoltAgent releases](https://github.com/VoltAgent/voltagent/releases)
- [@voltagent/core package.json](https://github.com/VoltAgent/voltagent/blob/main/packages/core/package.json)
- [VoltAgent docs](https://voltagent.dev/docs/)
- [Agents overview (docs)](https://voltagent.dev/docs/agents/overview/)
- [Sub-agents (docs)](https://voltagent.dev/docs/agents/sub-agents/)
- [Tools and needsApproval (docs)](https://voltagent.dev/docs/agents/tools/)
- [Workflows overview (docs)](https://voltagent.dev/docs/workflows/overview/)
- [Workflow suspend, resume and cancellation (docs)](https://voltagent.dev/docs/workflows/suspend-resume/)
- [Memory overview (docs)](https://voltagent.dev/docs/agents/memory/overview/)
- [MCP client (docs)](https://voltagent.dev/docs/agents/mcp/)
- [MCP server (docs)](https://voltagent.dev/docs/agents/mcp/mcp-server/)
- [A2A server (docs)](https://voltagent.dev/docs/agents/a2a/a2a-server/)
- [CopilotKit / AG-UI integration (docs)](https://voltagent.dev/docs/ui/copilotkit/)
- [Quick start (docs)](https://voltagent.dev/docs/quick-start/)
- [Migration guide 1.x to 2.x (docs)](https://voltagent.dev/docs/getting-started/migration-guide/)
- [Workspace security and tool policies (docs)](https://voltagent.dev/docs/workspaces/security/)
- [VoltOps pricing](https://voltagent.dev/pricing/)
- [VoltAgent homepage](https://voltagent.dev)

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/voltagent