voltagent Documentation

AI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework

10,007 stars TypeScript TypeScript 1 file · ~12,596 tokens #agents#ai#ai-agents#ai-agents-framework#aiagentframework#chatbots#chatgpt#framework
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy voltagent on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name voltagent -p 3593:3593 --restart always ghcr.io/cerbos/cerbos:latest
Configured Services & Ports
⚙️ cerbos
image: ghcr.io/cerbos/cerbos:latest
🔌 Ports: 3593:3593, 3592:3592
docker-compose.yml
yaml (docker-compose.yml) 
services:
  cerbos:
    image: ghcr.io/cerbos/cerbos:latest
    container_name: cerbos-pdp
    ports:
      - "3593:3593" # gRPC
      - "3592:3592" # HTTP
    volumes:
      - ./policies:/policies
    command: ["server", "--config=/conf.yaml"]
    configs:
      - source: cerbos-config
        target: /conf.yaml

configs:
  cerbos-config:
    content: |
      server:
        httpListenAddr: ":3592"
        grpcListenAddr: ":3593"
      storage:
        driver: disk
        disk:
          directory: /policies

File: README.md

VoltAgent is an end-to-end AI Agent Engineering Platform that consists of two main parts:

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

Core TypeScript Framework

With the open-source 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.
  • Resumable Streaming: Let clients reconnect to in-flight streams after refresh and continue receiving the same response.
  • Retrieval & RAG: Plug in retriever agents to pull facts from your data sources and ground responses (RAG) before the model answers.
  • VoltAgent Knowledge Base: Use the managed RAG service for document ingestion, chunking, embeddings, and search.
  • Voice: Add text-to-speech and speech-to-text capabilities with OpenAI, ElevenLabs, or custom voice providers.
  • Guardrails: Intercept and validate agent input or output at runtime to enforce content policies and safety rules.
  • Evals: Run agent eval suites alongside your workflows to measure and improve agent behavior.

MCP Server (@voltagent/mcp-docs-server)

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

💛 Sponsors

TestMu AI (formerly LambdaTest) is an AI-native testing cloud platform built for modern engineering teams. Covering everything from autonomous test creation and fast execution to testing AI agents, chatbots and voice assistants.

⚡ Quick Start

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

