Skip to main content
VoltAgent DocsVoltOps DocsExamplesChangelog
Quick Start

Create from scratch

Add VoltAgent to an existing TypeScript project. This guide walks through setting up the configuration, installing dependencies, and creating your first agent. To start from scratch, see Create with VoltAgent CLI guide.


1

Create Project Directory

Create a new project directory and initialize npm:

mkdir my-voltagent-project
cd my-voltagent-project
npm init -y
2

Configure TypeScript

Create a tsconfig.json file:

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

Add a tsdown.config.ts alongside tsconfig.json so production builds bundle correctly:

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: ["./src/index.ts"],
  sourcemap: true,
  outDir: "dist",
});
3

Install Dependencies

Install VoltAgent packages and development tools:

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

# Install dependencies
npm install @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3
4

Create Your Agent

Create the source directory and agent file:

mkdir src

Create src/index.ts:

src/index.ts
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono"; // HTTP server
import { LibSQLMemoryAdapter } from "@voltagent/libsql"; // For persistent memory
import { openai } from "@ai-sdk/openai"; // Example model
import { createPinoLogger } from "@voltagent/logger";

// Create logger (optional but recommended)
const logger = createPinoLogger({
  name: "my-agent",
  level: "info",
});

// Define a simple agent
const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant that answers questions without using tools",
  // VoltAgent uses ai-sdk directly - pick any ai-sdk model
  model: openai("gpt-4o-mini"),
  // Optional: Add persistent memory (remove this to use default in-memory storage)
  memory: new Memory({
    storage: new LibSQLMemoryAdapter({
      url: "file:./.voltagent/memory.db",
    }),
  }),
});

// Initialize VoltAgent with your agent(s)
new VoltAgent({
  agents: { agent },
  server: honoServer(), // Default port: 3141
  logger,
});
5

Configure Environment

Create a .env file and add your API key:

OPENAI_API_KEY=your-api-key-here
Get OpenAI API Key

Add the following to your package.json:

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

Your project structure should now look like this:

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

Run Your Agent

npm run dev

You should see the VoltAgent server startup message:

══════════════════════════════════════════════════
  VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
  ✓ HTTP Server:  http://localhost:3141
  ↪ Share it:    pnpm volt tunnel 3141 (secure HTTPS tunnel for teammates)
     Docs: https://voltagent.dev/docs/deployment/local-tunnel/
  ✓ Swagger UI:   http://localhost:3141/ui

  Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════
7

Test Your Agent

Open https://console.voltagent.dev and click Agents & Workflows in the sidebar to find your agent.

Select it, click the chat icon in the bottom right corner, and try sending a message like "Hello".

You should receive a response from your AI agent. The dev script uses tsx watch, so it will automatically restart if you make changes to your code.

Next Steps​

  • Tutorial - Build agents with tools, memory, and integrations
  • Agent Configuration - Agent options and settings
  • Memory - Conversation history and persistence
  • Tools - Create custom tools for your agent

Table of Contents