Guide · Open source

How to use VoltAgent: install, run your first agent and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

VoltAgent is an open-source TypeScript framework for building AI agents, which are programs that use language models to carry out multi-step tasks with tools and memory. It is paired with the VoltOps Console for observability, deployment and evals. This guide shows you how to create a project, run your first agent and find your way around the main features.

VoltAgentVoltAgent/voltagent · ★ 10.9k · MIT Install options & downloads

Quick start

1Check prerequisites. Install Node.js and npm on your computer.
2Create a project. Run npm create voltagent-app@latest and follow the prompts.
3Open the starter code. Read src/index.ts to see how the agent and VoltAgent instance are defined.
4Start the dev server. Run npm run dev from the project folder and wait for the startup message.
5Open the console. Click the VoltOps Console link in the terminal to view your agent.
6Change the agent. Edit the instructions, model or tools in your code and restart the dev server.

What you need before you install VoltAgent

VoltAgent is a TypeScript framework, so you need to be comfortable writing code. The setup is handled with the npm package manager, which means Node.js and npm must be installed on your machine.

Node.js
npm
Basic familiarity with TypeScript

Create a new VoltAgent project

The fastest way to start is the create-voltagent-app CLI. It guides you through setup and creates a starter project.

npm create voltagent-app@latest

Understand the starter code

The starter code lives in src/index.ts and registers an agent and a workflow example found in src/workflows/index.ts. The agent is created with a name, instructions, a model, tools and optional memory. The VoltAgent class then receives your agents and workflows, plus a server and a logger.

Memory is optional. The starter uses a LibSQL adapter that stores data in a local file, and the source notes that you can remove it to use the default in-memory memory.

agents: the agents you register with VoltAgent
workflows: multi-step automations you register
server: honoServer() provides the HTTP server
logger: a Pino logger created with createPinoLogger

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

const logger = createPinoLogger({
  name: "my-agent-app",
  level: "info",
});

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

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

new VoltAgent({
  agents: {
    agent,
  },
  workflows: {
    expenseApprovalWorkflow,
  },
  server: honoServer(),
  logger,
});

Run the dev server and test your agent

Go into your project folder and start the development server. According to the source, tsx compiles and runs your code. When the server starts, the terminal shows the HTTP address, which is http://localhost:3141 in the README example.

Open the VoltOps Console link shown in the terminal output to find and interact with your agent.

Find your agent in the VoltOps Console after the server starts
Send it a message to test its responses

npm run dev

Core features you can build with

The framework covers more than a single agent. The source lists these areas: a core runtime for defining agents with typed roles, tools, memory and model providers; a workflow engine for declarative multi-step automations; and supervisors that route tasks to sub-agents.

Multi-agent teams: a supervisor routes tasks to specialized sub-agents
Tools: Zod-typed tools with lifecycle hooks and cancellation, plus MCP server connections
Model switching: change providers such as OpenAI, Anthropic or Google by changing config
Memory and RAG: durable memory adapters and retriever agents
Voice, guardrails and evals for speech, content checks and agent testing

Documentation and AI coding assistants

The official documentation is at voltagent.dev/docs. An MCP server package, @voltagent/mcp-docs-server, lets AI coding assistants such as Claude, Cursor or Windsurf read VoltAgent docs, examples and changelogs while you code. The source links to a setup guide for it.

What people use it for

A TypeScript developer building a customer-facing assistant that calls their own tools
A team splitting a complex task across a supervisor agent and specialized sub-agents
An app that answers questions from documents using retrieval-augmented generation
A developer who wants to compare or switch model providers without rewriting agent logic

Frequently asked questions

Is VoltAgent free to use?

VoltAgent is released under the MIT licence, which is an open-source licence. The source does not list prices for the VoltOps Console, so check the official site for hosting and plan details.

What do I need to install VoltAgent?

The source lists Node.js and npm as prerequisites. You create a project with the npm create voltagent-app@latest command.

Can I use VoltAgent with Python?

No. VoltAgent is a TypeScript framework, so it is designed for TypeScript and Node.js projects. Python-first teams may prefer a Python-based library.

Do I need to know how to code to use VoltAgent?

Yes. Agents, tools and setup are written in code, so this framework suits developers rather than non-programmers.

How is VoltAgent different from LangChain.js or Vercel AI SDK?

The source lists LangChain.js, Mastra, Vercel AI SDK and LlamaIndex.TS as comparable projects but does not compare them in detail. Test each against your own requirements, especially multi-agent routing, memory and observability.

Can I change the AI model provider later?

The source says you can swap between providers such as OpenAI, Anthropic and Google by changing configuration rather than rewriting agent logic.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

VoltAgent suits TypeScript and Node.js developers who want to build multi-agent systems with memory, tools and RAG while keeping full code control. It is less suitable for non-programmers, Python-first teams or projects that only need a simple chatbot, where a lighter library may be enough.

Install options & downloads