VoltAgent - TypeScriptで本番運用できるAIエージェントを構築するフレームワーク

はじめに

AIエージェント開発、盛り上がってますね。

ChatGPTが登場してから、「AIに仕事を任せる」という発想が現実味を帯びてきました。単純にAPIを叩いて回答を得るだけじゃなく、ツールを使わせて、複数ステップの処理を実行させて、結果を検証して...という本格的なエージェントを作りたい需要が増えています。

ただ、いざ作ろうとすると壁にぶつかる。メモリ管理どうする？ワークフローの制御は？本番環境でのモニタリングは？一から全部実装するのは正直しんどい。

そこで今回紹介するのがVoltAgentです。

TypeScriptネイティブのAIエージェントフレームワークで、メモリ、ワークフロー、可観測性（オブザーバビリティ）が最初から組み込まれている。「本番環境で使える」を前提に設計されているのがポイントです。

GitHubスターは4,100を超えていて、Samsung、Oracle、Microsoft、Wells Fargoといった大手企業の開発者にも使われているという話。これ、かなり本気度が高いフレームワークだと思います。

VoltAgentとは

VoltAgentは、AIエージェントの構築・オーケストレーションのためのオープンソースTypeScriptフレームワークです。

公式サイトでは「Complete code control and full visibility, without proprietary black boxes」と謳っています。要するに、ブラックボックスに頼らず、コードを完全にコントロールしながらエージェントを開発できるということ。

イベント駆動型のアーキテクチャで、エンタープライズグレードのAIエージェントを構築できる設計になっています。

ライセンスはMIT。商用利用も問題ありません。

特徴・メリット

本番環境対応が前提の設計

VoltAgentの最大の特徴は、最初から本番環境を見据えた設計になっていること。

メモリ管理、ワークフローエンジン、可観測性といった機能が標準で組み込まれています。「プロトタイプは動いたけど、本番に持っていくには作り直しが必要」みたいな状況を避けられる。

インフラを一から構築する必要がないので、エージェントのロジックに集中できます。

VoltOps - 可観測性プラットフォーム

これ、かなり強力な機能です。

VoltOpsという専用の可観測性プラットフォームが用意されていて、リアルタイムで実行トレース、パフォーマンスメトリクス、詳細なログを確認できます。ビジュアルダッシュボードでエージェントの動作を可視化できる。

本番運用で「なんでこの回答になったの？」という調査が発生したとき、トレースが残っていないと地獄を見ます。VoltAgentならその心配がない。

マルチエージェント対応

スーパーバイザーパターンによる複数エージェント間の協調がサポートされています。

親エージェント（スーパーバイザー）が全体のワークフローを管理して、専門化された子エージェントにタスクを委譲する。それぞれのエージェントが得意分野を持って連携する、という設計ができます。

複雑なタスクを分解して、適切なエージェントに振り分ける。人間のチームワークに近いイメージですね。

宣言的ワークフローエンジン

Workflow Chain APIで、複雑なエージェントワークフローを宣言的に定義できます。

特に便利なのが「suspend/resume」機能。ワークフローを一時停止して人間の入力を待ち、その後再開する「ヒューマン・イン・ザ・ループ」パターンが簡単に実装できます。

経費承認フローで「一定金額以上は上長の承認を待つ」みたいな現実的なユースケースに対応できる。

型安全なツール定義

TypeScriptの強みを活かして、ツール定義がZodスキーマで型安全に書けます。

パラメータの型が自動推論されるので、typoや型の不整合でハマることが減る。コード補完も効くので、開発体験が良い。

複数のLLMプロバイダーに対応

OpenAI、Anthropic（Claude）、Google Gemini、Groq、Mistralなど、主要なLLMプロバイダーをサポートしています。

AISDKを使った統一インターフェースで、プロバイダーの切り替えが容易。コスト最適化やフォールバック対応がしやすい設計です。

40以上の外部サービス連携

Slack、Gmail、Airtable、Salesforce、GitHubなど、40以上のサービスとの連携が用意されています。

「GitHubでPRが作られたらSlackに通知して、関連するAirtableのレコードを更新する」みたいな自動化が、エージェントと組み合わせて実現できる。

インストール方法

VoltAgent CLIを使えば、すぐに始められます。

