mcpField
V
voltagent-best-practices

voltagent-best-practices

github.com/voltagentAgent workflows16723 installsUpdated 39w ago
Repository

About voltagent-best-practices

A quick reference skill for VoltAgent conventions, helping developers choose between agents and workflows and apply project patterns. It also covers memory defaults, server options, observability, and common pitfalls.

Key features

  1. 01Agent と workflow の選び方
  2. 02プロジェクト構成の例
  3. 03メモリ設定の指針
  4. 04サーバーと監視の選択肢
  5. 05よくある注意点

Use cases

  1. 01VoltAgent の新規コード作成
  2. 02エージェントとワークフローの設計
  3. 03メモリやサーバー構成の確認

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/voltagent/skills --skill voltagent-best-practices

After installing, type/voltagent-best-practicesin Claude Code to confirm it loaded.

Details

From the project README

VoltAgent Best Practices

Quick reference for VoltAgent conventions and patterns.

Choosing Agent or Workflow

UseWhen
AgentOpen-ended tasks that require tool selection and adaptive reasoning
WorkflowMulti-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

Comments

Markdown supported