Create VoltAgent Skill

Complete guide for creating new VoltAgent projects. Includes the CLI flow and a full manual setup.

Official documentation: https://voltagent.dev/docs/

Start Here

When a user wants to create a VoltAgent project, ask:

"How would you like to create your VoltAgent project?"

Automatic Setup - run npm create voltagent-app@latest and handle prompts Interactive Guide - walk through each step and confirm choices Manual Installation - set up dependencies and a full working example

Based on their choice:

Option 1: run the CLI, capture server and provider choices, and finish setup Option 2: gather server, provider, and API key, then run the CLI Option 3: follow the manual steps below Before You Start Node.js 20+ (>= 20.19.0 recommended) Git (optional, for auto git init) An API key for your model provider (not needed for Ollama) Fast Path

Create a new VoltAgent project with one command:

npm create voltagent-app@latest

Other package managers:

pnpm create voltagent-app@latest yarn create voltagent-app@latest bun create voltagent-app@latest

CLI Flow

The create-voltagent-app command:

Asks for a project name (default: my-voltagent-app) Prompts for a server framework (Hono or Elysia) Prompts for an AI provider (OpenAI, Anthropic, Google, Groq, Mistral, Ollama) Prompts for an API key when required Installs dependencies and scaffolds the project Writes .env, README.md, tsconfig.json, tsdown.config.ts, and Docker files Initializes a git repo when available CLI Walkthrough

Run:

npm create voltagent-app@latest

When prompted:

Choose a server (Hono recommended or Elysia) Choose an AI provider Enter your API key (skip if using Ollama)

Start the dev server:

cd npm run dev

If you chose Ollama:

ollama pull llama3.2

CLI Flags and Examples

Create in a specific directory:

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

Download an example from the VoltAgent repo:

npm create voltagent-app@latest -- --example with-workflow

pnpm / yarn / bun equivalents:

pnpm create voltagent-app@latest -- --example with-workflow yarn create voltagent-app@latest -- --example with-workflow bun create voltagent-app@latest -- --example with-workflow

Notes:

If you run the docs sync script in this repo, you may also see packages/core/docs generated.

Env Keys

The CLI writes .env with your provider key (or a placeholder). Common keys:

OPENAI_API_KEY=... ANTHROPIC_API_KEY=... GOOGLE_GENERATIVE_AI_API_KEY=... GROQ_API_KEY=... MISTRAL_API_KEY=... OLLAMA_HOST=http://localhost:11434

VOLTAGENT_PUBLIC_KEY=... VOLTAGENT_SECRET_KEY=...

Manual Setup (Full)

If you prefer not to use the CLI, follow these steps:

Step 1: Create the project directory mkdir my-voltagent-app && cd my-voltagent-app npm init -y mkdir -p src/tools src/workflows .voltagent

Step 2: Install dependencies

Choose one server package:

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-hono @voltagent/cli ai zod dotenv

npm install @voltagent/core @voltagent/libsql @voltagent/logger @voltagent/server-elysia @voltagent/cli ai zod dotenv

Dev dependencies:

npm install -D typescript tsx tsdown @types/node @biomejs/biome

Step 3: Add scripts to package.json { "scripts": { "dev": "tsx watch --env-file=.env ./src", "build": "tsdown", "start": "node dist/index.js", "lint": "biome check ./src", "lint:fix": "biome check --write ./src", "typecheck": "tsc --noEmit", "volt": "volt" } }

volt is the VoltAgent CLI. Use it for project utilities (for example init, deploy, eval, prompts, tunnel, update).

Step 4: Configure TypeScript

Create tsconfig.json:

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

Step 5: Add tsdown config

Create tsdown.config.ts:

import { defineConfig } from "tsdown";

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

Step 6: Create .env OPENAI_API_KEY=your-api-key-here VOLTAGENT_PUBLIC_KEY=your-public-key VOLTAGENT_SECRET_KEY=your-secret-key NODE_ENV=development