bash
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.

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 { 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:

bash
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:

text
══════════════════════════════════════════════════
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.

Running Your First Workflow

Your new project also includes a powerful workflow engine.

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

text
/* Detailed source-code truncated for AI context efficiency. */

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:
    json
    {
  "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.

Examples

For more examples, visit our examples repository.

VoltOps Console: LLM Observability - Automation - Deployment

VoltOps Console is the platform side of VoltAgent, providing observability, automation, and deployment so you can monitor and debug agents in production with real-time execution traces, performance metrics, and visual dashboards.

🎬 Try Live Demo

📖 VoltOps Documentation

🚀 VoltOps Platform

Observability & Tracing

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

Dashboard

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

Logs

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

Memory Management

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

Traces

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

Prompt Builder

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

Deployment

Deploy your agents to production with one-click GitHub integration and managed infrastructure.

📖 VoltOps Deploy Documentation

Triggers & Actions

Automate agent workflows with webhooks, schedules, and custom triggers to react to external events.

Monitoring

Monitor agent health, performance metrics, and resource usage across your entire system.

Guardrails

Set up safety boundaries and content filters to ensure agents operate within defined parameters.

Evals

Run evaluation suites to test agent behavior, accuracy, and performance against benchmarks.

RAG (Knowledge Base)

Connect your agents to knowledge sources with built-in retrieval-augmented generation capabilities.

Learning VoltAgent

Contribution

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

Contributor ♥️ Thanks

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.

License

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

File: archive/deprecated-providers/groq-ai/README.md

@voltagent/groq-ai

⚠️ DEPRECATED: This package is deprecated. Please use the Vercel AI SDK's Groq provider with @voltagent/vercel-ai instead.

Migration Guide:

typescript
// Old (deprecated)
import { GroqProvider } from "@voltagent/groq-ai";
const provider = new GroqProvider({ apiKey: "..." });

// New (recommended)
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { groq } from "@ai-sdk/groq";
const provider = new VercelAIProvider();
// Use with: model: groq("llama-3.3-70b-versatile")

VoltAgent Groq AI provider integration using the Groq SDK (@groq-sdk).

This package allows you to use Groq's fast inferencing models within your VoltAgent agents.

Installation

bash
npm install @voltagent/groq-ai
# or
yarn add @voltagent/groq-ai
# or
pnpm add @voltagent/groq-ai

Usage

You need to provide your Groq API key. You can get one from Groq after signing up.

typescript
import { VoltAgent, Agent } from "@voltagent/core";
import { GroqProvider } from "@voltagent/groq-ai";

const agent = new Agent({
  name: "finance",
  instructions: "A helpful assistant that answers questions without using tools",
  llm: new GroqProvider(),
  model: "meta-llama/llama-4-scout-17b-16e-instruct",
});

new VoltAgent({
  agents: {
    agent,
  },
});

License

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

File: archive/deprecated-providers/google-ai/README.md

Google AI Provider (`@voltagent/google-ai`)

⚠️ DEPRECATED: This package is deprecated. Please use the Vercel AI SDK's Google providers with @voltagent/vercel-ai instead.

Migration Guide:

typescript
// Old (deprecated)
import { GoogleAIProvider } from "@voltagent/google-ai";
const provider = new GoogleAIProvider({ apiKey: "..." });

// New (recommended) - for Gemini API
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { google } from "@ai-sdk/google";
const provider = new VercelAIProvider();
// Use with: model: google("gemini-1.5-pro")

// New (recommended) - for Vertex AI
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { vertex } from "@ai-sdk/google-vertex";
const provider = new VercelAIProvider();
// Use with: model: vertex("gemini-1.5-pro")

The Google AI Provider integrates VoltAgent with Google's Generative AI capabilities, supporting both the Gemini API (via API Key) and Vertex AI (via project/location configuration). It wraps the @google/genai SDK.

Key Characteristics:

  • Dual API Support: Works seamlessly with both Google AI Studio's Gemini API (using an API key) and Google Cloud's Vertex AI platform.
  • Model Agnostic (within Google): Accepts standard Google model identifier strings (e.g., 'gemini-1.5-pro', 'gemini-1.5-flash').
  • Core Functionality: Focuses on text generation, streaming, and structured object generation using the underlying Google SDK.

Installation

bash
npm install @voltagent/core @voltagent/google-ai zod

Note: @google/genai is a peer dependency. zod is required if using generateObject.

Configuration

Option 1: Gemini API (API Key)

typescript
import { GoogleAIProvider } from "@voltagent/google-ai";

// Direct API Key
const googleProvider = new GoogleAIProvider({
  apiKey: "YOUR_GOOGLE_API_KEY",
});

// Or via Environment Variable (GOOGLE_GENERATIVE_AI_API_KEY)
const googleProvider = new GoogleAIProvider({});

Option 2: Vertex AI (Project & Location)

typescript
import { GoogleAIProvider } from "@voltagent/google-ai";

const googleProvider = new GoogleAIProvider({
  project: "YOUR_GCP_PROJECT_ID",
  location: "us-central1", // or your preferred region
});

Usage

typescript
import { Agent } from "@voltagent/core";
import { GoogleAIProvider } from "@voltagent/google-ai";

const googleProvider = new GoogleAIProvider({ apiKey: "YOUR_API_KEY" });

const agent = new Agent({
  name: "Gemini Agent",
  instructions: "An agent powered by Google's Gemini",
  llm: googleProvider,
  model: "gemini-1.5-flash", // or "gemini-1.5-pro"
});

// Example call
async function run() {
  const response = await agent.generateText("What is the capital of France?");
  console.log(response.text);
}

run();

Supported Methods

  • generateText: ✅ Supported
  • streamText: ✅ Supported
  • generateObject: ✅ Supported
  • streamObject: ❌ Not supported

Tool Calling Support

✅ Supported.

The provider supports tool calling:

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

const weatherTool = createTool({
  name: "get_current_weather",
  parameters: z.object({
    location: z.string().describe("The location to get weather for"),
  }),
  execute: async (input) => {
    return {
      location: input.location,
      temperature: 72,
      condition: "sunny",
    };
  },
});

const agent = new Agent({
  name: "weather-agent",
  instructions: "A helpful weather assistant",
  llm: new GoogleAIProvider(),
  model: "gemini-1.5-flash",
  tools: [weatherTool],
});

Model Selection & Options

Set the model via the model property during Agent instantiation:

typescript
const response = await agent.generateText("Write a creative story.", {
  provider: {
    temperature: 0.9,
    maxTokens: 1024,
    // Other Google-specific parameters
  },
});

Refer to the Google AI documentation for available configuration parameters.

File: archive/deprecated-providers/anthropic-ai/README.md

Anthropic AI Provider (`@voltagent/anthropic-ai`)

⚠️ DEPRECATED: This package is deprecated. Please use the Vercel AI SDK's Anthropic provider with @voltagent/vercel-ai instead.

Migration Guide:

typescript
// Old (deprecated)
import { AnthropicProvider } from "@voltagent/anthropic-ai";
const provider = new AnthropicProvider({ apiKey: "..." });

// New (recommended)
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { anthropic } from "@ai-sdk/anthropic";
const provider = new VercelAIProvider();
// Use with: model: anthropic("claude-opus-4-1")

The Anthropic AI Provider integrates VoltAgent with Anthropic's Claude models. It wraps the official @anthropic-ai/sdk SDK.

Key Characteristics:

  • Claude Models: Supports all Claude models through the Anthropic API.
  • Model Agnostic: Accepts standard Claude model identifier strings (e.g., 'claude-opus-4-1', 'claude-3-opus-20240229').
  • Core Functionality: Focuses on text generation, streaming, and structured object generation using the underlying Anthropic SDK.

Installation

bash
npm install @voltagent/core @voltagent/anthropic-ai zod

Note: @anthropic-ai/sdk is a peer dependency. zod is required if using generateObject.

Configuration

The AnthropicProvider requires an API key, which can be provided directly or through an environment variable.

typescript
import { AnthropicProvider } from "@voltagent/anthropic-ai";

// Option 1: Direct API Key
const anthropicProvider = new AnthropicProvider({
  apiKey: "YOUR_ANTHROPIC_API_KEY",
});

// Option 2: Environment Variable (ANTHROPIC_API_KEY)
// Ensure process.env.ANTHROPIC_API_KEY is set
const anthropicProvider = new AnthropicProvider({});

Usage

Instantiate your Agent with the configured AnthropicProvider:

typescript
import { Agent } from "@voltagent/core";
import { AnthropicProvider } from "@voltagent/anthropic-ai";

const anthropicProvider = new AnthropicProvider({ apiKey: "YOUR_ANTHROPIC_API_KEY" });

const agent = new Agent({
  name: "Claude Agent",
  instructions: "An agent powered by Claude",
  llm: anthropicProvider,
  model: "claude-opus-4-1", // Specify the desired Claude model
});

// Example call
async function run() {
  const response = await agent.generateText("What is the capital of France?");
  console.log(response.text);
}

run();

Supported Methods

  • generateText: ✅ Supported. Calls Anthropic SDK's messages.create.
  • streamText: ✅ Supported. Calls Anthropic SDK's messages.create with stream: true.
  • generateObject: ✅ Supported. Uses Anthropic's structured output capabilities with Zod schema validation.
  • streamObject: ✅ Supported. Streams structured objects with schema validation.

Tool Calling Support

✅ Supported.

The @voltagent/anthropic-ai provider supports tool calling through the MCP (Model Control Protocol) format:

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

const weatherTool = createTool({
  name: "get_current_weather",
  parameters: z.object({
    location: z.string().describe("The location to get weather for"),
  }),
  execute: async (input) => {
    return {
      location: input.location,
      temperature: 72,
      condition: "sunny",
    };
  },
});

const agent = new Agent({
  name: "weather-agent",
  instructions: "A helpful weather assistant",
  llm: new AnthropicProvider(),
  model: "claude-opus-4-1",
  tools: [weatherTool],
});

Model Selection & Options

The specific Claude model (e.g., 'claude-opus-4-1', 'claude-3-opus-20240229') is set via the model property during Agent instantiation.

You can override or provide additional Anthropic-specific generation parameters (like temperature, max_tokens, top_p, stop_sequences, etc.) per-request using the provider key within the options object of generateText, streamText, or generateObject.

typescript
// Example: Overriding temperature for a specific call
const response = await agent.generateText("Write a creative story.", {
  provider: {
    temperature: 0.9,
    max_tokens: 1024,
    // Any other valid Anthropic parameters
  },
});

Refer to the Anthropic API documentation for the full list of available configuration parameters.

File: archive/deprecated-providers/vercel-ai/README.md

What is VoltAgent?

An AI Agent Framework provides the foundational structure and tools needed to build applications powered by autonomous agents. These agents, often driven by Large Language Models (LLMs), can perceive their environment, make decisions, and take actions to achieve specific goals. Building such agents from scratch involves managing complex interactions with LLMs, handling state, connecting to external tools and data, and orchestrating workflows.

VoltAgent is an open-source TypeScript framework that acts as this essential toolkit. It simplifies the development of AI agent applications by providing modular building blocks, standardized patterns, and abstractions. Whether you're creating chatbots, virtual assistants, automated workflows, or complex multi-agent systems, VoltAgent handles the underlying complexity, allowing you to focus on defining your agents' capabilities and logic.

Instead of building everything from scratch, VoltAgent provides ready-made, modular building blocks:

  • Core Engine (@voltagent/core): The heart of VoltAgent, providing fundamental capabilities for your AI agents Define individual agents with specific roles, tools, and memory.
  • Multi-Agent Systems: Architect complex applications by coordinating multiple specialized agents using Supervisors.
  • Extensible Packages: Enhance functionality with packages like @voltagent/voice for voice interactions.
  • Tooling & Integrations: Equip agents with tools to connect to external APIs, databases, and services, enabling them to perform real-world tasks. Supports the Model Context Protocol (MCP) for standardized tool interactions.
  • Data Retrieval & RAG: Implement specialized retriever agents for efficient information fetching and Retrieval-Augmented Generation (RAG).
  • Memory: Enable agents to remember past interactions for more natural and context-aware conversations.
  • LLM Compatibility: Works with popular AI models from OpenAI, Google, Anthropic, and more, allowing easy switching.
  • Developer Ecosystem: Includes helpers like create-voltagent-app, @voltagent/cli, and the visual VoltOps LLM Observability Platform for quick setup, monitoring, and debugging.

In essence, VoltAgent helps developers build sophisticated AI applications faster and more reliably, avoiding repetitive setup and the limitations of simpler tools.

Why VoltAgent?

Building AI applications often involves a trade-off:

  1. DIY Approach: Using basic AI provider tools offers control but leads to complex, hard-to-manage code and repeated effort.
  2. No-Code Builders: Simpler initially but often restrictive, limiting customization, provider choice, and complexity.

VoltAgent provides a middle ground, offering structure and components without sacrificing flexibility:

  • Build Faster: Accelerate development with pre-built components compared to starting from scratch.
  • Maintainable Code: Encourages organization for easier updates and debugging.
  • Scalability: Start simple and easily scale to complex, multi-agent systems handling intricate workflows.
  • Flexibility: Full control over agent behavior, LLM choice, tool integrations, and UI connections.
  • Avoid Lock-in: Freedom to switch AI providers and models as needed.
  • Cost Efficiency: Features designed to optimize AI service usage and reduce redundant calls.
  • Visual Monitoring: Use the VoltOps LLM Observability Platform to track agent performance, inspect state, and debug visually.

VoltAgent empowers developers to build their envisioned AI applications efficiently, from simple helpers to complex systems.

⚡ Quick Start

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

bash
npm create voltagent-app@latest

This command guides you through setup.

You'll see the starter code in src/index.ts to get you started with the VoltAgent framework.

typescript
import { VoltAgent, Agent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai"; // Example provider
import { openai } from "@ai-sdk/openai"; // Example model

// Define a simple agent
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that answers questions without using tools",
  // Note: You can swap VercelAIProvider and openai with other supported providers/models
  llm: new VercelAIProvider(),
  model: openai("gpt-4o-mini"),
});

// Initialize VoltAgent with your agent(s)
new VoltAgent({
  agents: {
    agent,
  },
});

Afterwards, navigate to your project and run:

bash
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:

text
══════════════════════════════════════════════════
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.

Key Features

  • Agent Core: Define agents with descriptions, LLM providers, tools, and memory management.
  • Multi-Agent Systems: Build complex workflows using Supervisor Agents coordinating multiple specialized Sub-Agents.
  • Tool Usage & Lifecycle: Equip agents with custom or pre-built tools (functions) with type-safety (Zod), lifecycle hooks, and cancellation support to interact with external systems.
  • Flexible LLM Support: Integrate seamlessly with various LLM providers (OpenAI, Anthropic, Google, etc.) and easily switch between models.
  • Memory Management: Enable agents to retain context across interactions using different configurable memory providers.
  • Observability & Debugging: Visually monitor agent states, interactions, logs, and performance via the VoltOps LLM Observability Platform.
  • Voice Interaction: Build voice-enabled agents capable of speech recognition and synthesis using the @voltagent/voice package.
  • Data Retrieval & RAG: Integrate specialized retriever agents for efficient information fetching and Retrieval-Augmented Generation (RAG) from various sources.
  • Model Context Protocol (MCP) Support: Connect to external tool servers (HTTP/stdio) adhering to the MCP standard for extended capabilities.
  • Prompt Engineering Tools: Leverage utilities like createPrompt for crafting and managing effective prompts for your agents.
  • Framework Compatibility: Designed for easy integration into existing Node.js applications and popular frameworks.

Use Cases

VoltAgent is versatile and can power a wide range of AI-driven applications:

  • Complex Workflow Automation: Orchestrate multi-step processes involving various tools, APIs, and decision points using coordinated agents.
  • Intelligent Data Pipelines: Build agents that fetch, process, analyze, and transform data from diverse sources.
  • AI-Powered Internal Tools & Dashboards: Create interactive internal applications that leverage AI for analysis, reporting, or task automation, often integrated with UIs using hooks.
  • Automated Customer Support Agents: Develop sophisticated chatbots that can understand context (memory), use tools (e.g., check order status), and escalate complex issues.
  • Repository Analysis & Codebase Automation: Analyze code repositories, automate refactoring tasks, generate documentation, or manage CI/CD processes.
  • Retrieval-Augmented Generation (RAG) Systems: Build agents that retrieve relevant information from knowledge bases (using retriever agents) before generating informed responses.
  • Voice-Controlled Interfaces & Applications: Utilize the @voltagent/voice package to create applications that respond to and generate spoken language.
  • Personalized User Experiences: Develop agents that adapt responses and actions based on user history and preferences stored in memory.
  • Real-time Monitoring & Alerting: Design agents that continuously monitor data streams or systems and trigger actions or notifications based on defined conditions.
  • And Virtually Anything Else...: If you can imagine an AI agent doing it, VoltAgent can likely help you build it! ⚡

Learning VoltAgent

  • Documentation: Dive into guides, concepts, and tutorials.
  • Examples: Explore practical implementations.
  • Blog: Read more about technical insights, and best practices.

Contribution

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

Community ♥️ Thanks

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.

License

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

File: archive/deprecated-providers/vercel-ui/README.md

VoltAgent Vercel UI SDK Integration

VoltAgent integration with the Vercel UI SDK for building agentic applications.

🚀 Quick Start

bash
npm install @voltagent/vercel-ui
typescript
import { convertToUIMessages } from "@voltagent/vercel-ui";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { Agent } from "@voltagent/core";

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  purpose: "A helpful assistant that can answer questions and help with tasks.",
  instructions: "You are a helpful assistant that can answer questions and help with tasks.",
  model: "gpt-4.1-mini",
  llm: new VercelAIProvider(),
  hooks: {
    onEnd: async (result) => {
      await chatStore.save({
        conversationId: result.conversationId,
        messages: convertToUIMessages(result.operationContext),
      });
    },
  },
});

