😺

TypeScriptで始めるAIエージェント開発 - VoltAgentとMCPで効率的なAI構築

2025/09/01に公開

フレームワーク

voltagent

tech

TypeScriptで始めるAIエージェント開発 - VoltAgentとMCPで効率的なAI構築

はじめに

AIエージェント開発を始めたいけれど、どのフレームワークを選べばいいかわからない。複数のLLMプロバイダを使い分けたい。TypeScriptで型安全な開発をしたい。そんな悩みを持つ開発者におすすめしたいのが、VoltAgentです。

VoltAgentは、TypeScriptで開発されたオープンソースのAIエージェントフレームワークで、日本ではまだあまり知られていませんが、AIアプリケーションの構築とオーケストレーションを大幅に効率化してくれる優秀なツールです。

本記事では、VoltAgentの基本概念から、MCP（Model Context Protocol）を活用した開発サポート、プロバイダの切り替え方法、TypeScriptでの開発体験、WebUIでのトレース機能まで、初級者向けに分かりやすく解説します。

VoltAgentとは何か？

VoltAgentは、AIエージェントの開発を迅速かつ柔軟に行うためのTypeScriptフレームワークです。従来のAI開発で複雑だった以下の課題を解決してくれます：

LLMとの対話の複雑さ
状態管理の困難さ
外部ツールとの統合の手間
プロバイダ切り替えの煩雑さ

VoltAgentの主な特徴

TypeScriptネイティブ - 型安全性とオートコンプリート
プロバイダ非依存 - OpenAI、Anthropic、Googleなど自由に切り替え
MCP対応 - 標準化されたツール統合
WebUIトレース - 視覚的なデバッグとモニタリング
モジュール設計 - 再利用可能なコンポーネント

VoltAgentの基本概念

VoltAgentの核となる概念を理解しましょう。

Agent（エージェント）

AIエージェントは、特定の目的を持ったAIアシスタントです。VoltAgentでは、以下のように簡単に作成できます：

