voltagent-best-practices

VoltAgent のベストプラクティス

VoltAgent の規約とパターンをすばやく確認できます。

---

エージェントとワークフローの選択

用途	使用する場面
エージェント	ツールの選択と適応的な推論が必要な、自由度の高いタスク
ワークフロー	明示的な制御フローと一時停止／再開を伴う複数ステップのパイプライン

---

レイアウト

src/
|-- index.ts
|-- agents/
|-- tools/
`-- workflows/

---

クイックスニペット

基本的なエージェント

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）。

基本的なワークフロー

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 のブートストラップ

import { VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";

new VoltAgent({
  agents: { agent },
  workflows: { workflow },
  server: honoServer(),
});

---

メモリのデフォルト設定

• エージェントとワークフロー全体で共有するデフォルト設定には memory を使用します。
• デフォルト設定を個別にする必要がある場合は、agentMemory または workflowMemory を使用します。

---

サーバーのオプション

• Node の HTTP サーバーには @voltagent/server-hono を使用します。
• 代替の Node サーバープロバイダーとして @voltagent/server-elysia を使用します。
• fetch ランタイム（Cloudflare、Netlify）には serverless プロバイダーを使用します。

---

可観測性に関するメモ

• トレースには VoltOpsClient または createVoltAgentObservability を使用します。
• VOLTAGENT_PUBLIC_KEY と VOLTAGENT_SECRET_KEY が設定されている場合、VoltAgent は VoltOps を自動設定します。

---

レシピ

ベストプラクティスをまとめた短いレシピは、組み込みドキュメントにあります。

• packages/core/docs/recipes/
• 検索：rg -n "keyword" packages/core/docs/recipes -g"*.md"
• 読み込み：cat packages/core/docs/recipes/<file>.md

---

落とし穴

• VoltAgent のパッケージ内では JSON.stringify を使用しないでください。代わりに @voltagent/internal の safeStringify を使用してください。

---

リソース

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