Run a first voltagent example
Run a first voltagent example: AI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework
Start with the smallest workflow described by the README for voltagent. Complete installation and configuration first.
Quick Start
Create a new VoltAgent project in seconds using the create-voltagent-app CLI tool:
npm create voltagent-app@latestThis 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.
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";
// Create a logger instance
const logger = createPinoLogger({
name: "my-agent-app",
level: "info",
});
// Optional persistent memory (remove to use default in-memory)
const memory = new Memory({
storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});
// A simple, general-purpose agent for the project.
const agent = new Agent({
name: "my-agent",
instructions: "A helpful assistant that can check weather and help with various tasks",
model: openai("gpt-4o-mini"),
tools: [weatherTool],
memory,
});
// Initialize VoltAgent with your agent(s) and workflow(s)
new VoltAgent({
agents: {
agent,
},
workflows: {
expenseApprovalWorkflow,
},
server: honoServer(),
logger,
});Afterwards, navigate to your project and run:
npm run devWhen 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
Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════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:
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 we're resuming with manager's decision
if (resumeData) {
return {
...data,
approved: resumeData.approved,
approvedBy: resumeData.managerId,
finalAmount: resumeData.adjustedAmount || data.amount,
};
}
// Check if manager approval is needed (expenses over $500)
if (data.amount > 500) {
await suspend("Manager approval required", {
employeeId: data.employeeId,
requestedAmount: data.amount,
});
}
// 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,
};
},
});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:
{ "employeeId": "EMP-123", "amount": 250, "category": "office-supplies", "description": "New laptop mouse and keyboard" } - View the Results: After execution, you can inspect the detailed logs for each step and see the final output directly in the console.
Verify your changes
The root manifest provides this check:
npm run testRead any errors before continuing. Build and type checks verify source consistency; exercise the README example to verify the behavior you need.
Next task
Read the usage guide for the documented components, configuration, and source layout.
Source and help
The catalog identifies the license as MIT. Read the repository license before redistributing source or assets.
This catalog entry is a fork. The README may describe upstream packages, domains, or release procedures; those destinations do not establish a separate release of this fork.
Source captured: 2026-10-11
