VoltAgent

# VoltAgent: The Comprehensive Developer & LLM Guide (v1.0.x) This document provides an exhaustive, self-contained guide to the VoltAgent framework (version 1.x). It is intended for both human developers seeking deep understanding and Large Language Models (LLMs) requiring rich context for analysis, code generation, or answering questions about VoltAgent. It details the architecture, core components, features, design rationale, key workflows, and provides illustrative code examples directly within the text. While links to source code and further documentation are provided, the core concepts and mechanisms are explained herein. **Framework Overview:** > VoltAgent is an open-source TypeScript framework designed for building, orchestrating, and observing sophisticated AI agents. It bridges the gap between the flexibility of pure code and the clarity of visual/no-code tools, providing structure without sacrificing control. Built specifically for the JavaScript/TypeScript ecosystem, VoltAgent empowers developers with modular components (Agents, Tools, Memory, RAG, Voice, Sub-agents) and integrates first-class observability through the dedicated VoltAgent VoltOps Platform. **Core Philosophy (Manifesto TL;DR):** VoltAgent exists because building robust AI agents in JS/TS was harder than it needed to be. Existing solutions were often either too basic (requiring extensive boilerplate and lacking observability) or too restrictive (no-code platforms limiting customization and provider choice). VoltAgent aims to provide: 1. **Developer Experience:** A code-first approach familiar to JS/TS developers, leveraging TypeScript for type safety. 2. **Structure & Modularity:** Pre-built components and patterns for common agent tasks (tools, memory, multi-agent coordination). 3. **Observability:** Deep, visual insight into agent execution via the VoltOps Platform to combat the "black box" problem. 4. **Flexibility:** Easy integration with various LLM providers and external services, avoiding vendor lock-in. * `[Project Manifesto](/website/pages/manifesto.tsx)`: Full philosophy. * `[Root README](/README.md)`: High-level project overview. --- ## 1. Project Setup & Quick Start ### 1.1. `create-voltagent-app` (Recommended) The quickest way to initialize a VoltAgent project is via the dedicated CLI tool. **Command:** ```bash # Installs necessary dependencies and sets up the basic structure npm create voltagent-app@latest my-voltagent-app # Follow prompts for package manager selection (npm/yarn/pnpm) cd my-voltagent-app # Add API keys to the generated .env file echo "OPENAI_API_KEY=sk-..." > .env # Example for OpenAI # Start the development server npm run dev ``` **Rationale:** This tool ensures all necessary core packages (`@voltagent/core`, `ai` + an ai-sdk provider like `@ai-sdk/openai`, and optionally `@voltagent/server-hono`), TypeScript configuration (`tsconfig.json`), basic scripts (`package.json`), and initial file structure (`src/index.ts`) are correctly set up, including the `.voltagent` directory for local SQLite databases. **Default Project Structure Generated:** ``` my-voltagent-app/ ├── src/ │ └── index.ts # Main agent definition and framework initialization ├── .voltagent/ # Default directory for local SQLite databases (memory/observability) ├── .env # Environment variables (API keys) ├── .gitignore ├── package.json # Project metadata, dependencies, scripts ├── tsconfig.json # TypeScript configuration └── README.md # Basic project README ``` The `npm run dev` command utilizes `tsx watch` for hot-reloading during development, automatically restarting the server on code changes. The server typically runs on `http://localhost:3141`. **More Info:** * `[Quick Start Guide](/docs/getting-started/quick-start.md)` * `[create-voltagent-app README](/packages/create-voltagent-app/README.md)` * `[Project Creator Source](/packages/create-voltagent-app/src/project-creat […truncated]