Skip to main content
VoltAgent DocsRecipes & GuidesVoltOps DocsExamplesChangelog
Quick Start

Create with VoltAgent CLI

Build your first AI agent with VoltAgent. This guide covers creating an agent, connecting it to external events, running workflows, and deploying to production.

Looking for full recipes? Check out the Recipes & Guides section.


1

Create New Project

Run the following command to create a new VoltAgent project:

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

The CLI will prompt you for project name, AI provider, and API key. Once complete:

cd my-agent-app
requirement

Be sure your environment is running Node.js 20.19 or newer so the generated tsdown build works without ESM resolution issues.

2

Configure and Start

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

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

Now start the development server:

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
══════════════════════════════════════════════════
3

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 asking "What's the weather in San Francisco?"

You should receive a response, you've successfully created your first basic AI agent that understand and generate responses.

Enterprise Support + Self-hosted

For teams that need to self-host VoltAgent Console. We also offer enterprise support:

• Deploy with Docker or Kubernetes on any cloud provider
• Slack Priority Support
• Unlimited tracing & role-based access control
• Works with AWS, GCP, Azure, or on-premise environments
• Connect to your existing auth and security infrastructure
• Custom MSA
Contact us for enterprise

Up to this point, you created and tested a basic working AI agent. The next steps show how to connect it to external events, services, and using workflows.

4

Add Triggers and Actions (Optional)

You now have a working AI agent that responds to messages. VoltAgent also supports event-driven workflows.

Together, they let your agent react to events and take actions automatically.

The diagram below shows an event-driven agent example: a GitHub star event triggers the agent, which generates a message and sends it to Discord.

Workflow diagram

Workflow steps:

  1. Trigger - Captures a GitHub star webhook event
  2. AI Agent - Generates a message based on the event
  3. Action - Sends the message to Discord

To implement this workflow with your agent, go to the VoltAgent Console Get Started Guide and continue from Step 4.



5

Run a Workflow

Running Your First Human-in-the-Loop Workflow​

Workflows chain multiple steps (data transformations, API calls, AI agent interactions) into a single execution. Unlike a standalone agent that responds to one message at a time, workflows coordinate multi-step processes.

The generated project includes an expense approval workflow that demonstrates suspend/resume functionality. Workflows can pause execution, wait for human input, and then continue.

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(),
  }),
})
  // Step 1: Validate expense and check if approval needed
  .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 resuming with manager's decision
      if (resumeData) {
        return {
          ...data,
          approved: resumeData.approved,
          approvedBy: resumeData.managerId,
          finalAmount: resumeData.adjustedAmount || data.amount,
        };
      }

      // Expenses over $500 require manager approval
      if (data.amount > 500) {
        await suspend("Manager approval required", {
          employeeId: data.employeeId,
          requestedAmount: data.amount,
          category: data.category,
        });
      }

      // Auto-approve small expenses
      return {
        ...data,
        approved: true,
        approvedBy: "system",
        finalAmount: data.amount,
      };
    },
  })
  // Step 2: Process the final decision
  .andThen({
    id: "process-decision",
    execute: async ({ data }) => {
      return {
        status: data.approved ? "approved" : "rejected",
        approvedBy: data.approvedBy,
        finalAmount: data.finalAmount,
      };
    },
  });



Run the example workflow​

Open the Workflows page in console, select "Expense Approval Workflow", and click "Test Workflow". Enter input and click "Execute Workflow".

This workflow simulates an expense approval process where certain decisions require human input before continuing:

  • Expenses under $500 are auto-approved by the system
  • Expenses over $500 trigger a suspend, pausing the workflow until a manager approves or rejects

Auto-approval example (under $500):

{
  "employeeId": "EMP-123",
  "amount": 250,
  "category": "office-supplies",
  "description": "New laptop mouse and keyboard"
}

Manual review example (over $500):

{
  "employeeId": "EMP-456",
  "amount": 750,
  "category": "travel",
  "description": "Flight tickets for client meeting"
}
Workflow Step Types

VoltAgent workflows support multiple step types:

  • andThen - sequential data transformation (used in this example)
  • andAgent - AI agent calls
  • andAll - parallel processing
  • andRace - racing operations
  • andWhen - conditional logic
  • andTap - side effects without modifying data
6

Share Your Local Server

When you need to demo your agent remotely or receive external webhooks, install the VoltAgent CLI and open a tunnel:

Install the CLI (adds a volt script and dev dependency)
npx @voltagent/cli init

Then expose your local server:

pnpm volt tunnel 3141

The command prints an HTTPS URL (for example https://your-tunnel-address.tunnel.voltagent.dev) that forwards traffic to your local port until you press Ctrl+C. You can also run it ad‑hoc without installing dependencies:

Tip: skipping the port (pnpm volt tunnel) uses the default 3141.

npx @voltagent/cli tunnel 3141

See the Local Tunnel guide for details.

7

Build for Production

When you're ready to deploy, bundle the app and run the compiled JavaScript with Node:

npm run build
npm start

The build script invokes tsdown, which bundles your TypeScript entrypoint (and any sibling directories such as ./workflows or ./tools) into dist/index.js. This extra step keeps the Node ESM loader from throwing ERR_UNSUPPORTED_DIR_IMPORT while preserving extensionless imports during development.

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

To add VoltAgent to an existing project, see Create from scratch.