| name | voltagent-best-practices |
| description | VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability. |
| license | MIT |
| metadata | {"author":"VoltAgent","version":"1.0.0","repository":"https://github.com/VoltAgent/skills"} |
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.
Resources
