TypeScript × VoltAgent：プロダクション対応AIエージェントの作り方

はじめに

最近、AIエージェントが注目を集めていますが、「自分でもAIエージェントを作ってみたい」と思ったことはありませんか？

「AIエージェントって何から始めればいいの？」
「実際にプロダクションで使えるレベルのものを作れる？」

本記事では、VoltAgentを使って実用的なAIエージェントを構築する方法を、実際のコード例とともに解説します。

AIエージェントとは

AIエージェントは、目的に向かって自律的に行動を決定・実行するAIシステムです。

要素	役割	例
Planning	タスクを分解・計画	「ファイル作成→内容記述→保存」
Memory	過去の行動・結果を記憶	前回の実行結果、学習内容
Tools	外部システムとの連携	ファイル操作、API呼び出し
Reasoning	状況判断・意思決定	次に何をすべきか判断

VoltAgentとは

VoltAgentは、エンタープライズグレードのAIエージェントを構築するためのTypeScriptフレームワークです。

機能	説明	メリット
マルチエージェント	複数のエージェントを統合的に管理	複雑なタスクを効率的に分担処理
統一API	複数のLLMプロバイダーに対応	OpenAI、Anthropicなどを簡単に切り替え
ツール統合	40+のアプリケーション連携	Notion、Slack、GitHubなど
永続メモリ	長期記憶とコンテキスト管理	エージェント間での知識共有
RAG機能	ベクトルデータベース統合	大規模な知識ベースの活用

VoltAgentの導入

まず、VoltAgentをプロジェクトに導入しましょう。

npm install @voltagent/core
# または
yarn add @voltagent/core

1. 基本的なエージェントの作成

VoltAgentを使って、最初の簡単なエージェントを作成してみましょう。

src/basic-agent.ts

import { Agent, AgentConfig } from '@voltagent/core';

// エージェント設定
const config: AgentConfig = {
  name: 'TaskHelper',
  llm: {
    provider: 'openai',
    model: 'gpt-4',
    apiKey: process.env.OPENAI_API_KEY
  },
  memory: {
    type: 'local', // または 'vector', 'redis'
    maxEntries: 100
  }
};

// エージェントを初期化
const agent = new Agent(config);

// タスクを実行
async function runBasicTask() {
  const result = await agent.run({
    task: "TypeScript学習用の記事の構成を考えて、マークダウン形式で出力してください",
    context: "プログラミング初心者向けの内容で、実践的な例を含めたい"
  });
  
  console.log('エージェントの応答:', result);
}

runBasicTask().catch(console.error);

2. ツールの追加

VoltAgentの強力な機能の一つは、カスタムツールを簡単に追加できることです。

src/tools/file-manager.ts

import { Tool } from '@voltagent/core';
import { promises as fs } from 'fs';
import path from 'path';

// ファイル操作ツール
export const fileManagerTool: Tool = {
  name: 'file_manager',
  description: 'ファイルの作成、読み込み、削除を行う',
  schema: {
    type: 'object',
    properties: {
      action: { 
        type: 'string', 
        enum: ['create', 'read', 'delete', 'list'] 
      },
      path: { type: 'string' },
      content: { type: 'string' }
    },
    required: ['action', 'path']
  },
  execute: async (params) => {
    const { action, path: filePath, content } = params;
    
    switch (action) {
      case 'create':
        await fs.writeFile(filePath, content || '', 'utf-8');
        return { success: true, message: `ファイル ${filePath} を作成しました` };
        
      case 'read':
        const data = await fs.readFile(filePath, 'utf-8');
        return { success: true, content: data };
        
      case 'delete':
        await fs.unlink(filePath);
        return { success: true, message: `ファイル ${filePath} を削除しました` };
        
      case 'list':
        const files = await fs.readdir(path.dirname(filePath));
        return { success: true, files };
        
      default:
        throw new Error(`未知のアクション: ${action}`);
    }
  }
};

// エージェントにツールを追加
agent.addTool(fileManagerTool);

マルチエージェントシステムの構築

VoltAgentの真の力は、複数のエージェントを協調させることで発揮されます。

1. スーパーバイザーエージェントパターン

