English | 繁體中文 | 简体中文 | 日本語 | 한국어

Home Page | Documentation | Examples

VoltAgent is an open source TypeScript framework for building and orchestrating AI agents. You can build production-ready agents with memory, workflows, tools, and built-in LLM observability.

• Production-Ready from Day One: Ship agents with built-in memory, workflows, and observability instead of building infrastructure from scratch.
• Code with Confidence: Full TypeScript support with type-safe tools, automatic inference, and compile time safety across your entire agent system.
• Debug Like a Pro: Built-in VoltOps observability lets you trace every decision, monitor performance, and optimize workflows in real-time without external tools.
• Build Complex Systems Simply: Orchestrate multi-agent teams with supervisor coordination, declarative workflows, and modular architecture that scales from prototypes to production.

VoltAgent provides a complete platform for developing and monitoring AI agents through two complementary tools.

With the core framework, you can build intelligent agents with memory, tools, and multi-step workflows while connecting to any AI provider. Create sophisticated multi-agent systems where specialized agents work together under supervisor coordination.

• Core Runtime (@voltagent/core): Define agents with typed roles, tools, memory, and model providers in one place so everything stays organized.
• Workflow Engine: Describe multi-step automations declaratively rather than stitching together custom control flow.
• Supervisors & Sub-Agents: Run teams of specialized agents under a supervisor runtime that routes tasks and keeps them in sync.
• Tool Registry & MCP: Ship Zod-typed tools with lifecycle hooks and cancellation, and connect to Model Context Protocol servers without extra glue code.
• LLM Compatibility: Swap between OpenAI, Anthropic, Google, or other providers by changing config, not rewriting agent logic.
• Memory: Attach durable memory adapters so agents remember important context across runs.
• Retrieval & RAG: Plug in retriever agents to pull facts from your data sources and ground responses (RAG) before the model answers.
• Evals: Ship guardrails faster by running agent eval suites alongside your workflows.

VoltAgent comes with built-in VoltOps LLM observability to monitor and debug your agents in real-time with detailed execution traces, performance metrics, and visual dashboards. Inspect every decision your agents make, track tool usage, and optimize your workflows with built-in OpenTelemetry-based observability.

You can use the MCP server @voltagent/mcp-docs-server to teach your LLM how to use VoltAgent for AI-powered coding assistants like Claude, Cursor, or Windsurf. This allows AI assistants to access VoltAgent documentation, examples, and changelogs directly while you code.

📖 How to setup MCP docs server

Create a new VoltAgent project in seconds using the create-voltagent-app CLI tool:

npm create voltagent-app@latest

This command guides you through setup.

You'll see the starter code in src/index.ts, which now registers both an agent and a comprehensive workflow example found in src/workflows/index.ts.

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";

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

// Optional persistent memory (remove to use default in-memory)
const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

// A simple, general-purpose agent for the project.
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,
});

// Initialize VoltAgent with your agent(s) and workflow(s)
new VoltAgent({
  agents: {
    agent,
  },
  workflows: {
    expenseApprovalWorkflow,
  },
  server: honoServer(),
  logger,
});

Afterwards, navigate to your project and run:

npm run dev

When you run the dev command, tsx will compile and run your code. You should see the VoltAgent server startup message in your terminal:

══════════════════════════════════════════════════
VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
✓ HTTP Server: http://localhost:3141

Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════

Your agent is now running! To interact with it:

1. Open the Console: Click the VoltOps LLM Observability Platform link in your terminal output (or copy-paste it into your browser).
2. Find Your Agent: On the VoltOps LLM Observability Platform page, you should see your agent listed (e.g., "my-agent").
3. Open Agent Details: Click on your agent's name.
4. Start Chatting: On the agent detail page, click the chat icon in the bottom right corner to open the chat window.
5. Send a Message: Type a message like "Hello" and press Enter.

Your new project also includes a powerful workflow engine.

The expense approval workflow demonstrates human-in-the-loop automation with suspend/resume capabilities:

import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

export const expenseApprovalWorkflow = createWorkflowChain({
  id: "expense-approval",
  name: "Expense Approval Workflow",
  purpose: "Process expense reports with manager approval for high amounts",

  input: z.object({
    employeeId: z.string(),
    amount: z.number(),
    category: z.string(),
    description: z.string(),
  }),
  result: z.object({
    status: z.enum(["approved", "rejected"]),
    approvedBy: z.string(),
    finalAmount: z.number(),
  }),
})
  // Step 1: Validate expense and check if approval needed
  .andThen({
    id: "check-approval-needed",
    resumeSchema: z.object({
      approved: z.boolean(),
      managerId: z.string(),
      comments: z.string().optional(),
      adjustedAmount: z.number().optional(),
    }),
    execute: async ({ data, suspend, resumeData }) => {
      // If we're resuming with manager's decision
      if (resumeData) {
        return {
          ...data,
          approved: resumeData.approved,
          approvedBy: resumeData.managerId,
          finalAmount: resumeData.adjustedAmount || data.amount,
        };
      }

      // Check if manager approval is needed (expenses over $500)
      if (data.amount > 500) {
        await suspend("Manager approval required", {
          employeeId: data.employeeId,
          requestedAmount: data.amount,
        });
      }

      // Auto-approve small expenses
      return {
        ...data,
        approved: true,
        approvedBy: "system",
        finalAmount: data.amount,
      };
    },
  })
  // Step 2: Process the final decision
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });

