Quick Start

Create a new VoltAgent project in seconds using the create-voltagent-app CLI tool:

1npm create voltagent-app@latest

This command guides you through setup.

You'll see the starter code in src/index.ts, which now registers both an agent and a comprehensive workflow example found in src/workflows/index.ts.

1import { VoltAgent, Agent, Memory } from "@voltagent/core";
2import { LibSQLMemoryAdapter } from "@voltagent/libsql";
3import { createPinoLogger } from "@voltagent/logger";
4import { honoServer } from "@voltagent/server-hono";
5import { openai } from "@ai-sdk/openai";
6import { expenseApprovalWorkflow } from "./workflows";
7import { weatherTool } from "./tools";
8 
9// Create a logger instance
10const logger = createPinoLogger({
11  name: "my-agent-app",
12  level: "info",
13});
14 
15// Optional persistent memory (remove to use default in-memory)
16const memory = new Memory({
17  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
18});
19 
20// A simple, general-purpose agent for the project.
21const agent = new Agent({
22  name: "my-agent",
23  instructions: "A helpful assistant that can check weather and help with various tasks",
24  model: openai("gpt-4o-mini"),
25  tools: [weatherTool],
26  memory,
27});
28 
29// Initialize VoltAgent with your agent(s) and workflow(s)
30new VoltAgent({
31  agents: {
32    agent,
33  },
34  workflows: {
35    expenseApprovalWorkflow,
36  },
37  server: honoServer(),
38  logger,
39});

Afterwards, navigate to your project and run:

1npm 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:

1══════════════════════════════════════════════════
2VOLTAGENT SERVER STARTED SUCCESSFULLY
3══════════════════════════════════════════════════
4✓ HTTP Server: http://localhost:3141
5
6Test your agents with VoltOps Console: https://console.voltagent.dev
7══════════════════════════════════════════════════

Your agent is now running! To interact with it:

Open the Console: Click the VoltOps LLM Observability Platform link in your terminal output (or copy-paste it into your browser).
Find Your Agent: On the VoltOps LLM Observability Platform page, you should see your agent listed (e.g., "my-agent").
Open Agent Details: Click on your agent's name.
Start Chatting: On the agent detail page, click the chat icon in the bottom right corner to open the chat window.
Send a Message: Type a message like "Hello" and press Enter.

Running Your First Workflow

Your new project also includes a powerful workflow engine.

The expense approval workflow demonstrates human-in-the-loop automation with suspend/resume capabilities:

1import { createWorkflowChain } from "@voltagent/core";
2import { z } from "zod";
3 
4export const expenseApprovalWorkflow = createWorkflowChain({
5  id: "expense-approval",
6  name: "Expense Approval Workflow",
7  purpose: "Process expense reports with manager approval for high amounts",
8 
9  input: z.object({
10    employeeId: z.string(),
11    amount: z.number(),
12    category: z.string(),
13    description: z.string(),
14  }),
15  result: z.object({
16    status: z.enum(["approved", "rejected"]),
17    approvedBy: z.string(),
18    finalAmount: z.number(),
19  }),
20})
21  // Step 1: Validate expense and check if approval needed
22  .andThen({
23    id: "check-approval-needed",
24    resumeSchema: z.object({
25      approved: z.boolean(),
26      managerId: z.string(),
27      comments: z.string().optional(),
28      adjustedAmount: z.number().optional(),
29    }),
30    execute: async ({ data, suspend, resumeData }) => {
31      // If we're resuming with manager's decision
32      if (resumeData) {
33        return {
34          ...data,
35          approved: resumeData.approved,
36          approvedBy: resumeData.managerId,
37          finalAmount: resumeData.adjustedAmount || data.amount,
38        };
39      }
40 
41      // Check if manager approval is needed (expenses over $500)
42      if (data.amount > 500) {
43        await suspend("Manager approval required", {
44          employeeId: data.employeeId,
45          requestedAmount: data.amount,
46        });
47      }
48 
49      // Auto-approve small expenses
50      return {
51        ...data,
52        approved: true,
53        approvedBy: "system",
54        finalAmount: data.amount,
55      };
56    },
57  })
58  // Step 2: Process the final decision
59  .andThen({
60    id: "process-decision",
61    execute: async ({ data }) => {
62      return {
63        status: data.approved ? "approved" : "rejected",
64        approvedBy: data.approvedBy,
65        finalAmount: data.finalAmount,
66      };
67    },
68  });

You can test the pre-built expenseApprovalWorkflow directly from the VoltOps console:

Go to the Workflows Page: After starting your server, go directly to the Workflows page.
Select Your Project: Use the project selector to choose your project (e.g., "my-agent-app").
Find and Run: You will see "Expense Approval Workflow" listed. Click it, then click the "Run" button.

Provide Input: The workflow expects a JSON object with expense details. Try a small expense for automatic approval:

1{
2  "employeeId": "EMP-123",
3  "amount": 250,
4  "category": "office-supplies",
5  "description": "New laptop mouse and keyboard"
6}

View the Results: After execution, you can inspect the detailed logs for each step and see the final output directly in the console.

Source captured: 2026-10-11

