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) _

This command will ask you a few questions and automatically set up a VoltAgent project based on your preferences. Once the setup is complete, navigate to your project directory and start your application:

cd my-voltagent-app
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

  Developer Console:    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 VoltAgent Console 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 Console

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​

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": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "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

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

  Developer Console:    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 VoltAgent Console 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​

Table of Contents