VoltAgent Best Practices

Quick reference for VoltAgent conventions and patterns.

Choosing Agent or Workflow

Use	When
Agent	Open-ended tasks that require tool selection and adaptive reasoning
Workflow	Multi-step pipelines with explicit control flow and suspend/resume

Layout

src/
|-- index.ts
|-- agents/
|-- tools/
`-- workflows/

Quick Snippets

Basic Agent

import { Agent } from "@voltagent/core";

const agent = new Agent({
  name: "assistant",
  instructions: "You are helpful.",
  model: "openai/gpt-4o-mini",
});

Model format is provider/model (for example openai/gpt-4o-mini or anthropic/claude-3-5-sonnet).

Basic Workflow

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

const workflow = createWorkflowChain({
  id: "example",
  input: z.object({ text: z.string() }),
  result: z.object({ summary: z.string() }),
}).andThen({
  id: "summarize",
  execute: async ({ data }) => ({ summary: data.text }),
});

VoltAgent Bootstrap

import { VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";

new VoltAgent({
  agents: { agent },
  workflows: { workflow },
  server: honoServer(),
});

Memory Defaults

Use memory for a shared default across agents and workflows.
Use agentMemory or workflowMemory when defaults need to differ.

Server Options

Use @voltagent/server-hono for Node HTTP servers.
Use @voltagent/server-elysia as an alternative Node server provider.
Use serverless provider for fetch runtimes (Cloudflare, Netlify).

Observability Notes

Use VoltOpsClient or createVoltAgentObservability for tracing.
VoltAgent will auto-configure VoltOps if VOLTAGENT_PUBLIC_KEY and VOLTAGENT_SECRET_KEY are set.

Recipes

Short best-practice recipes live in the embedded docs:

packages/core/docs/recipes/
Search: rg -n "keyword" packages/core/docs/recipes -g"*.md"
Read: cat packages/core/docs/recipes/<file>.md

Footguns

Do not use JSON.stringify inside VoltAgent packages. Use safeStringify from @voltagent/internal.

voltagent-best-practices