For Ollama:

OLLAMA_HOST=http://localhost:11434

Step 7: Create a tool

Create src/tools/weather.ts:

import { createTool } from "@voltagent/core"; import { z } from "zod";

export const weatherTool = createTool({ name: "getWeather", description: "Get the current weather for a specific location", parameters: z.object({ location: z.string().describe("City or location to get weather for"), }), execute: async ({ location }) => { return { weather: { location, temperature: 21, condition: "Sunny", humidity: 45, windSpeed: 8, }, message: Current weather in ${location}: 21 C and sunny., }; }, });

Create src/tools/index.ts:

export { weatherTool } from "./weather";

Step 8: Create a workflow

Create src/workflows/index.ts:

import { createWorkflowChain } from "@voltagent/core"; import { z } from "zod";

export const expenseApprovalWorkflow = createWorkflowChain({ id: "expense-approval", name: "Expense Approval Workflow", purpose: "Process expense reports with manager approval for high amounts", input: z.object({ employeeId: z.string(), amount: z.number(), category: z.string(), description: z.string(), }), result: z.object({ status: z.enum(["approved", "rejected"]), approvedBy: z.string(), finalAmount: z.number(), }), }) .andThen({ id: "check-approval-needed", resumeSchema: z.object({ approved: z.boolean(), managerId: z.string(), comments: z.string().optional(), adjustedAmount: z.number().optional(), }), execute: async ({ data, suspend, resumeData }) => { if (resumeData) { return { ...data, approved: resumeData.approved, approvedBy: resumeData.managerId, finalAmount: resumeData.adjustedAmount || data.amount, managerComments: resumeData.comments, }; }

  if (data.amount > 500) {
    await suspend("Manager approval required", {
      employeeId: data.employeeId,
      requestedAmount: data.amount,
      category: data.category,
    });
  }

  return {
    ...data,
    approved: true,
    approvedBy: "system",
    finalAmount: data.amount,
  };
},

}) .andThen({ id: "process-decision", execute: async ({ data }) => { return { status: data.approved ? "approved" : "rejected", approvedBy: data.approvedBy, finalAmount: data.finalAmount, }; }, });

Step 9: Create the entry point

Create src/index.ts:

import "dotenv/config"; import { Agent, Memory, VoltAgent, VoltAgentObservability, VoltOpsClient, } from "@voltagent/core"; import { LibSQLMemoryAdapter, LibSQLObservabilityAdapter } from "@voltagent/libsql"; import { createPinoLogger } from "@voltagent/logger"; import { honoServer } from "@voltagent/server-hono"; import { expenseApprovalWorkflow } from "./workflows"; import { weatherTool } from "./tools";

const logger = createPinoLogger({ name: "my-voltagent-app", level: "info" });

const memory = new Memory({ storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db", logger: logger.child({ component: "libsql" }), }), });

const observability = new VoltAgentObservability({ storage: new LibSQLObservabilityAdapter({ url: "file:./.voltagent/observability.db", }), });

const agent = new Agent({ name: "my-voltagent-app", instructions: "A helpful assistant that can check weather and help with various tasks", model: "openai/gpt-4o-mini", tools: [weatherTool], memory, });

new VoltAgent({ agents: { agent }, workflows: { expenseApprovalWorkflow }, server: honoServer(), logger, observability, voltOpsClient: new VoltOpsClient({ publicKey: process.env.VOLTAGENT_PUBLIC_KEY || "", secretKey: process.env.VOLTAGENT_SECRET_KEY || "", }), });

Model format is provider/model. Examples:

openai/gpt-4o-mini anthropic/claude-3-5-sonnet google/gemini-2.0-flash groq/llama-3.3-70b-versatile mistral/mistral-large-latest ollama/llama3.2

If you chose Elysia, replace honoServer with elysiaServer and update the import.

Step 10: Run the dev server npm run dev

安装