const result = await agent.generateText("Hello, how are you?");

// You can now fetch the messages from your custom chat store and return to the UI to provide a
// history of the conversation.

app.get("/api/chats/:id", async ({ req }) => {
  const conversation = await chatStore.read(req.param("id"));
  return Response.json(conversation.messages);
});

🧪 Testing

This package maintains strict test coverage requirements. All code must have comprehensive test coverage with the following thresholds:

Coverage Requirements

  • Global: 90% statements, 90% branches, 100% functions, 90% lines
  • Messages module: 100% statements, 95% branches, 100% functions, 100% lines
  • Utils module: 100% statements, 100% branches, 100% functions, 100% lines
  • Streams module: 90% statements, 90% branches, 100% functions, 90% lines

Running Tests

bash
# Run tests in watch mode
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests with strict coverage enforcement
pnpm test:coverage:strict

Coverage Exclusions

The following files are excluded from coverage requirements as they contain only type definitions:

  • src/types.ts
  • src/streams/type-utils.ts

📄 License

MIT License - see LICENSE file for details.

File: archive/deprecated-providers/xsai/README.md

What is VoltAgent?

An AI Agent Framework provides the foundational structure and tools needed to build applications powered by autonomous agents. These agents, often driven by Large Language Models (LLMs), can perceive their environment, make decisions, and take actions to achieve specific goals. Building such agents from scratch involves managing complex interactions with LLMs, handling state, connecting to external tools and data, and orchestrating workflows.

