From 84eb5ae71365168545be0238a7485c65ad0d1ebe Mon Sep 17 00:00:00 2001 From: GitHub Contribution Agent Date: Fri, 8 May 2026 02:21:00 +0800 Subject: [PATCH 1/3] docs: add FAQ section for common questions --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/README.md b/README.md index ad520f7ac..90a90aa70 100644 --- a/README.md +++ b/README.md @@ -351,6 +351,109 @@ Connect your agents to knowledge sources with built-in retrieval-augmented gener - **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Explore practical implementations. - **[Blog](https://voltagent.dev/blog/)**: Read more about technical insights, and best practices. +## ❓ FAQ + +### What is VoltAgent? + +VoltAgent is an end-to-end AI Agent Engineering Platform that combines an open-source TypeScript framework with VoltOps Console for production-ready observability, automation, and deployment. + +### How does VoltAgent differ from other agent frameworks? + +VoltAgent provides a complete platform rather than just a framework: +- **TypeScript Framework**: Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow with full code control +- **VoltOps Console**: Real-time observability, traces, memory management, prompt builder, deployment, triggers, monitoring, evals +- **Supervisors & Sub-Agents**: Multi-agent orchestration with supervisor coordination +- **Resumable Streaming**: Clients can reconnect and continue receiving responses + +### How do I get started? + +```bash +npm create voltagent-app@latest +``` + +This creates a project with an agent and workflow example. Run `npm run dev` and test via [VoltOps Console](https://console.voltagent.dev). + +### What LLM providers does VoltAgent support? + +VoltAgent works with OpenAI, Anthropic, Google (Gemini), and other providers. Swap providers by changing config, not rewriting agent logic: + +```typescript +import { openai } from "@ai-sdk/openai"; +import { anthropic } from "@ai-sdk/anthropic"; + +const agent = new Agent({ + model: openai("gpt-4o-mini"), // or anthropic("claude-3-5-sonnet") +}); +``` + +### How do I add memory to my agent? + +```typescript +import { Memory } from "@voltagent/core"; +import { LibSQLMemoryAdapter } from "@voltagent/libsql"; + +const memory = new Memory({ + storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), +}); + +const agent = new Agent({ name: "my-agent", memory }); +``` + +### What is VoltOps Console? + +VoltOps Console is the platform side of VoltAgent providing: +- **Observability**: Real-time traces, logs, memory inspection +- **Dashboard**: Performance metrics and system overview +- **Prompt Builder**: Design and test prompts +- **Deployment**: One-click GitHub integration +- **Triggers & Actions**: Webhooks, schedules, automation +- **Guardrails**: Safety boundaries and content filters +- **Evals**: Evaluation suites for testing agent behavior + +[Try Live Demo](https://console.voltagent.dev/demo) + +### How do I create multi-agent systems? + +VoltAgent supports Supervisors & Sub-Agents for multi-agent orchestration: + +```typescript +const supervisor = new Agent({ + name: "supervisor", + instructions: "Coordinate specialized agents", + subAgents: [researchAgent, writerAgent, reviewAgent], +}); +``` + +The supervisor routes tasks and keeps sub-agents synchronized. + +### What are workflows? + +Workflows are multi-step automations with suspend/resume capabilities: + +```typescript +const workflow = createWorkflowChain({ id: "approval" }) + .andThen({ execute: async ({ data, suspend }) => { + if (data.amount > 500) await suspend("Manager approval required"); + return { approved: true };\n }}) + .andThen({ execute: async ({ data }) => { + return { status: "approved" };\n }}); +``` + +### Does VoltAgent support MCP? + +Yes! VoltAgent has built-in MCP (Model Context Protocol) support: +- Connect to MCP servers without extra glue code +- Use `@voltagent/mcp-docs-server` to teach AI assistants about VoltAgent + +### Where can I find more resources? + +- **[Interactive Tutorial](https://voltagent.dev/tutorial/introduction/)**: Learn fundamentals +- **[Documentation](https://voltagent.dev/docs/)**: Guides and concepts +- **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Practical implementations +- **[Discord](https://s.voltagent.dev/discord)**: Community support + +--- + ## Contribution We welcome contributions! Please refer to the contribution guidelines (link needed if available). Join our [Discord](https://s.voltagent.dev/discord) server for questions and discussions. From 4c6a6a3a60300651c633415075e75d5e8e6bf5d6 Mon Sep 17 00:00:00 2001 From: meichuanyi <35057768+meichuanyi@users.noreply.github.com> Date: Wed, 13 May 2026 17:10:40 +0800 Subject: [PATCH 2/3] docs: add FAQ section --- README.md | 174 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 111 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 90a90aa70..f0c9f46ed 100644 --- a/README.md +++ b/README.md @@ -351,120 +351,168 @@ Connect your agents to knowledge sources with built-in retrieval-augmented gener - **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Explore practical implementations. - **[Blog](https://voltagent.dev/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](https://s.voltagent.dev/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](https://contrib.rocks/image?repo=voltagent/voltagent&max=500&columns=20&anon=1) + ## ❓ FAQ ### What is VoltAgent? -VoltAgent is an end-to-end AI Agent Engineering Platform that combines an open-source TypeScript framework with VoltOps Console for production-ready observability, automation, and deployment. +VoltAgent is an end-to-end **AI Agent Engineering Platform** that provides: +- **Open-Source TypeScript Framework**: Build agents with memory, tools, workflows, voice, and RAG +- **VoltOps Console**: Production-ready observability, automation, deployment, and evaluations -### How does VoltAgent differ from other agent frameworks? +### How is VoltAgent different from other agent frameworks? -VoltAgent provides a complete platform rather than just a framework: -- **TypeScript Framework**: Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow with full code control -- **VoltOps Console**: Real-time observability, traces, memory management, prompt builder, deployment, triggers, monitoring, evals -- **Supervisors & Sub-Agents**: Multi-agent orchestration with supervisor coordination -- **Resumable Streaming**: Clients can reconnect and continue receiving responses +| Feature | VoltAgent | LangChain | CrewAI | +|---------|-----------|-----------|--------| +| **Architecture** | TypeScript-first | Python-first | Python-first | +| **Workflow Engine** | Declarative workflows | Sequential chains | Role-playing teams | +| **Memory** | Multiple adapters | In-memory + options | Shared memory | +| **Observability** | Built-in VoltOps Console | External tools | Limited | +| **Deployment** | One-click cloud | Manual setup | Manual setup | +| **Voice Support** | Built-in TTS/STT | External providers | No | -### How do I get started? +### How do I install VoltAgent? ```bash npm create voltagent-app@latest ``` -This creates a project with an agent and workflow example. Run `npm run dev` and test via [VoltOps Console](https://console.voltagent.dev). +This creates a new project with starter code and examples. + +### Which LLM providers are supported? + +VoltAgent supports all major providers through AI SDK: +- **OpenAI**: GPT-4, GPT-4o, o1, o3-mini +- **Anthropic**: Claude 3.5, Claude Sonnet 4 +- **Google**: Gemini 1.5 Pro, Gemini 2.0 Flash +- **Groq**: Llama, Mixtral (fast inference) +- **Custom**: Any provider supported by AI SDK + +### What are Supervisors and Sub-Agents? + +VoltAgent supports **multi-agent systems** where: +- **Supervisor**: Routes tasks to specialized sub-agents +- **Sub-Agents**: Handle specific tasks (e.g., weather, expenses, research) + +Example: A supervisor agent coordinates weather lookup and expense approval agents. -### What LLM providers does VoltAgent support? +### How do I add custom tools? -VoltAgent works with OpenAI, Anthropic, Google (Gemini), and other providers. Swap providers by changing config, not rewriting agent logic: +Use the `@voltagent/core` tool registry: ```typescript -import { openai } from "@ai-sdk/openai"; -import { anthropic } from "@ai-sdk/anthropic"; +import { VoltAgent, Agent } from "@voltagent/core"; +import { weatherTool } from "./tools"; const agent = new Agent({ - model: openai("gpt-4o-mini"), // or anthropic("claude-3-5-sonnet") + name: "Weather Agent", + tools: [weatherTool], }); ``` -### How do I add memory to my agent? +### What is MCP support? -```typescript -import { Memory } from "@voltagent/core"; -import { LibSQLMemoryAdapter } from "@voltagent/libsql"; +VoltAgent supports **Model Context Protocol (MCP)** servers: +- Connect to MCP servers without extra glue code +- Use existing MCP tools and resources +- Example: File system MCP, database MCP, custom MCP -const memory = new Memory({ - storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }), -}); +### How does memory work? -const agent = new Agent({ name: "my-agent", memory }); -``` +VoltAgent provides **durable memory adapters**: +- **LibSQL**: SQLite-based persistent storage +- **In-Memory**: Default, no persistence +- Custom adapters possible ### What is VoltOps Console? -VoltOps Console is the platform side of VoltAgent providing: -- **Observability**: Real-time traces, logs, memory inspection -- **Dashboard**: Performance metrics and system overview -- **Prompt Builder**: Design and test prompts -- **Deployment**: One-click GitHub integration -- **Triggers & Actions**: Webhooks, schedules, automation -- **Guardrails**: Safety boundaries and content filters -- **Evals**: Evaluation suites for testing agent behavior +VoltOps Console is the **production operations platform**: +- **Observability**: Trace agent runs, view logs +- **Automation**: Schedule workflows, set triggers +- **Deployment**: One-click cloud deployment +- **Evals**: Run evaluation suites +- **Guardrails**: Enforce content policies -[Try Live Demo](https://console.voltagent.dev/demo) +Options: Cloud (managed) or Self-Hosted. -### How do I create multi-agent systems? +### How do I use RAG? -VoltAgent supports Supervisors & Sub-Agents for multi-agent orchestration: +VoltAgent provides built-in RAG capabilities: ```typescript -const supervisor = new Agent({ - name: "supervisor", - instructions: "Coordinate specialized agents", - subAgents: [researchAgent, writerAgent, reviewAgent], +import { VoltAgent, Agent } from "@voltagent/core"; +import { retrieverAgent } from "./retriever"; + +const agent = new Agent({ + name: "RAG Agent", + retriever: retrieverAgent, }); ``` -The supervisor routes tasks and keeps sub-agents synchronized. +Or use **VoltAgent Knowledge Base** for managed RAG service. -### What are workflows? +### How do I add voice support? -Workflows are multi-step automations with suspend/resume capabilities: +VoltAgent provides built-in voice providers: ```typescript -const workflow = createWorkflowChain({ id: "approval" }) - .andThen({ execute: async ({ data, suspend }) => { - if (data.amount > 500) await suspend("Manager approval required"); - return { approved: true };\n }}) - .andThen({ execute: async ({ data }) => { - return { status: "approved" };\n }}); +import { VoltAgent, Agent } from "@voltagent/core"; +import { openai } from "@voltagent/voice-openai"; + +const agent = new Agent({ + name: "Voice Agent", + voice: { provider: openai() }, +}); ``` -### Does VoltAgent support MCP? +### How do I run evaluations? -Yes! VoltAgent has built-in MCP (Model Context Protocol) support: -- Connect to MCP servers without extra glue code -- Use `@voltagent/mcp-docs-server` to teach AI assistants about VoltAgent +Use the Evals system: -### Where can I find more resources? +```typescript +import { EvalSuite } from "@voltagent/evals"; -- **[Interactive Tutorial](https://voltagent.dev/tutorial/introduction/)**: Learn fundamentals -- **[Documentation](https://voltagent.dev/docs/)**: Guides and concepts -- **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Practical implementations -- **[Discord](https://s.voltagent.dev/discord)**: Community support +const suite = new EvalSuite({ + name: "Weather Agent Eval", + tests: [...], +}); ---- +await suite.run(); +``` -## Contribution +### What guardrails are available? -We welcome contributions! Please refer to the contribution guidelines (link needed if available). Join our [Discord](https://s.voltagent.dev/discord) server for questions and discussions. +VoltAgent provides runtime guardrails: +- **Input Guardrails**: Validate agent input +- **Output Guardrails**: Validate agent output +- Content policy enforcement +- Custom validation rules -## Contributor ♥️ Thanks +### Can I use VoltAgent without VoltOps Console? -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. +Yes! The **core framework** is open-source and works standalone: +- Build agents with all features +- Deploy manually or use VoltOps Console later +- Console is optional for production operations -VoltAgent is a community effort, and it keeps getting better because of people like you. +### Where can I get help? + +- 📖 [Documentation](https://voltagent.dev/docs/) +- 💬 [Discord Community](https://s.voltagent.dev/discord) +- 🐛 [GitHub Issues](https://github.com/voltagent/voltagent/issues) +- 📧 [Twitter](https://x.com/voltagent_dev) -![Contributors](https://contrib.rocks/image?repo=voltagent/voltagent&max=500&columns=20&anon=1) ## License From c0f8a8de28bd0902cf50be4738d115b23a59b766 Mon Sep 17 00:00:00 2001 From: meichuanyi <35057768+meichuanyi@users.noreply.github.com> Date: Wed, 20 May 2026 17:14:46 +0800 Subject: [PATCH 3/3] docs: Add FAQ section --- README.md | 606 ++++++++++++------------------------------------------ 1 file changed, 126 insertions(+), 480 deletions(-) diff --git a/README.md b/README.md index f0c9f46ed..811926c65 100644 --- a/README.md +++ b/README.md @@ -1,519 +1,165 @@ -
- -voltagent - -

-AI Agent Engineering Platform -

- -
-English | 繁體中文 | 简体中文 | 日本語 | 한국어 -
- -
- -
- Home Page | - Documentation | - Examples -
-
- -
- -
- -[![GitHub issues](https://img.shields.io/github/issues/voltagent/voltagent)](https://github.com/voltagent/voltagent/issues) -[![GitHub pull requests](https://img.shields.io/github/issues-pr/voltagent/voltagent)](https://github.com/voltagent/voltagent/pulls) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md) -[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) - -[![npm downloads](https://img.shields.io/npm/dm/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core) -[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord) -[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://x.com/voltagent_dev) - -
+## ❓ FAQ -

-⭐ Like what we're doing? Give us a star ⬆️ -

+### What is VoltAgent? -VoltAgent is an end-to-end AI Agent Engineering Platform that consists of two main parts: +VoltAgent is an **end-to-end AI Agent Engineering Platform** consisting of two main parts: -- **[Open-Source TypeScript Framework](#core-framework)** – Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow, and more. -- **[VoltOps Console](#voltops-console)** `Cloud` `Self-Hosted` – Observability, Automation, Deployment, Evals, Guardrails, Prompts, and more. +- **Open-Source TypeScript Framework** – Memory, RAG, Guardrails, Tools, MCP, Voice, Workflow, and more. +- **VoltOps Console** (Cloud/Self-Hosted) – Observability, Automation, Deployment, Evals, Guardrails, Prompts, and more. 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](https://voltagent.dev/docs/agents/overview/) (`@voltagent/core`)**: Define agents with typed roles, tools, memory, and model providers in one place so everything stays organized. -- **[Workflow Engine](https://voltagent.dev/docs/workflows/overview/)**: Describe multi-step automations declaratively rather than stitching together custom control flow. -- **[Supervisors & Sub-Agents](https://voltagent.dev/docs/agents/sub-agents/)**: Run teams of specialized agents under a supervisor runtime that routes tasks and keeps them in sync. -- **[Tool Registry](https://voltagent.dev/docs/agents/tools/) & [MCP](https://voltagent.dev/docs/agents/mcp/)**: Ship Zod-typed tools with lifecycle hooks and cancellation, and connect to [Model Context Protocol](https://modelcontextprotocol.io/) servers without extra glue code. -- **[LLM Compatibility](https://voltagent.dev/docs/getting-started/providers-models/)**: Swap between OpenAI, Anthropic, Google, or other providers by changing config, not rewriting agent logic. -- **[Memory](https://voltagent.dev/docs/agents/memory/overview/)**: Attach durable memory adapters so agents remember important context across runs. -- **[Resumable Streaming](https://voltagent.dev/docs/agents/resumable-streaming/)**: Let clients reconnect to in-flight streams after refresh and continue receiving the same response. -- **[Retrieval & RAG](https://voltagent.dev/docs/rag/overview/)**: Plug in retriever agents to pull facts from your data sources and ground responses (RAG) before the model answers. -- **[VoltAgent Knowledge Base](https://voltagent.dev/docs/rag/voltagent/)**: Use the managed RAG service for document ingestion, chunking, embeddings, and search. -- **[Voice](https://voltagent.dev/docs/agents/voice/)**: Add text-to-speech and speech-to-text capabilities with OpenAI, ElevenLabs, or custom voice providers. -- **[Guardrails](https://voltagent.dev/docs/guardrails/overview/)**: Intercept and validate agent input or output at runtime to enforce content policies and safety rules. -- **[Evals](https://voltagent.dev/docs/evals/overview/)**: 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](https://voltagent.dev/docs/getting-started/mcp-docs-server/) - -## ⚡ Quick Start - -Create a new VoltAgent project in seconds using the `create-voltagent-app` CLI tool: +### How does VoltAgent differ from other agent frameworks? +| Feature | VoltAgent | LangChain | CrewAI | +|---------|-----------|-----------|--------| +| Language | TypeScript | Python | Python | +| Architecture | Core + Console | Library | Multi-agent | +| Observability | VoltOps Console | LangSmith | Built-in | +| Deployment | One-click | Manual | Manual | +| Memory | Pluggable adapters | In-memory | Memory class | +| RAG | Built-in VoltAgent KB | External | External | +| Voice | Native support | External | External | +| MCP | Native integration | External | External | +| Guardrails | Built-in | External | External | +| Evals | Built-in suites | External | External | + +### Core Framework Features + +| Feature | Description | +|---------|-------------| +| **Core Runtime** (`@voltagent/core`) | Typed roles, tools, memory, model providers | +| **Workflow Engine** | Multi-step declarative automations | +| **Supervisors & Sub-Agents** | Specialized agents under supervisor coordination | +| **Tool Registry & MCP** | Zod-typed tools with lifecycle hooks, MCP integration | +| **LLM Compatibility** | Swap between OpenAI, Anthropic, Google by config | +| **Memory** | Durable memory adapters (LibSQL, etc.) | +| **Resumable Streaming** | Reconnect to in-flight streams | +| **Retrieval & RAG** | Pull facts from data sources, ground responses | +| **VoltAgent Knowledge Base** | Managed RAG service for document ingestion | +| **Voice** | TTS/STT with OpenAI, ElevenLabs, custom providers | +| **Guardrails** | Intercept and validate input/output | +| **Evals** | Run agent eval suites alongside workflows | + +### VoltOps Console Features + +| Feature | Description | +|---------|-------------| +| **Observability & Tracing** | Deep execution traces and performance metrics | +| **Dashboard** | Agent/workflow/system overview | +| **Logs** | Detailed execution logs | +| **Memory Management** | Inspect agent memory and conversation history | +| **Traces** | Complete execution analysis | +| **Prompt Builder** | Design and test prompts in console | +| **Deployment** | One-click GitHub integration | +| **Triggers & Actions** | Webhooks, schedules, custom triggers | +| **Monitoring** | Health, performance, resource metrics | +| **Guardrails** | Safety boundaries and content filters | +| **Evals** | Test agent behavior against benchmarks | +| **RAG (Knowledge Base)** | Built-in retrieval-augmented generation | + +### What TypeScript/Node.js version is required? + +- **Node.js**: 18+ (recommended) +- **TypeScript**: 5.0+ +- Works with npm, yarn, pnpm + +### What LLM providers are supported? + +| Provider | Package | Model Example | +|----------|---------|---------------| +| OpenAI | `@ai-sdk/openai` | `gpt-4o-mini`, `gpt-4o` | +| Anthropic | `@ai-sdk/anthropic` | `claude-sonnet-4-20250514` | +| Google | `@ai-sdk/google` | `gemini-2.0-flash` | +| Azure | `@ai-sdk/azure` | Azure OpenAI deployments | +| Custom | `@ai-sdk/provider` | Custom provider integration | + +### How do I get started? + +**Quick Start:** ```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: - +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: - -``` -══════════════════════════════════════════════════ -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](https://console.voltagent.dev) 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](thumbnail.png)](https://github.com/user-attachments/assets/26340c6a-be34-48a5-9006-e822bf6098a7) - -### 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: - -```typescript -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](thumbnail.png)](https://github.com/user-attachments/assets/3d3ea67b-4ab5-4dc0-932d-cedd92894b18) - -1. **Go to the Workflows Page:** After starting your server, go directly to the [Workflows page](https://console.voltagent.dev/workflows). -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](https://github.com/VoltAgent/voltagent/tree/main/examples). - -- **[Airtable Agent](https://voltagent.dev/examples/guides/airtable-agent)** - React to new records and write updates back into Airtable with VoltOps actions. -- **[Slack Agent](https://voltagent.dev/examples/guides/slack-agent)** - Respond to channel messages and reply via VoltOps Slack actions. -- **[ChatGPT App With VoltAgent](https://voltagent.dev/examples/agents/chatgpt-app)** - Deploy VoltAgent over MCP and connect to ChatGPT Apps. -- **[WhatsApp Order Agent](https://voltagent.dev/examples/agents/whatsapp-ai-agent)** - Build a WhatsApp chatbot that handles food orders through natural conversation. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-whatsapp)) -- **[YouTube to Blog Agent](https://voltagent.dev/examples/agents/youtube-blog-agent)** - Convert YouTube videos into Markdown blog posts using a supervisor agent with MCP tools. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-youtube-to-blog)) -- **[AI Ads Generator Agent](https://voltagent.dev/examples/agents/ai-instagram-ad-agent)** - Generate Instagram ads using BrowserBase Stagehand and Google Gemini AI. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-ad-creator)) -- **[AI Recipe Generator Agent](https://voltagent.dev/examples/agents/recipe-generator)** - Create personalized cooking suggestions based on ingredients and preferences. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-recipe-generator) | [Video](https://youtu.be/KjV1c6AhlfY)) -- **[AI Research Assistant Agent](https://voltagent.dev/examples/agents/research-assistant)** - Multi-agent research workflow for generating comprehensive reports. ([Source](https://github.com/VoltAgent/voltagent/tree/main/examples/with-research-assistant) | [Video](https://youtu.be/j6KAUaoZMy4)) - -

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](https://console.voltagent.dev/demo) - -📖 [VoltOps Documentation](https://voltagent.dev/voltops-llm-observability-docs/) - -🚀 [VoltOps Platform](https://voltagent.dev/voltops-llm-observability/) - -### 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](https://cdn.voltagent.dev/console/logs.png) - -### Memory Management - -Inspect and manage agent memory, context, and conversation history. - -![VoltOps Memory Overview](https://cdn.voltagent.dev/console/memory.png) - -### Traces - -Analyze complete execution traces to understand agent behavior and optimize performance. - -![VoltOps Traces](https://cdn.voltagent.dev/console/traces.png) - -### 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](https://voltagent.dev/docs/deployment/voltops/) +Visit [VoltOps Console](https://console.voltagent.dev) to interact with your agent. -### 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 - -- **[Start with interactive tutorial](https://voltagent.dev/tutorial/introduction/)** to learn the fundamentals building AI Agents. -- **[Documentation](https://voltagent.dev/docs/)**: Dive into guides, concepts, and tutorials. -- **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)**: Explore practical implementations. -- **[Blog](https://voltagent.dev/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](https://s.voltagent.dev/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](https://contrib.rocks/image?repo=voltagent/voltagent&max=500&columns=20&anon=1) - -## ❓ FAQ - -### What is VoltAgent? - -VoltAgent is an end-to-end **AI Agent Engineering Platform** that provides: -- **Open-Source TypeScript Framework**: Build agents with memory, tools, workflows, voice, and RAG -- **VoltOps Console**: Production-ready observability, automation, deployment, and evaluations - -### How is VoltAgent different from other agent frameworks? - -| Feature | VoltAgent | LangChain | CrewAI | -|---------|-----------|-----------|--------| -| **Architecture** | TypeScript-first | Python-first | Python-first | -| **Workflow Engine** | Declarative workflows | Sequential chains | Role-playing teams | -| **Memory** | Multiple adapters | In-memory + options | Shared memory | -| **Observability** | Built-in VoltOps Console | External tools | Limited | -| **Deployment** | One-click cloud | Manual setup | Manual setup | -| **Voice Support** | Built-in TTS/STT | External providers | No | - -### How do I install VoltAgent? +### How do I use the MCP Docs Server? +Install the MCP docs server to teach your LLM how to use VoltAgent: ```bash -npm create voltagent-app@latest +npm install @voltagent/mcp-docs-server ``` -This creates a new project with starter code and examples. - -### Which LLM providers are supported? - -VoltAgent supports all major providers through AI SDK: -- **OpenAI**: GPT-4, GPT-4o, o1, o3-mini -- **Anthropic**: Claude 3.5, Claude Sonnet 4 -- **Google**: Gemini 1.5 Pro, Gemini 2.0 Flash -- **Groq**: Llama, Mixtral (fast inference) -- **Custom**: Any provider supported by AI SDK - -### What are Supervisors and Sub-Agents? - -VoltAgent supports **multi-agent systems** where: -- **Supervisor**: Routes tasks to specialized sub-agents -- **Sub-Agents**: Handle specific tasks (e.g., weather, expenses, research) - -Example: A supervisor agent coordinates weather lookup and expense approval agents. - -### How do I add custom tools? - -Use the `@voltagent/core` tool registry: - -```typescript -import { VoltAgent, Agent } from "@voltagent/core"; -import { weatherTool } from "./tools"; - -const agent = new Agent({ - name: "Weather Agent", - tools: [weatherTool], -}); -``` - -### What is MCP support? - -VoltAgent supports **Model Context Protocol (MCP)** servers: -- Connect to MCP servers without extra glue code -- Use existing MCP tools and resources -- Example: File system MCP, database MCP, custom MCP - -### How does memory work? - -VoltAgent provides **durable memory adapters**: -- **LibSQL**: SQLite-based persistent storage -- **In-Memory**: Default, no persistence -- Custom adapters possible - -### What is VoltOps Console? - -VoltOps Console is the **production operations platform**: -- **Observability**: Trace agent runs, view logs -- **Automation**: Schedule workflows, set triggers -- **Deployment**: One-click cloud deployment -- **Evals**: Run evaluation suites -- **Guardrails**: Enforce content policies - -Options: Cloud (managed) or Self-Hosted. - -### How do I use RAG? - -VoltAgent provides built-in RAG capabilities: - -```typescript -import { VoltAgent, Agent } from "@voltagent/core"; -import { retrieverAgent } from "./retriever"; - -const agent = new Agent({ - name: "RAG Agent", - retriever: retrieverAgent, -}); +Configure your AI assistant (Claude Desktop, Cursor, Windsurf): +```json +{ + "mcpServers": { + "voltagent": { + "command": "npx", + "args": ["-y", "@voltagent/mcp-docs-server"] + } + } +} ``` -Or use **VoltAgent Knowledge Base** for managed RAG service. - -### How do I add voice support? +### What is the Memory system? -VoltAgent provides built-in voice providers: +VoltAgent supports pluggable memory adapters: +- **LibSQL Memory Adapter** (`@voltagent/libsql`) – Persistent SQLite storage +- **In-memory** – Default, no persistence +- **Custom adapters** – Implement your own storage -```typescript -import { VoltAgent, Agent } from "@voltagent/core"; -import { openai } from "@voltagent/voice-openai"; - -const agent = new Agent({ - name: "Voice Agent", - voice: { provider: openai() }, -}); -``` +Memory persists important context across agent runs. -### How do I run evaluations? +### What is RAG in VoltAgent? -Use the Evals system: +RAG (Retrieval-Augmented Generation) allows agents to: +- Pull facts from your data sources +- Ground responses before the model answers +- Use **VoltAgent Knowledge Base** for managed ingestion, chunking, embeddings, search -```typescript -import { EvalSuite } from "@voltagent/evals"; +### What are Guardrails? -const suite = new EvalSuite({ - name: "Weather Agent Eval", - tests: [...], -}); +Guardrails intercept and validate agent input/output at runtime: +- Content policy enforcement +- Safety rules +- Output validation -await suite.run(); -``` +### What are Evals? -### What guardrails are available? +Evals run agent evaluation suites alongside workflows: +- Measure agent behavior +- Test accuracy against benchmarks +- Improve performance -VoltAgent provides runtime guardrails: -- **Input Guardrails**: Validate agent input -- **Output Guardrails**: Validate agent output -- Content policy enforcement -- Custom validation rules +### What languages are supported? -### Can I use VoltAgent without VoltOps Console? +VoltAgent documentation is available in: +- English (default) +- [繁體中文](i18n/README-cn-traditional.md) +- [简体中文](i18n/README-cn-bsc.md) +- [日本語](i18n/README-jp.md) +- [한국어](i18n/README-kr.md) -Yes! The **core framework** is open-source and works standalone: -- Build agents with all features -- Deploy manually or use VoltOps Console later -- Console is optional for production operations +### Where can I learn more? -### Where can I get help? +- **[Interactive Tutorial](https://voltagent.dev/tutorial/introduction/)** – Learn fundamentals +- **[Documentation](https://voltagent.dev/docs/)** – Guides, concepts, tutorials +- **[Examples](https://github.com/voltagent/voltagent/tree/main/examples)** – Practical implementations +- **[Blog](https://voltagent.dev/blog/)** – Technical insights and best practices -- 📖 [Documentation](https://voltagent.dev/docs/) -- 💬 [Discord Community](https://s.voltagent.dev/discord) -- 🐛 [GitHub Issues](https://github.com/voltagent/voltagent/issues) -- 📧 [Twitter](https://x.com/voltagent_dev) +### License +MIT License – See [LICENSE](LICENSE) for details. -## License +### Help Resources -Licensed under the MIT License, Copyright © 2026-present VoltAgent. +- **Discord**: [Join community](https://s.voltagent.dev/discord) +- **GitHub Issues**: [Report bugs](https://github.com/VoltAgent/voltagent/issues) +- **GitHub Discussions**: [Ask questions](https://github.com/VoltAgent/voltagent/discussions)