voltagent-best-practices

voltagent-best-practices

VoltAgent architectural patterns and conventions. Covers agents vs workflows, project layout, memory, servers, and observability.

16stars
10forks
Updated 1/27/2026
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 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