VoltAgent is an open-source TypeScript framework that acts as this essential toolkit. It simplifies the development of AI agent applications by providing modular building blocks, standardized patterns, and abstractions. Whether you're creating chatbots, virtual assistants, automated workflows, or complex multi-agent systems, VoltAgent handles the underlying complexity, allowing you to focus on defining your agents' capabilities and logic.

Instead of building everything from scratch, VoltAgent provides ready-made, modular building blocks:

  • Core Engine (@voltagent/core): The heart of VoltAgent, providing fundamental capabilities for your AI agents Define individual agents with specific roles, tools, and memory.
  • Multi-Agent Systems: Architect complex applications by coordinating multiple specialized agents using Supervisors.
  • Extensible Packages: Enhance functionality with packages like @voltagent/voice for voice interactions.
  • Tooling & Integrations: Equip agents with tools to connect to external APIs, databases, and services, enabling them to perform real-world tasks. Supports the Model Context Protocol (MCP) for standardized tool interactions.
  • Data Retrieval & RAG: Implement specialized retriever agents for efficient information fetching and Retrieval-Augmented Generation (RAG).
  • Memory: Enable agents to remember past interactions for more natural and context-aware conversations.
  • LLM Compatibility: Works with popular AI models from OpenAI, Google, Anthropic, and more, allowing easy switching.
  • Developer Ecosystem: Includes helpers like create-voltagent-app, @voltagent/cli, and the visual VoltOps LLM Observability Platform for quick setup, monitoring, and debugging.

