VoltAgent Best Practices

Choosing Agent or Workflow

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",
});

provider/model

openai/gpt-4o-mini

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

• 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