Agent skill

voltagent-best-practices

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

View SKILL.md on GitHub Repository
Stars 9
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/VoltAgent/skills/tree/main/skills/voltagent-best-practices

Metadata

Additional technical details for this skill

author
VoltAgent
version
1.0.0
repository
https://github.com/VoltAgent/skills

SKILL.md

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

typescript
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

typescript
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

typescript
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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

VoltAgent/skills

voltagent-docs-bundle

Look up VoltAgent documentation embedded in node_modules/@voltagent/core/docs for version-matched docs. Use for API signatures, guides, and examples.

9 1
Explore
VoltAgent/skills

create-voltagent

Skill for creating AI agent projects using the VoltAgent framework. Guide for CLI setup and manual bootstrapping.

9 1
Explore
VoltAgent/skills

voltagent-core-reference

9 1
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results