In essence, VoltAgent helps developers build sophisticated AI applications faster and more reliably, avoiding repetitive setup and the limitations of simpler tools.

Why VoltAgent?

Building AI applications often involves a trade-off:

  1. DIY Approach: Using basic AI provider tools offers control but leads to complex, hard-to-manage code and repeated effort.
  2. No-Code Builders: Simpler initially but often restrictive, limiting customization, provider choice, and complexity.

VoltAgent provides a middle ground, offering structure and components without sacrificing flexibility:

  • Build Faster: Accelerate development with pre-built components compared to starting from scratch.
  • Maintainable Code: Encourages organization for easier updates and debugging.
  • Scalability: Start simple and easily scale to complex, multi-agent systems handling intricate workflows.
  • Flexibility: Full control over agent behavior, LLM choice, tool integrations, and UI connections.
  • Avoid Lock-in: Freedom to switch AI providers and models as needed.
  • Cost Efficiency: Features designed to optimize AI service usage and reduce redundant calls.
  • Visual Monitoring: Use the VoltOps LLM Observability Platform to track agent performance, inspect state, and debug visually.

VoltAgent empowers developers to build their envisioned AI applications efficiently, from simple helpers to complex systems.

⚡ Quick Start

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

bash
npm create voltagent-app@latest

