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-creator.ts)`
*   `[Base Template Source](/packages/create-voltagent-app/templates/base/)`

### 1.2. Manual Setup

While not recommended for beginners, manual setup involves:

1.  Initializing a Node.js/TypeScript project (`npm init`, `tsc --init`).
2.  Installing core dependencies: `@voltagent/core`, `ai`, and an ai-sdk provider package (e.g., `@ai-sdk/openai`, `@ai-sdk/anthropic`). Optionally add `@voltagent/server-hono` for HTTP server and `@voltagent/libsql` for persistent memory.
3.  Installing dev dependencies: `typescript`, `tsx`, `@types/node`, `@voltagent/cli` (optional).
4.  Configuring `tsconfig.json` (target ES2020+, module NodeNext).
5.  Configuring `package.json` (set `"type": "module"`, add `dev`/`start` scripts).
6.  Creating `src/index.ts` with Agent definition and `new VoltAgent({...})` initialization.
7.  Creating a `.env` file for API keys.

*Refer to the Quick Start Guide documentation for detailed manual steps.*

---

## 2. Core Architecture: The Agent and its Managers (`@voltagent/core`)

### 2.1. The `Agent` Class (`/packages/core/src/agent/index.ts`)

This is the central orchestrator in VoltAgent. **It is NOT merely a wrapper for an LLM API call.** Its responsibilities include:

*   **Configuration:** Holding the agent's identity (`name`, `description`), LLM connection (`llm`, `model`), and capabilities (`tools`, `memory`, `retriever`, `subAgents`, `hooks`, `voice`).
*   **Lifecycle Management:** Handling the start and end of interactions.
*   **Context Assembly:** Gathering system prompts, memory, and RAG results before calling the LLM.
*   **LLM Interaction:** Delegating the actual API call (text, object, streaming) to the configured `LLMProvider`.
*   **Tool Orchestration:** Interpreting LLM requests for tool use, managing the tool execution lifecycle via `ToolManager`, and feeding results back to the LLM.
*   **State Coordination:** Interacting with internal managers (`MemoryManager`, `SubAgentManager`, `HistoryManager`) to manage state and history.
*   **Event Emission:** Triggering events for observability (via `AgentEventEmitter`).

**Constructor Signature (Simplified):**