src/multi-agent/supervisor.ts

import { Agent, SupervisorAgent, WorkflowChain } from '@voltagent/core';

// 専門エージェントを定義
const researchAgent = new Agent({
  name: 'ResearchAgent',
  role: '情報収集と分析を担当',
  llm: { provider: 'openai', model: 'gpt-4' },
  tools: ['web_search', 'document_analyzer']
});

const writerAgent = new Agent({
  name: 'WriterAgent', 
  role: '記事作成とライティングを担当',
  llm: { provider: 'anthropic', model: 'claude-3' },
  tools: ['markdown_formatter', 'content_optimizer']
});

const reviewerAgent = new Agent({
  name: 'ReviewerAgent',
  role: '品質チェックと改善提案を担当',
  llm: { provider: 'openai', model: 'gpt-4' },
  tools: ['grammar_checker', 'readability_analyzer']
});

// スーパーバイザーエージェントを作成
const supervisor = new SupervisorAgent({
  name: 'ArticleSupervisor',
  agents: [researchAgent, writerAgent, reviewerAgent],
  coordination: 'sequential' // または 'parallel', 'conditional'
});

// ワークフローを定義
const articleWorkflow = new WorkflowChain()
  .step('research', {
    agent: researchAgent,
    task: '指定されたトピックについて詳細な情報を収集する',
    output: 'research_data'
  })
  .step('write', {
    agent: writerAgent,
    task: '収集した情報を基に記事を作成する',
    input: 'research_data',
    output: 'draft_article'
  })
  .step('review', {
    agent: reviewerAgent,
    task: '記事の品質をチェックし、改善提案を行う',
    input: 'draft_article',
    output: 'final_article'
  });

// 実行
async function runArticleCreation() {
  const result = await supervisor.executeWorkflow(articleWorkflow, {
    topic: 'TypeScriptの最新機能',
    target_audience: 'プログラミング初心者',
    article_length: '3000文字程度'
  });
  
  console.log('完成した記事:', result.final_article);
}

2. 外部サービス統合の例

VoltAgentは豊富な統合機能を提供しています。

src/integrations/notion-slack.ts

import { Agent, NotionTool, SlackTool, GitHubTool } from '@voltagent/core';

// Notion連携エージェント
const notionAgent = new Agent({
  name: 'NotionManager',
  tools: [
    new NotionTool({
      token: process.env.NOTION_TOKEN,
      databaseId: process.env.NOTION_DATABASE_ID
    }),
    new SlackTool({
      token: process.env.SLACK_BOT_TOKEN,
      channel: '#dev-updates'
    }),
    new GitHubTool({
      token: process.env.GITHUB_TOKEN,
      repository: 'my-org/my-project'
    })
  ]
});

// タスク管理ワークフロー
async function taskManagementWorkflow() {
  const result = await notionAgent.run({
    task: `
    1. GitHubのissueを確認
    2. 新しいissueがあればNotionデータベースに追加
    3. 重要度が高いissueがあればSlackに通知
    `,
    context: 'プロジェクトの進捗管理を自動化したい'
  });

  return result;
}

RAG（検索拡張生成）の活用

VoltAgentは、ベクトルデータベースと連携したRAG機能を簡単に実装できます。

1. ベクトルストアとの連携

src/rag/knowledge-base.ts

import { Agent, VectorStore, EmbeddingModel } from '@voltagent/core';
import { PineconeVectorStore } from '@voltagent/integrations';

// ベクトルストアの設定
const vectorStore = new PineconeVectorStore({
  apiKey: process.env.PINECONE_API_KEY,
  environment: process.env.PINECONE_ENVIRONMENT,
  indexName: 'technical-docs'
});

// 埋め込みモデルの設定
const embeddingModel = new EmbeddingModel({
  provider: 'openai',
  model: 'text-embedding-ada-002'
});

// RAG対応エージェント
const ragAgent = new Agent({
  name: 'KnowledgeAgent',
  llm: { provider: 'openai', model: 'gpt-4' },
  vectorStore: vectorStore,
  embedding: embeddingModel,
  ragConfig: {
    topK: 5,
    threshold: 0.7,
    includeMetadata: true
  }
});