npm create voltagent-app@latest my-agent-app

これを実行すると、対話形式でセットアップが進みます。プロジェクト名、AIプロバイダー、APIキーを設定すれば完了。

動作要件

Node.js 20.19以上

比較的新しいNode.jsが必要なので、nvmなどでバージョン管理しておくと良いでしょう。

手動セットアップ

既存プロジェクトに追加する場合は、パッケージを直接インストールします。

npm install @voltagent/core

AIプロバイダーのSDKも必要です。

# OpenAIを使う場合
npm install @ai-sdk/openai

# Anthropicを使う場合
npm install @ai-sdk/anthropic

# Google Geminiを使う場合
npm install @ai-sdk/google

基本的な使い方

最小構成のエージェント

まずは最小限のエージェントから。

import { VoltAgent, Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";

const agent = new Agent({
  name: "my-assistant",
  instructions: "あなたは親切なアシスタントです。ユーザーの質問に丁寧に回答してください。",
  model: openai("gpt-4o-mini"),
});

// エージェントの実行
const response = await agent.generate("TypeScriptの型推論について教えて");
console.log(response);

nameでエージェントを識別し、instructionsで振る舞いを定義、modelでLLMを指定する。シンプルですね。

ツールを持つエージェント

エージェントに機能を追加するには、ツールを定義します。

import { Agent, createTool } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

// 天気取得ツールの定義
const weatherTool = createTool({
  name: "get_weather",
  description: "指定した都市の現在の天気を取得します",
  parameters: z.object({
    city: z.string().describe("天気を取得したい都市名"),
  }),
  execute: async ({ city }) => {
    // 実際にはAPIを呼び出す
    return {
      city,
      temperature: 22,
      condition: "晴れ",
    };
  },
});

const agent = new Agent({
  name: "weather-assistant",
  instructions: "天気に関する質問に答えてください。必要に応じて天気情報を取得してください。",
  model: openai("gpt-4o-mini"),
  tools: [weatherTool],
});

const response = await agent.generate("東京の天気を教えて");

Zodスキーマでパラメータを定義するので、型安全に書けます。エージェントは文脈に応じて適切なツールを選択して実行してくれる。

ワークフローの定義

複数ステップの処理を組み立てるには、ワークフローを使います。

import { Workflow } from "@voltagent/core";
import { z } from "zod";

// 経費承認ワークフローの例
const expenseWorkflow = new Workflow({
  name: "expense-approval",
  steps: [
    {
      name: "validate",
      execute: async (context) => {
        // 経費データのバリデーション
        const { amount, category } = context.input;
        if (amount > 100000) {
          return { requiresApproval: true, amount, category };
        }
        return { requiresApproval: false, amount, category };
      },
    },
    {
      name: "approval",
      execute: async (context) => {
        if (context.requiresApproval) {
          // 人間の承認を待つ
          await context.suspend({ reason: "高額経費の承認が必要です" });
        }
        return { approved: true };
      },
    },
    {
      name: "process",
      execute: async (context) => {
        // 経費処理の実行
        return { status: "processed", amount: context.amount };
      },
    },
  ],
});

// ワークフローの実行
const result = await expenseWorkflow.run({
  amount: 150000,
  category: "出張費",
});

suspend()で処理を一時停止して、人間の入力を待つことができます。承認後にresume()で再開する流れ。

マルチエージェントの構築

スーパーバイザーパターンで複数エージェントを協調させる例。

import { Agent, SupervisorAgent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";

// 専門化されたエージェントを定義
const researchAgent = new Agent({
  name: "researcher",
  instructions: "情報収集と調査を担当します。",
  model: openai("gpt-4o-mini"),
  tools: [searchTool],
});

const writerAgent = new Agent({
  name: "writer",
  instructions: "文章作成を担当します。",
  model: openai("gpt-4o"),
  tools: [writingTool],
});

// スーパーバイザーが全体を統括
const supervisor = new SupervisorAgent({
  name: "supervisor",
  instructions: "タスクを適切なエージェントに振り分けて、全体の品質を管理します。",
  model: openai("gpt-4o"),
  agents: [researchAgent, writerAgent],
});

const result = await supervisor.generate("AIエージェントについてのブログ記事を書いて");