
voltagent-best-practices
VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability.
16stars
10forks
Updated 1/27/2026
Related Skills
SKILL.md
read-only
name
voltagent-best-practices
description
VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability.
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
memoryfor a shared default across agents and workflows. - Use
agentMemoryorworkflowMemorywhen defaults need to differ.
Server Options
- Use
@voltagent/server-honofor Node HTTP servers. - Use
@voltagent/server-elysiaas an alternative Node server provider. - Use
serverlessprovider for fetch runtimes (Cloudflare, Netlify).
Observability Notes
- Use
VoltOpsClientorcreateVoltAgentObservabilityfor tracing. - VoltAgent will auto-configure VoltOps if
VOLTAGENT_PUBLIC_KEYandVOLTAGENT_SECRET_KEYare 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.stringifyinside VoltAgent packages. UsesafeStringifyfrom@voltagent/internal.