This command guides you through setup.

You'll see the starter code in src/index.ts to get you started with the VoltAgent framework.

typescript
import { VoltAgent, Agent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai"; // Example provider
import { openai } from "@ai-sdk/openai"; // Example model

// Define a simple agent
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that answers questions without using tools",
  // Note: You can swap VercelAIProvider and openai with other supported providers/models
  llm: new VercelAIProvider(),
  model: openai("gpt-4o-mini"),
});

// Initialize VoltAgent with your agent(s)
new VoltAgent({
  agents: {
    agent,
  },
});

Afterwards, navigate to your project and run:

bash
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:

text
══════════════════════════════════════════════════
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.

Key Features

  • Agent Core: Define agents with descriptions, LLM providers, tools, and memory management.
  • Multi-Agent Systems: Build complex workflows using Supervisor Agents coordinating multiple specialized Sub-Agents.
  • Tool Usage & Lifecycle: Equip agents with custom or pre-built tools (functions) with type-safety (Zod), lifecycle hooks, and cancellation support to interact with external systems.
  • Flexible LLM Support: Integrate seamlessly with various LLM providers (OpenAI, Anthropic, Google, etc.) and easily switch between models.
  • Memory Management: Enable agents to retain context across interactions using different configurable memory providers.
  • Observability & Debugging: Visually monitor agent states, interactions, logs, and performance via the VoltOps LLM Observability Platform.
  • Voice Interaction: Build voice-enabled agents capable of speech recognition and synthesis using the @voltagent/voice package.
  • Data Retrieval & RAG: Integrate specialized retriever agents for efficient information fetching and Retrieval-Augmented Generation (RAG) from various sources.
  • Model Context Protocol (MCP) Support: Connect to external tool servers (HTTP/stdio) adhering to the MCP standard for extended capabilities.
  • Prompt Engineering Tools: Leverage utilities like createPrompt for crafting and managing effective prompts for your agents.
  • Framework Compatibility: Designed for easy integration into existing Node.js applications and popular frameworks.

