voltagent-best-practices

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

• https://voltagent.dev/docs
• https://github.com/voltagent/voltagent
• https://github.com/voltagent/voltagent/tree/main/examples