Voltagent best practices
VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability.From its SKILL.md
npx -y skills add VoltAgent/skills --skill voltagent-best-practicesAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 17 stars17 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
2.6 KB, 623 tokens by cl100k_base, as published. Nobody here has run it
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.