import { Agent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";

const myAgent = new Agent({
  name: "hello-agent",
  purpose: "挨拶とサポートを提供するエージェント",
  instructions: `あなたは親しみやすいAIアシスタントです。
  ユーザーに丁寧で役立つ回答を提供してください。`,
  
  llm: new VercelAIProvider(),
  model: openai("gpt-4o-mini"),
  temperature: 0.1,
});

// エージェントとの対話
const response = await myAgent.generateText("こんにちは！");
console.log(response.text);

Tools（ツール）- TypeScriptで確実な処理を実現

ツールは、エージェントが実行できる機能です。VoltAgentの大きな利点は、AIに任せるのではなく、TypeScriptコードで確実な処理を提供できることです。

TypeScriptツールの利点

確実な結果 - AIの不安定さに頼らず、決定的な処理が可能
型安全性 - コンパイル時にエラーを検出
デバッグ容易性 - 通常のTypeScriptデバッグ手法が使用可能
パフォーマンス - ネイティブコード実行で高速
外部システム連携 - API呼び出し、データベース操作など確実に実行

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

// 確実な計算処理（AIではなくコードで実行）
export const calculatorTool = createTool({
  name: "calculator",
  description: "数学的計算を確実に実行します",
  parameters: z.object({
    expression: z.string().describe("計算式（例: 2 + 3 * 4）"),
  }),
  execute: async ({ expression }) => {
    try {
      // TypeScriptで確実な計算処理
      const result = evaluateMathExpression(expression);
      return {
        success: true,
        result: result,
        calculation: `${expression} = ${result}`,
        type: "exact_calculation"
      };
    } catch (error) {
      return {
        success: false,
        error: error.message,
        type: "calculation_error"
      };
    }
  },
});

// データベース操作も確実に実行
export const databaseTool = createTool({
  name: "queryDatabase",
  description: "データベースから確実にデータを取得",
  parameters: z.object({
    query: z.string(),
    params: z.array(z.any()).optional(),
  }),
  execute: async ({ query, params = [] }) => {
    // SQLクエリを確実に実行（AIの解釈に依存しない）
    const result = await database.query(query, params);
    return {
      success: true,
      data: result.rows,
      rowCount: result.rowCount,
      executionTime: result.executionTime
    };
  },
});

AIツール vs TypeScriptツールの比較

項目	AIツール	TypeScriptツール
精度	不安定（同じ入力で異なる結果）	100%確実（決定的処理）
速度	AIモデル呼び出しで遅い	ネイティブ実行で高速
コスト	トークン消費でコスト高	実行コストのみ
デバッグ	AIの思考過程が不明	通常のデバッグ手法
外部連携	AIが解釈する必要あり	直接API呼び出し

MCPによる開発サポート - Cursorとの連携

MCP（Model Context Protocol）は、アプリケーションがLLMにコンテキストを提供する方法を標準化するオープンプロトコルです。VoltAgentはMCPをネイティブサポートしており、これにより様々な外部ツールとの統合が簡単になります。

CursorでのMCP活用

{
  "mcpServers": {
    "voltagent": {
      "command": "npx",
      "args": [
        "-y",
        "@voltagent/docs-mcp"
      ],
      "env": {}
    }
}

MCPの利点

標準化された統合 - 一度の実装で複数のツールに対応
プロトコルの透明性 - デバッグとトラブルシューティングが容易
豊富なエコシステム - 既存のMCPサーバを活用可能
Cursor連携 - エディタとシームレスに統合

プロバイダの切り替えの容易さ

VoltAgentの最大の魅力の一つが、LLMプロバイダを簡単に切り替えられることです。ツールやエージェントの構成はそのままに、モデルだけを変更できます。

複数プロバイダの対応例

import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";

// 環境変数でプロバイダを選択
const getModel = () => {
  const provider = process.env.LLM_PROVIDER || "openai";
  
  switch (provider) {
    case "openai":
      return openai("gpt-4o-mini");
    case "anthropic":
      return anthropic("claude-3-haiku-20240307");
    case "google":
      return google("gemini-1.5-flash");
    default:
      throw new Error(`Unknown provider: ${provider}`);
  }
};

// エージェント作成（プロバイダに依存しない）
const agent = new Agent({
  name: "multi-provider-agent",
  llm: new VercelAIProvider(),
  model: getModel(), // 動的にプロバイダを選択
  tools: [webSearchTool, calculatorTool], // ツールは共通
});

プロバイダ別の特徴比較

プロバイダ	特徴	適用場面
OpenAI (GPT-4o-mini)	高精度、汎用性が高い	複雑な推論タスク
Anthropic (Claude)	安全性重視、長文対応	倫理的配慮が必要な場面
Google (Gemini)	マルチモーダル、高速	画像・動画処理

サンプルコードガイド

ここでは、VoltAgentを使用したAIエージェントの基本的な実装パターンをサンプルコードと共に紹介します。

基本的なプロジェクト構成

my-voltagent-app/
├── package.json
├── tsconfig.json
├── .env
├── src/
│   ├── index.ts           # メインエントリーポイント
│   ├── agents/            # エージェント定義
│   │   └── research-agent.ts
│   ├── tools/             # ツール定義
│   │   ├── calculator.ts
│   │   └── web-search.ts
│   └── config/            # 設定ファイル
│       └── mcp.ts

package.jsonの設定

{
  "name": "my-voltagent-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx watch --env-file=.env ./src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@voltagent/core": "^0.1.84",
    "@voltagent/vercel-ai": "^1.0.0",
    "@ai-sdk/openai": "^2.0.14",
    "zod": "^3.25.0",
    "dotenv": "^16.4.7"
  },
  "devDependencies": {
    "@types/node": "^22.10.5",
    "tsx": "^4.19.2",
    "typescript": "^5.7.3"
  }
}

基本的なエージェント実装

// src/agents/research-agent.ts
import { Agent, InMemoryStorage } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";
import { calculatorTool } from "../tools/calculator";

export const researchAgent = new Agent({
  name: "ResearchAgent",
  purpose: "調査研究専門のAIアシスタント",
  memory: new InMemoryStorage({ storageLimit: 50 }),
  
  instructions: `あなたは調査研究の専門家です。
  以下の原則に従って行動してください：
  
  1. 最新の情報を重視し、信頼できる情報源を使用する
  2. 数値計算は必ずツールを使用して正確性を確保する
  3. 情報の出典を明記し、根拠を示す
  4. 複数の視点から分析を行う`,
  
  llm: new VercelAIProvider(),
  model: openai("gpt-4o-mini"),
  temperature: 0.1,
  maxSteps: 3,
  
  tools: [calculatorTool],
});

ツールの実装例

// src/tools/calculator.ts
import { createTool } from "@voltagent/core";
import { z } from "zod";

export const calculatorTool = createTool({
  name: "calculator",
  description: "数学計算を正確に実行します",
  parameters: z.object({
    expression: z.string().describe("計算式（例: 2 + 3 * 4, sqrt(16)）"),
    precision: z.number().optional().default(2).describe("小数点以下の桁数"),
  }),
  execute: async ({ expression, precision }) => {
    try {
      // 安全な数式評価の実装
      const result = evaluateExpression(expression);
      const roundedResult = Number(result.toFixed(precision));
      
      return {
        success: true,
        expression,
        result: roundedResult,
        formatted: `${expression} = ${roundedResult}`,
        type: "calculation"
      };
    } catch (error) {
      return {
        success: false,
        error: `計算エラー: ${error.message}`,
        expression,
        type: "error"
      };
    }
  },
});

// 安全な数式評価関数の実装例
function evaluateExpression(expression: string): number {
  // 許可された文字と関数のみを使用
  const allowedPattern = /^[0-9+\-*\/\(\)\.\s]+$/;
  
  if (!allowedPattern.test(expression.replace(/sqrt|log|sin|cos|tan/g, ''))) {
    throw new Error('無効な文字が含まれています');
  }
  
  // Function constructorを使用した安全な評価
  const sanitized = expression
    .replace(/sqrt\(/g, 'Math.sqrt(')
    .replace(/log\(/g, 'Math.log(')
    .replace(/sin\(/g, 'Math.sin(')
    .replace(/cos\(/g, 'Math.cos(')
    .replace(/tan\(/g, 'Math.tan(');
    
  return Function(`"use strict"; return (${sanitized})`)();
}

MCP設定の実装

// src/config/mcp.ts
import { MCPConfiguration } from "@voltagent/core";

export const createMcpConfig = () => {
  return new MCPConfiguration({
    servers: {
      filesystem: {
        type: "stdio",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_DIRECTORIES: process.env.WORKSPACE_PATH || process.cwd(),
        }
      },
      
      github: {
        type: "http",
        url: "https://api.github.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
          "User-Agent": "VoltAgent-App"
        }
      }
    }
  });
};

メインアプリケーション

// src/index.ts
import "dotenv/config";
import { VoltAgent } from "@voltagent/core";
import { createPinoLogger } from "@voltagent/logger";
import { researchAgent } from "./agents/research-agent";
import { createMcpConfig } from "./config/mcp";

const logger = createPinoLogger({
  name: "voltagent-app",
  level: "info"
});

async function main() {
  try {
    // MCP設定の初期化
    const mcpConfig = createMcpConfig();
    const mcpTools = await mcpConfig.getTools();
    
    // エージェントにMCPツールを追加
    researchAgent.tools.push(...mcpTools);
    
    // VoltAgent初期化
    const voltAgent = new VoltAgent({
      agents: { researchAgent },
      logger,
    });
    
    // エージェントのテスト実行
    const response = await researchAgent.generateText(
      "TypeScriptとVoltAgentについて調査して、主要な特徴をまとめてください"
    );
    
    console.log("🤖 エージェントの回答:");
    console.log(response.text);
    
    // MCPクリーンアップ
    await mcpConfig.disconnect();
    
  } catch (error) {
    logger.error("エラーが発生しました:", error);
  }
}

main().catch(console.error);

環境設定（.env）

# LLMプロバイダ設定
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-proj-your-api-key

# GitHub連携（オプション）
GITHUB_TOKEN=github_pat_your-token

# ワークスペース設定
WORKSPACE_PATH=/path/to/your/project

# VoltOps（WebUIトレース用、オプション）
VOLTAGENT_PUBLIC_KEY=your-public-key
VOLTAGENT_SECRET_KEY=your-secret-key

実行方法

# 依存関係のインストール
npm install

# 開発モード（ホットリロード）
npm run dev

# ビルド
npm run build

# 本番実行
npm start

まとめ

VoltAgentは、TypeScriptでのAIエージェント開発を大幅に効率化してくれる優秀なフレームワークです。本記事で紹介した特徴をまとめると：

VoltAgentの主要メリット

型安全性 - TypeScriptネイティブで安心して開発
プロバイダ非依存 - OpenAI、Anthropic、Google等を自由に切り替え
MCP統合 - 標準化されたツール連携（Cursor等との相性抜群）
確実なツール実行 - AIに頼らずTypeScriptコードで安定した処理
視覚的デバッグ - WebUIでのリアルタイム監視

始めるためのステップ

基本概念の理解 - Agent、Tools、Workflowの関係を把握
シンプルなプロジェクト - 基本的なエージェントから開始
TypeScriptツールの活用 - 確実な処理のためのツール作成
MCP統合 - Cursorなどのエディタとの連携
本格運用 - AWS Lambda等での実装

今後の展望

VoltAgentは急速に進化しているフレームワークです。MCP対応やWebUIトレース機能など、開発者にとって便利な機能が続々と追加されています。特にCursorのようなAI支援エディタとの組み合わせにより、開発体験はさらに向上していくでしょう。

AIエージェント開発に興味のある方は、ぜひVoltAgentを試してみてください。日本でもより多くの開発者がこの優秀なツールを活用することで、AIアプリケーション開発がさらに加速することを期待しています。

TypeScriptで始めるAIエージェント開発 - VoltAgentとMCPで効率的なAI構築

はじめに

VoltAgentとは何か？

VoltAgentの主な特徴

VoltAgentの基本概念

Agent（エージェント）

Tools（ツール）- TypeScriptで確実な処理を実現

TypeScriptツールの利点

AIツール vs TypeScriptツールの比較

MCPによる開発サポート - Cursorとの連携

CursorでのMCP活用

MCPの利点

プロバイダの切り替えの容易さ

複数プロバイダの対応例

プロバイダ別の特徴比較

サンプルコードガイド

基本的なプロジェクト構成

package.jsonの設定

基本的なエージェント実装

ツールの実装例

MCP設定の実装

メインアプリケーション

環境設定（.env）

実行方法

まとめ

VoltAgentの主要メリット

始めるためのステップ

今後の展望

Discussion