Skip to main content

Quick Start

There are two ways to create a VoltAgent application: Automatic setup or manual setup. While both work, the automatic setup provides the smoothest experience, especially for new users.

You can quickly create a new project using the create-voltagent-app CLI tool:

npm create voltagent-app@latest my-agent-app

After running the command, you'll see the VoltAgent Generator welcome screen:

 _    __      ____  ___                    __
| |  / /___  / / /_/   | ____ ____  ____  / /_
| | / / __ \/ / __/ /| |/ __ `/ _ \/ __ \/ __/
| |/ / /_/ / / /_/ ___ / /_/ /  __/ / / / /_
|___/\____/_/\__/_/  |_\__, /\___/_/ /_/\__/
                      /____/

   ╭───────────────────────────────────────────────╮
   │                                               │
   │   Welcome to VoltAgent Generator!             │
   │                                               │
   │   Create powerful AI agents with VoltAgent.   │
   │                                               │
   ╰───────────────────────────────────────────────╯

Let's create your next AI application...


? What is your project named? (my-voltagent-app) _

The CLI will guide you through the setup process:

  1. Project Name: Choose a name for your project
  2. AI Provider: Select from OpenAI, Anthropic, Google, Groq, Mistral, or Ollama (local)
  3. API Key (optional): Enter your API key or skip to add it later
  4. Package Manager: Choose from installed package managers (npm, yarn, or pnpm)
  5. IDE Configuration: Optionally configure MCP Docs Server for your IDE

The tool will automatically:

  • Create project files and structure
  • Generate a .env file with your API key (if provided)
  • Initialize a git repository
  • Install dependencies Once the setup is complete, navigate to your project directory:
cd my-voltagent-app

Add Your API Key​

If you skipped API key entry during setup, create or edit the .env file in your project root and add your API key:

# For OpenAI
OPENAI_API_KEY=your-api-key-here

# For Anthropic
ANTHROPIC_API_KEY=your-api-key-here

# For Google
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key-here

# For Groq
GROQ_API_KEY=your-api-key-here

# For Mistral
MISTRAL_API_KEY=your-api-key-here

# For Ollama (no API key needed, runs locally)
# Make sure Ollama is installed and running

Get your API key:

Start Your Application​

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

  VoltOps Platform:    https://console.voltagent.dev
══════════════════════════════════════════════════
[VoltAgent] All packages are up to date

Your agent is now running! To interact with it:

  1. Open the Console: Click the 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.

VoltOps LLM Observability Platform

You should receive a response from your AI agent in the chat window. This confirms that your VoltAgent application is set up correctly and communicating with the LLM.

The dev script uses tsx watch, so it will automatically restart if you make changes to your code in the src directory. Press Ctrl+C in the terminal to stop the agent.

Explore and Run Your Workflow from the Console​

Your new project isn't just an agent; it's a powerful automation engine. We've included an expense approval workflow example to get you started, and you can run it directly from the VoltOps console.

This workflow demonstrates how to chain together all the core steps of VoltAgent:

  • Data Transformation (andThen)
  • AI Agent Calls (andAgent)
  • Parallel Processing (andAll)
  • Racing Operations (andRace)
  • Conditional Logic (andWhen)

How to Run the Workflow​

VoltOps Workflow Observability

  1. Go to the Workflows Page: After starting your server, go directly to the Workflows page.
  2. Select Your Project: Use the project selector on the page to choose your newly created project (e.g., "my-agent-app").
  3. Find and Run the Workflow: You will see "Expense Approval Workflow" listed. Click on it to open the detail page, then click the "Run" button.
  4. Provide Input: An input form will appear. The workflow expects a JSON object with expense details. Try one of the following inputs to see how it works:
    • For automatic approval (under $100):
{
  "amount": 75,
  "category": "office supplies",
  "description": "Notebooks and pens for team meeting"
}
  • For manual review (over $100):
{
  "amount": 450,
  "category": "equipment",
  "description": "New monitor for development workstation"
}
  1. View the Results: After execution, you can inspect the detailed logs for each step and see the final output directly in the console.

This interactive experience is a great way to understand how to build and test complex automations with VoltAgent without needing to modify your code for every run.

Next Steps​

Ready to build real AI agents? Follow our step-by-step tutorial:

  • Start the Tutorial - Learn to build agents with tools, memory, and real-world integrations

Or explore specific topics:

Manual Setup​

Follow these steps to create a new TypeScript project and add VoltAgent:

Create a new project directory:

mkdir my-voltagent-project
cd my-voltagent-project

Initialize a new npm project:

npm init -y

Create a basic TypeScript configuration file (tsconfig.json):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "outDir": "dist",
    "strict": true
  },
  "include": ["src"]
}

Install Dependencies​

# Install development dependencies
npm install --save-dev typescript tsx @types/node @voltagent/cli

# Install dependencies
npm install @voltagent/core @voltagent/vercel-ai @ai-sdk/openai zod@^3.25.0

Create a source directory:

mkdir src

Create a basic agent in src/index.ts:

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,
  },
});

Create a .env file and add your OpenAI API key:

# Make sure to replace 'your_openai_api_key' with your actual key
OPENAI_API_KEY=your_openai_api_key

Add the following to your package.json:

"type": "module",
"scripts": {
  "build": "tsc",
  "dev": "tsx watch --env-file=.env ./src",
  "start": "node dist/index.js",
  "volt": "volt" // Requires @voltagent/cli
}

Your project structure should now look like this:

my-voltagent-project/
├── node_modules/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
├── .env
└── .voltagent/ (created automatically when you run the agent)

Run Your Agent​

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

  VoltOps Platform:    https://console.voltagent.dev
══════════════════════════════════════════════════
[VoltAgent] All packages are up to date

Your agent is now running! To interact with it:

  1. Open the Console: Click the 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.

[Placeholder for GIF showing Console interaction: Finding agent, clicking chat, sending message]

You should receive a response from your AI agent in the chat window. This confirms that your VoltAgent application is set up correctly and communicating with the LLM.

The dev script uses tsx watch, so it will automatically restart if you make changes to your code in the src directory. Press Ctrl+C in the terminal to stop the agent.

Next Steps​

Ready to build real AI agents? Follow our step-by-step tutorial:

  • Start the Tutorial - Learn to build agents with tools, memory, and real-world integrations

Or explore specific topics:

Table of Contents