Quick Start

Create a new VoltAgent project in seconds using the create-voltagent-app CLI tool:

1npm create voltagent-app@latest

This command guides you through setup.

You'll see the starter code in src/index.ts, which now registers both an agent and a comprehensive workflow example found in src/workflows/index.ts.

1import { VoltAgent, Agent, Memory } from "@voltagent/core";
2import { LibSQLMemoryAdapter } from "@voltagent/libsql";
3import { createPinoLogger } from "@voltagent/logger";
4import { honoServer } from "@voltagent/server-hono";
5import { openai } from "@ai-sdk/openai";
6import { expenseApprovalWorkflow } from "./workflows";
7import { weatherTool } from "./tools";
8 
9// Create a logger instance
10const logger = createPinoLogger({
11  name: "my-agent-app",
12  level: "info",
13});
14 
15// Optional persistent memory (remove to use default in-memory)
16const memory = new Memory({
17  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
18});
19 
20// A simple, general-purpose agent for the project.
21const agent = new Agent({
22  name: "my-agent",
23  instructions: "A helpful assistant that can check weather and help with various tasks",
24  model: openai("gpt-4o-mini"),
25  tools: [weatherTool],
26  memory,
27});
28 
29// Initialize VoltAgent with your agent(s) and workflow(s)
30new VoltAgent({
31  agents: {
32    agent,
33  },
34  workflows: {
35    expenseApprovalWorkflow,
36  },
37  server: honoServer(),
38  logger,
39});

Afterwards, navigate to your project and run:

1npm 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:

1══════════════════════════════════════════════════
2VOLTAGENT SERVER STARTED SUCCESSFULLY
3══════════════════════════════════════════════════
4✓ HTTP Server: http://localhost:3141
5
6Test your agents with VoltOps Console: https://console.voltagent.dev
7══════════════════════════════════════════════════

Your agent is now running! To interact with it:

Open the Console: Click the VoltOps LLM Observability Platform link in your terminal output (or copy-paste it into your browser).
Find Your Agent: On the VoltOps LLM Observability Platform page, you should see your agent listed (e.g., "my-agent").
Open Agent Details: Click on your agent's name.
Start Chatting: On the agent detail page, click the chat icon in the bottom right corner to open the chat window.
Send a Message: Type a message like "Hello" and press Enter.

Running Your First Workflow

Your new project also includes a powerful workflow engine.

The expense approval workflow demonstrates human-in-the-loop automation with suspend/resume capabilities:

1import { createWorkflowChain } from "@voltagent/core";
2import { z } from "zod";
3 
4export const expenseApprovalWorkflow = createWorkflowChain({
5  id: "expense-approval",
6  name: "Expense Approval Workflow",
7  purpose: "Process expense reports with manager approval for high amounts",
8 
9  input: z.object({
10    employeeId: z.string(),
11    amount: z.number(),
12    category: z.string(),
13    description: z.string(),
14  }),
15  result: z.object({
16    status: z.enum(["approved", "rejected"]),
17    approvedBy: z.string(),
18    finalAmount: z.number(),
19  }),
20})
21  // Step 1: Validate expense and check if approval needed
22  .andThen({
23    id: "check-approval-needed",
24    resumeSchema: z.object({
25      approved: z.boolean(),
26      managerId: z.string(),
27      comments: z.string().optional(),
28      adjustedAmount: z.number().optional(),
29    }),
30    execute: async ({ data, suspend, resumeData }) => {
31      // If we're resuming with manager's decision
32      if (resumeData) {
33        return {
34          ...data,
35          approved: resumeData.approved,
36          approvedBy: resumeData.managerId,
37          finalAmount: resumeData.adjustedAmount || data.amount,
38        };
39      }
40 
41      // Check if manager approval is needed (expenses over $500)
42      if (data.amount > 500) {
43        await suspend("Manager approval required", {
44          employeeId: data.employeeId,
45          requestedAmount: data.amount,
46        });
47      }
48 
49      // Auto-approve small expenses
50      return {
51        ...data,
52        approved: true,
53        approvedBy: "system",
54        finalAmount: data.amount,
55      };
56    },
57  })
58  // Step 2: Process the final decision
59  .andThen({
60    id: "process-decision",
61    execute: async ({ data }) => {
62      return {
63        status: data.approved ? "approved" : "rejected",
64        approvedBy: data.approvedBy,
65        finalAmount: data.finalAmount,
66      };
67    },
68  });

You can test the pre-built expenseApprovalWorkflow directly from the VoltOps console:

Go to the Workflows Page: After starting your server, go directly to the Workflows page.
Select Your Project: Use the project selector to choose your project (e.g., "my-agent-app").
Find and Run: You will see "Expense Approval Workflow" listed. Click it, then click the "Run" button.

Provide Input: The workflow expects a JSON object with expense details. Try a small expense for automatic approval:

1{
2  "employeeId": "EMP-123",
3  "amount": 250,
4  "category": "office-supplies",
5  "description": "New laptop mouse and keyboard"
6}

View the Results: After execution, you can inspect the detailed logs for each step and see the final output directly in the console.

Source captured: 2026-10-11