// ドキュメントをベクトルストアに追加
async function addDocuments() {
  const documents = [
    {
      content: 'TypeScriptは静的型付け言語です...',
      metadata: { type: 'tutorial', difficulty: 'beginner' }
    },
    {
      content: 'React Hooksの使い方について...',
      metadata: { type: 'guide', framework: 'react' }
    }
  ];

  await ragAgent.addDocuments(documents);
  console.log('ドキュメントをベクトルストアに追加しました');
}

// 知識ベースを活用した回答生成
async function askWithKnowledge() {
  const result = await ragAgent.run({
    task: 'TypeScriptでReactコンポーネントを書く際のベストプラクティスは？',
    useRAG: true
  });

  console.log('RAGを活用した回答:', result);
}

2. メモリ管理の最適化

VoltAgentは永続メモリとセッションメモリを効率的に管理します。

src/memory/advanced-memory.ts

import { Agent, MemoryConfig } from '@voltagent/core';
import { RedisMemoryStore } from '@voltagent/integrations';

// 高度なメモリ設定
const memoryConfig: MemoryConfig = {
  shortTerm: {
    type: 'local',
    maxEntries: 50,
    ttl: '1h'
  },
  longTerm: {
    type: 'redis',
    store: new RedisMemoryStore({
      url: process.env.REDIS_URL
    }),
    maxEntries: 1000
  },
  vector: {
    type: 'pinecone',
    indexName: 'agent-memory',
    dimensions: 1536
  }
};

const memoryAgent = new Agent({
  name: 'MemoryAgent',
  memory: memoryConfig,
  llm: { provider: 'openai', model: 'gpt-4' }
});

// コンテキストを考慮した応答
async function contextAwareResponse() {
  // 以前の会話履歴を自動的に考慮
  const result = await memoryAgent.run({
    task: '前回の話の続きで、実装方法の詳細を教えて',
    sessionId: 'user_123'
  });

  return result;
}

VoltOpsによる可観測性

VoltAgentには、エージェントの動作を監視・デバッグするためのVoltOpsが組み込まれています。

1. 基本的な監視設定

src/observability/monitoring.ts

import { Agent, VoltOps } from '@voltagent/core';

// VoltOps設定
const voltOps = new VoltOps({
  apiKey: process.env.VOLTOPS_API_KEY,
  projectId: 'my-ai-project',
  environment: 'production'
});

// 監視対応エージェント
const monitoredAgent = new Agent({
  name: 'ProductionAgent',
  llm: { provider: 'openai', model: 'gpt-4' },
  observability: voltOps,
  telemetry: {
    tracing: true,
    metrics: true,
    logging: 'debug'
  }
});

// エラーハンドリングと回復
async function resilientExecution() {
  try {
    const result = await monitoredAgent.run({
      task: '複雑なデータ処理タスク',
      retryConfig: {
        maxAttempts: 3,
        backoffStrategy: 'exponential',
        retryableErrors: ['NetworkError', 'TimeoutError']
      }
    });
    
    return result;
  } catch (error) {
    // VoltOpsに自動的にエラーレポートが送信される
    console.error('タスク実行に失敗:', error);
    throw error;
  }
}

2. パフォーマンス分析

src/performance/analysis.ts

import { Agent, PerformanceAnalyzer } from '@voltagent/core';

const analyzer = new PerformanceAnalyzer({
  enableMetrics: true,
  enableTracing: true,
  sampleRate: 0.1 // 10%のリクエストをサンプリング
});

const performanceAgent = new Agent({
  name: 'PerformanceAgent',
  analyzer: analyzer,
  optimization: {
    caching: true,
    parallelization: true,
    memoryLimit: '512MB'
  }
});

// パフォーマンス測定付き実行
async function measurePerformance() {
  const startTime = performance.now();
  
  const result = await performanceAgent.run({
    task: 'パフォーマンステスト用のタスク'
  });
  
  const metrics = analyzer.getMetrics();
  console.log('実行時間:', performance.now() - startTime);
  console.log('メモリ使用量:', metrics.memoryUsage);
  console.log('API呼び出し回数:', metrics.apiCalls);
  
  return result;
}