Use Cases

VoltAgent is versatile and can power a wide range of AI-driven applications:

  • Complex Workflow Automation: Orchestrate multi-step processes involving various tools, APIs, and decision points using coordinated agents.
  • Intelligent Data Pipelines: Build agents that fetch, process, analyze, and transform data from diverse sources.
  • AI-Powered Internal Tools & Dashboards: Create interactive internal applications that leverage AI for analysis, reporting, or task automation, often integrated with UIs using hooks.
  • Automated Customer Support Agents: Develop sophisticated chatbots that can understand context (memory), use tools (e.g., check order status), and escalate complex issues.
  • Repository Analysis & Codebase Automation: Analyze code repositories, automate refactoring tasks, generate documentation, or manage CI/CD processes.
  • Retrieval-Augmented Generation (RAG) Systems: Build agents that retrieve relevant information from knowledge bases (using retriever agents) before generating informed responses.
  • Voice-Controlled Interfaces & Applications: Utilize the @voltagent/voice package to create applications that respond to and generate spoken language.
  • Personalized User Experiences: Develop agents that adapt responses and actions based on user history and preferences stored in memory.
  • Real-time Monitoring & Alerting: Design agents that continuously monitor data streams or systems and trigger actions or notifications based on defined conditions.
  • And Virtually Anything Else...: If you can imagine an AI agent doing it, VoltAgent can likely help you build it! ⚡

Learning VoltAgent

  • Documentation: Dive into guides, concepts, and tutorials.
  • Examples: Explore practical implementations.
  • Blog: Read more about technical insights, and best practices.

