A2A JS サンプル: 映画エージェント

ソースコード

プロジェクト概要

このプロジェクトは、A2A（Agent2Agent）フレームワークで構築された包括的な映画情報エージェントを実演します。このエージェントは、TMDB（The Movie Database）APIを活用して詳細な映画情報、検索機能、およびOpenRouter統合を通じたAI駆動の会話機能を提供します。

主な機能

強化されたTMDB API統合: Bearerトークン認証を使用した現代的な実装
包括的な映画検索: 年、アダルトコンテンツなどのフィルターで映画を検索
マルチ検索機能: 映画、テレビ番組、人物を同時に検索
AI駆動の会話: インテリジェントな映画クエリのためにOpenRouter APIを活用
プロキシサポート: ネットワークリクエスト用の内蔵SOCKS5/HTTPプロキシサポート
A2Aフレームワーク: Agent2Agent通信プロトコルを実装
CLIインターフェース: テスト用のインタラクティブなコマンドラインインターフェース
Expressサーバー: エージェント通信用のRESTful APIエンドポイント

プロジェクトアーキテクチャ

プロジェクトは関心の明確な分離を持つモジュラーアーキテクチャに従います：

src/
├── index.ts                    # メインサーバーエントリーポイント
├── cli.ts                      # コマンドラインインターフェース
├── config/
│   └── env.ts                  # 環境設定
└── movie-agent/
    ├── index.ts                # コアエージェント実行器
    ├── tools.ts                # TMDB APIツール
    ├── tmdb.ts                 # TMDB APIクライアント
    └── openai.ts              # OpenRouter統合

ステップバイステップのセットアップと実行

1. 前提条件

Node.js（v18以上）
Bunパッケージマネージャー
TMDB APIアカウント
OpenRouter APIアカウント

2. 依存関係のインストール

# リポジトリをクローン
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Bunを使用して依存関係をインストール
bun install

3. 環境設定

プロジェクトルートに.envファイルを作成します：

# TMDB APIキー（Bearerトークン）
TMDB_API_TOKEN=your_tmdb_api_token_here

# AI機能用のOpenRouter APIキー
OPENROUTER_API_KEY=your_openrouter_api_key_here

# プロキシ設定（オプション）
USE_PROXY=true
PROXY_URL=socks5://127.0.0.1:7890

# サーバー設定
NODE_ENV=development
PORT=3000

4. エージェントサーバーの実行

# 開発サーバーを開始
bun dev

# または本番環境でビルドして実行
bun run build
bun start

サーバーはhttp://localhost:3000（または.envファイルで指定されたポート）で開始されます。

5. CLIインターフェースでのテスト

# インタラクティブCLIを実行
bun cli

# またはカスタムサーバーURLを指定
bun cli http://localhost:3000

6. エージェント情報へのアクセス

サーバーが実行されると、以下にアクセスできます：

エージェントカード: http://localhost:3000/.well-known/agent.json
APIドキュメント: A2Aフレームワークエンドポイントを通じて利用可能

プロジェクトロジックの説明

コアコンポーネント

MovieAgentExecutor: ユーザークエリを処理するメインエージェントロジック
TMDBツール: 映画データ取得用の5つの専門ツール
OpenAI統合: OpenRouter経由でAI駆動の会話を処理
A2Aフレームワーク: エージェント通信プロトコルを管理

利用可能なツール

エージェントは映画情報のための5つの主要ツールを提供します：

searchMovies: オプションのフィルター（年、アダルトコンテンツ）付きの基本映画検索
searchPeople: 俳優、監督、その他の映画業界の人物を検索
getMovieDetails: 特定の映画に関する詳細情報を取得
searchMoviesWithDetails: 1回の呼び出しで検索と詳細を組み合わせ（推奨）
multiSearch: すべてのコンテンツタイプ（映画、テレビ番組、人物）を同時に検索

ワークフロープロセス

エージェントは以下の一般的なワークフローに従います：

