voltagent README

The project's README from github.com/VoltAgent/voltagent. As one markdown file: README.md.

voltagent

AI Agent Engineering Platform

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

Home Page | Documentation | Examples

GitHub issues GitHub pull requests License: MIT Contributor Covenant npm version

npm downloads Discord Twitter Follow

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.

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

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.

VoltAgent Demo

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:

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:

expense-approval

  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.

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.

1

Dashboard

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

dashboar

Logs

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

VoltOps Logs

Memory Management

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

VoltOps Memory Overview

Traces

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

VoltOps Traces

Prompt Builder

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

prompts

Deployment

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

deployment

📖 VoltOps Deploy Documentation

Triggers & Actions

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

triggers

Monitoring

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

monitoring

Guardrails

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

guardrails

Evals

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

evals

RAG (Knowledge Base)

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

rag

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.

Contributors

License

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

voltagent (VoltAgent/voltagent)

Searching Database…

10.8K ·GitHub
这是什么?VoltAgent 是一个端到端的 AI 智能体开发平台:它是一个开源的 TypeScript 框架,用来构建具备记忆、工具、RAG、工作流和语音能力的智能体,同时提供用于可观测性和运维的 VoltOps 控制台。
它是我写代码时用的框架,还是一个托管服务?两者都是。核心是一个开源的 TypeScript 框架,通过 npm 包安装后直接写代码使用;VoltOps 控制台则是平台部分,可以用云端版本,也可以自己部署,用来监控和管理你的智能体。
我怎么从零开始把一个智能体跑起来?先用 create-voltagent-app 命令行工具搭建一个项目,再运行它的开发命令,智能体服务器就启动了——打开终端里打印出来的控制台链接,马上就能和你的智能体对话。
我需要装什么环境?它能对接哪些 AI 服务商?需要 Node.js 20 或更高版本(如果你想改这个 monorepo 本身,则需要 pnpm 8+)。AI 服务商可以通过配置随时切换——比如 OpenAI、Anthropic、Google 等等,不用重写智能体的逻辑。
我能在商业项目里免费使用它吗?可以——这个框架采用 MIT 许可证,可以免费使用、修改并发布到商业产品中。
它自带哪些示例智能体?现成的示例包括:能在频道里回复的 Slack 智能体、Airtable 自动化智能体、WhatsApp 点餐聊天机器人、YouTube 转博客工具,以及能产出完整报告的多智能体研究助手。
智能体能说话和听声音吗?能——框架通过 OpenAI、ElevenLabs 或自定义语音服务,支持文字转语音和语音转文字。
工作流运行到一半能暂停下来等人工决定吗?可以。初始项目自带一个报销审批工作流,演示带人工介入的自动化,支持暂停和恢复,并且可以直接在控制台里运行和查看。
如果用户在输出过程中刷新了页面会怎样?凭借可恢复的流式传输,客户端刷新后可以重新连接到仍在进行中的流,继续接收同一个响应。
Creator
VoltAgent
Size
34 MB
Stars
10.8K
Age
1y
Commits · 90 Days