実用的なユースケース集

1. コンテンツ管理システム

src/use-cases/content-management.ts

import { Agent, WorkflowChain } from '@voltagent/core';

// コンテンツ管理エージェント
const contentAgent = new Agent({
  name: 'ContentManager',
  llm: { provider: 'openai', model: 'gpt-4' },
  tools: ['file_manager', 'markdown_processor', 'seo_analyzer']
});

// ブログ記事作成ワークフロー
const blogWorkflow = new WorkflowChain()
  .step('research', {
    task: 'トピックに関する最新情報を収集',
    tools: ['web_search', 'trend_analyzer']
  })
  .step('outline', {
    task: '記事の構成を作成',
    input: 'research_data'
  })
  .step('write', {
    task: '記事本文を執筆',
    input: 'outline_data'
  })
  .step('optimize', {
    task: 'SEO最適化とメタデータ追加',
    input: 'article_content'
  });

async function createBlogPost(topic: string) {
  return await contentAgent.executeWorkflow(blogWorkflow, { topic });
}

2. カスタマーサポート自動化

src/use-cases/customer-support.ts

import { Agent, ConversationMemory } from '@voltagent/core';

const supportAgent = new Agent({
  name: 'SupportBot',
  llm: { provider: 'anthropic', model: 'claude-3' },
  memory: new ConversationMemory({
    maxTurns: 20,
    summarization: true
  }),
  tools: [
    'knowledge_base_search',
    'ticket_creator',
    'escalation_handler'
  ]
});

// サポートチケット処理
async function handleSupportRequest(message: string, userId: string) {
  const context = await supportAgent.getContext(userId);
  
  const response = await supportAgent.run({
    task: `
    ユーザーからの問い合わせに対応してください:
    "${message}"
    
    以下の手順で処理してください:
    1. 問い合わせ内容を分析
    2. 適切な回答を知識ベースから検索
    3. 解決できない場合は人間のサポートにエスカレーション
    `,
    sessionId: userId,
    context: context
  });

  return response;
}

3. データ分析・レポート生成

src/use-cases/data-analysis.ts

import { Agent, DataConnector } from '@voltagent/core';

const analyticsAgent = new Agent({
  name: 'DataAnalyst',
  llm: { provider: 'openai', model: 'gpt-4' },
  connectors: [
    new DataConnector('postgresql', process.env.DB_URL),
    new DataConnector('elasticsearch', process.env.ES_URL)
  ],
  tools: ['sql_executor', 'chart_generator', 'report_formatter']
});

// 自動レポート生成
async function generateWeeklyReport() {
  const result = await analyticsAgent.run({
    task: `
    週次レポートを生成してください:
    1. 売上データを集計（過去1週間）
    2. 前週比較分析を実行
    3. トレンドグラフを作成
    4. インサイトをまとめてレポート形式で出力
    `,
    outputFormat: 'markdown'
  });

  return result;
}

まとめ

本記事では、VoltAgentを活用した実用的なAIエージェントの構築方法を解説しました。

✅ VoltAgentを選ぶ理由

• エンタープライズ対応: プロダクション環境での安定性
• 豊富な統合: 40+のアプリケーション連携
• マルチエージェント: 複雑なワークフローの分散処理
• 統一API: 複数のLLMプロバイダーへの対応
• 可観測性: VoltOpsによる包括的な監視機能

🎯 実装のベストプラクティス

• 段階的導入: 小さなタスクから始めて徐々に拡張
• 適切なツール選択: タスクに応じたカスタムツールの実装
• メモリ管理: 効率的なコンテキスト保持と永続化
• エラーハンドリング: 堅牢な回復機能の設計
• 監視・デバッグ: VoltOpsを活用した運用監視

次のステップ

• 高度なRAG: 専門知識ベースとの統合
• カスタムツール開発: 業務特化型ツールの作成
• ワークフロー最適化: 複雑な業務プロセスの自動化
• スケーリング: 大規模運用への対応

VoltAgentは、AIエージェント開発における多くの課題を解決してくれる強力なフレームワークです。ぜひあなたのプロジェクトでも活用してみてください！