リクエスト処理: A2Aフレームワークを通じてユーザークエリを受信
コンテキスト管理: 会話履歴とコンテキストを維持
AI分析: OpenRouterを使用してユーザーの意図を理解
ツール実行: クエリに基づいて適切なTMDBツールを呼び出し
レスポンス生成: 包括的な映画情報をフォーマットして返却
状態管理: タスクステータスを追跡し、リアルタイム更新を提供

Mermaidシーケンス図

sequenceDiagram
    participant U as User
    participant CLI as CLI Client
    participant A as A2A Server
    participant MA as Movie Agent
    participant AI as OpenRouter API
    participant TMDB as TMDB API

    U->>CLI: Enter movie query
    CLI->>A: Send message via A2A protocol
    A->>MA: Execute task
    MA->>A: Publish "working" status
    A->>CLI: Stream status update
    CLI->>U: Show "Processing..." message

    MA->>AI: Send query with available tools
    AI->>MA: Respond with tool calls
    MA->>TMDB: Execute tool calls (searchMovies, getMovieDetails, etc.)
    TMDB->>MA: Return movie data
    MA->>AI: Send tool results
    AI->>MA: Generate final response
    MA->>A: Publish "completed" status with response
    A->>CLI: Stream final response
    CLI->>U: Display movie information

    Note over MA,TMDB: Tools available:<br/>- searchMovies<br/>- searchPeople<br/>- getMovieDetails<br/>- searchMoviesWithDetails<br/>- multiSearch

技術的ハイライト

AI駆動のインテリジェンス

エージェントはOpenRouterを使用してインテリジェントなレスポンスを提供し、ユーザークエリに基づいてどのツールを使用するかを自動的に決定します。「トム・クルーズ主演の2023年のアクション映画を見つけて」のような複雑なリクエストを複数のツール呼び出しを組み合わせて処理できます。

強化されたTMDB統合

基本的なTMDB実装とは異なり、このエージェントは：

現代的なBearerトークン認証を使用
効率的なAPI使用のための「append to response」を実装
完全な画像URLを自動生成
包括的なエラーハンドリングを提供

A2Aプロトコル準拠

エージェントはA2A（Agent2Agent）プロトコルを完全に実装し、以下を可能にします：

エージェントカードを通じた標準化されたエージェント発見
処理中のリアルタイムステータス更新
適切なタスクライフサイクル管理
より良いユーザーエクスペリエンスのためのストリーミングレスポンス

プロキシサポート

内蔵プロキシサポートにより、制限されたネットワーク環境でもエージェントが動作することを保証し、以下をサポートします：

SOCKS5プロキシ
HTTP/HTTPSプロキシ
設定可能なプロキシ設定

使用例

基本的な映画検索

ユーザー: "インセプションという映画について教えて"
エージェント: [インセプションを検索し、詳細、キャスト、プロットを取得]

複雑なクエリ

ユーザー: "クリストファー・ノーラン監督の2020年のSF映画を見つけて"
エージェント: [複数のツールを使用して結果を検索しフィルタリング]

俳優情報

ユーザー: "レオナルド・ディカプリオが最近出演した映画は？"
エージェント: [俳優を検索し、最近のフィルモグラフィーをリスト]

開発とデプロイメント

プロジェクトには包括的な開発ツールが含まれています：

TypeScript: コードベース全体での完全な型安全性
ESLint & Prettier: コード品質とフォーマット
Bun: 高速なパッケージ管理と実行
モジュラーアーキテクチャ: 拡張と保守が容易

結論

このA2A JS映画エージェントは、Agent2Agentフレームワークの洗練された実装を実演し、現代的なWeb技術とAI機能を組み合わせて強力な映画情報システムを作成します。このプロジェクトは、外部APIと相互作用し、ユーザークエリに対して豊富で文脈的なレスポンスを提供できるインテリジェントで会話型のエージェントを構築する方法の優れた例として機能します。

モジュラー設計、包括的なエラーハンドリング、A2Aプロトコルへの準拠により、このプロジェクトは学習目的と本番デプロイメントシナリオの両方に適しています。