You can test the pre-built expenseApprovalWorkflow directly from the VoltOps console:

1. Go to the Workflows Page: After starting your server, go directly to the Workflows page.
2. Select Your Project: Use the project selector to choose your project (e.g., "my-agent-app").
3. Find and Run: You will see "Expense Approval Workflow" listed. Click it, then click the "Run" button.
4. Provide Input: The workflow expects a JSON object with expense details. Try a small expense for automatic approval:

   {
     "employeeId": "EMP-123",
     "amount": 250,
     "category": "office-supplies",
     "description": "New laptop mouse and keyboard"
   }

5. View the Results: After execution, you can inspect the detailed logs for each step and see the final output directly in the console.

VoltAgent comes with VoltOps, a LLM observability platform built-in to help you monitor, debug, and optimize your agents in real-time.

🎬 Try Live Demo

📖 VoltOps Documentation

🚀 VoltOps Platform

Deep dive into agent execution flow with detailed traces and performance metrics.

Get a comprehensive overview of all your agents, workflows, and system performance metrics.

Track detailed execution logs for every agent interaction and workflow step.

Inspect and manage agent memory, context, and conversation history.

Analyze complete execution traces to understand agent behavior and optimize performance.

Design, test, and refine prompts directly in the console.

Explore real-world implementations of VoltAgent with complete source code and video tutorials.

For more examples and use cases, visit our examples repository.

Build a WhatsApp chatbot that handles food orders through natural conversation, manages menu items from a database, and processes orders with full conversation context.

• 📖 Tutorial
• 💻 Source Code

Convert YouTube videos into Markdown blog posts using a supervisor agent that coordinates subagents with MCP tools, shared working memory, and VoltOps observability.

• 📖 Tutorial
• 💻 Source Code

Implement an Instagram ad generator that uses BrowserBase Stagehand to analyze landing pages, extract brand data, and generate visuals through Google Gemini AI.

• 📖 Tutorial
• 💻 Source Code

Build an intelligent recipe recommendation system that creates personalized cooking suggestions based on available ingredients, dietary preferences, and time constraints.

• 📖 Tutorial
• 📹 Watch Video
• 💻 Source Code

Create a multi-agent research workflow where different AI agents collaborate to research topics and generate comprehensive reports with type-safe data flow.

• 📖 Tutorial
• 📹 Watch Video
• 💻 Source Code

Build AI agents for real-world business needs across different industries:

• HR Agent - Automate recruiting, employee onboarding, and HR support tasks.
• Customer Support Agent - Build support agents that handle customer questions and issues.
• Sales Teams - Qualify leads, gather customer data, and personalize sales outreach.
• Finance Agent - Manage invoices, track expenses, and generate financial reports.
• Development Agent - Review code, manage deployments, and help development teams.
• Marketing Agent - Plan campaigns, create content, and analyze marketing performance.
• Legal Agent - Review contracts, check compliance, and handle legal tasks.
• Insurance Agent - Process claims, evaluate risks, and manage policies.
• Industrial Agent - Monitor equipment, predict maintenance needs, and ensure safety.
• Education Agent - Provide personalized tutoring, track student progress, and support learning.
• Government Agent - Handle permit applications, process benefits, and serve citizens.
• Documentation Agent - Create API docs, write changelogs, and generate tutorials from code.

• 📖 Start with interactive tutorial to learn the fundamentals building AI Agents.
• Documentation: Dive into guides, concepts, and tutorials.
• Examples: Explore practical implementations.
• Blog: Read more about technical insights, and best practices.

We welcome contributions! Please refer to the contribution guidelines (link needed if available). Join our Discord server for questions and discussions.

Big thanks to everyone who's been part of the VoltAgent journey, whether you've built a plugin, opened an issue, dropped a pull request, or just helped someone out on Discord or GitHub Discussions.

VoltAgent is a community effort, and it keeps getting better because of people like you.

Your stars help us reach more developers! If you find VoltAgent useful, please consider giving us a star on GitHub to support the project and help others discover it.

Licensed under the MIT License, Copyright © 2025-present VoltAgent.