Contribution

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

Community ♥️ Thanks

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.

License

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

File: archive/deprecated-providers/README.md

Deprecated VoltAgent Providers

This directory contains deprecated provider packages that have been replaced by Vercel AI SDK providers.

Deprecated Packages

  • @voltagent/anthropic-ai → Use @ai-sdk/anthropic with @voltagent/vercel-ai
  • @voltagent/google-ai → Use @ai-sdk/google with @voltagent/vercel-ai
  • @voltagent/groq-ai → Use @ai-sdk/groq with @voltagent/vercel-ai

Migration Guides

Why Archived?

These packages have been archived to:

  1. Keep the main codebase clean for contributors
  2. Reduce maintenance burden
  3. Focus on core VoltAgent features
  4. Leverage Vercel AI SDK's well-maintained providers

Note

These packages are still available on NPM for backward compatibility, but will not receive updates.

File: docs/linting.md

Linting

VoltAgent uses Biome for linting and formatting code. Biome is a fast and modern linter and formatter for TypeScript and JavaScript that has set of pre-defined rules that are applied to the codebase.

Tools

  • Linter + Formatter: Biome (replaces ESLint + Prettier)
  • Config: biome.json

Running Commands

bash
# Check all files
pnpm lint

# Auto-fix issues
pnpm lint:fix

# Check only (CI mode)
pnpm lint:ci

VS Code Integration

Install the Biome extension:

json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

File: docs/structure.md

Repository Structure

This monorepo is organized using pnpm workspaces and Lerna with the following main directories:

Overview

text
voltagent/
├── packages/       # Core packages and integrations
├── examples/       # Example implementations
├── website/        # Documentation website and marketplace
├── docs/           # Project documentation
├── scripts/        # Build and utility scripts
├── .changeset/     # Changeset configuration
└── package.json    # Root package configuration

Details

`packages/`

Core packages, AI provider integrations, and utilities:

  • cli - VoltAgent CLI for project scaffolding and management
  • core - Main VoltAgent framework with agent orchestration, memory management, tools, and observability. Includes the ConversationBuffer (merges model/tool messages into UI messages for persistence) and MemoryPersistQueue (debounced memory write pipeline).
  • create-voltagent-app - Project initialization tool
  • docs-mcp - Model Context Protocol documentation server
  • internal - Internal utilities and shared types used across packages
  • langfuse-exporter - LangFuse telemetry exporter
  • libsql - LibSQL database integration
  • logger - Universal logger implementation
  • postgres - PostgreSQL database integration
  • sdk - JavaScript/TypeScript SDK for VoltAgent API
  • server-core - Core server handlers, schemas, and business logic
  • server-hono - Hono-based server implementation with API routes
  • supabase - Supabase client integration
  • vercel-ai-exporter - Vercel AI telemetry exporter
  • voice - Voice interaction capabilities

Conventions

Packages are named using the following conventions:

  • @voltagent/* - Core framework packages
  • @voltagent/*-exporter - Telemetry exporters
  • voltagent-example-* - Example applications

Certain packages are deprecated and include a DEPRECATED.md file with migration instructions in the root of the package (i.e. google-ai).

`examples/`

Example implementations demonstrating VoltAgent usage:

  • Basic agent examples
  • Integration patterns
  • Advanced use cases
  • Best practices demonstrations

Conventions

Examples are named using the following conventions:

  • with-* - Example application using the specific integration (i.e. with-chroma or with-google-ai)

`website/`

Documentation website built with Docusaurus:

  • docs/ - Technical documentation
  • blog/ - Blog posts and tutorials
  • static/ - Static assets and images

`docs/`

Project-level documentation:

  • structure.md - This file, describing repository organization
  • tooling.md - Development tools and workflows
  • Additional architecture and design documents

`scripts/`

Reusable scripts for the project, for repeatable development tasks.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agents Browse agents catalog → #ai Browse ai catalog → #ai-agents Browse ai-agents catalog → #ai-agents-framework Browse ai-agents-framework catalog → #aiagentframework Browse aiagentframework catalog → #chatbots Browse chatbots catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →