Multi Agent Lab

🚀 マルチエージェントラボ 🤖

このプロジェクトは、Google ADK (Agent Development Kit) を使用してマルチエージェントシステムの基本概念を説明するために、教育およびデモンストレーション目的でのみ開発されました。

⚠️ 重要提示

これは本番環境向けのサンプルではありません！以下の内容を理解するための教育用ラボです。

• エージェントの階層的アーキテクチャを実装する方法
• 専門エージェント間の統合
• MCP (Model Context Protocol) プロトコルの使用
• AIエージェントによるツール（tools）の実行
• 複数の言語モデル間の協調

🚀 クイックスタート

システムの概要

このシステムは、健康相談付きの電子商取引をシミュレートしており、異なる専門エージェントが協力して顧客に対応します。

Root Agent (主なコーディネーター)
├── Shop Mate (商品専門家)
│   └── Help Customer (MCPインターフェース)
├── Seller Agent (販売専門家)
│   ├── Create Order (注文作成)
│   ├── Billing (請求書発行)
│   └── Manage Stock (在庫管理)
└── Health Mate (健康相談員)
    ├── Nutra Specialist (栄養/皮膚専門家)
    └── Workout Specialist (運動専門家)

実装されたコンポーネント

1. Vitra AI (主要システム)

• Root Agent: タスクをサブエージェントに委任する主なコーディネーター
• 専用のプロンプト: 各エージェントに対する特定の指示
• 様々なモデル: LiteLLM経由でGemini、Claude、およびLlama

2. Search MCP Server (ツールサーバー)

• 商品検索: 検索システム（MeiliSearch）とのインターフェース
• 支払いプラン: 融資オプションのシミュレーション
• ロギング: すべての操作を監査用に記録

3. 専門サブエージェント

Shop Mate

• 機能: 商品の推薦と検索
• ツール: 照会のためのMCPサーバーへのアクセス
• モデル: Claude 3.5 Sonnet

Seller Agent

• 機能: 注文の完全な処理
• サブエージェント:
  • Create Order: 注文の作成と管理
  • Billing: 請求書の生成
  • Manage Stock: 在庫管理
• ツール: 電子商取引のカスタム関数

Health Mate

• 機能: 健康と幸福に関する相談
• サブエージェント:
  • Nutra Specialist: 皮膚ケアと栄養に関する専門家
  • Workout Specialist: 運動とトレーニングのヒント
• モデル: Gemini 2.5 FlashおよびLlama 3.1 8B

プロジェクトの実行方法

前提条件

• Python 3.13以上
• UV (Pythonパッケージマネージャー)
• ポート7700で実行されているMeiliSearch (オプション - 以下の代替案を参照)

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

# リポジトリをクローン
git clone <seu-repositorio>
cd multi_agent_lab

# 主要システムの依存関係をインストール
cd vitra_ai
uv sync

# MCPサーバーの依存関係をインストール
cd ../search_mcp_server
uv sync

2. モデルの設定

APIキーが設定されていることを確認してください。

# Claude (Anthropic)の場合
export ANTHROPIC_API_KEY="sua_chave_aqui"

# Gemini (Google)の場合
export GOOGLE_API_KEY="sua_chave_aqui"

# Ollama (ローカル)の場合
# Ollamaをインストールし、llama3.1:8bモデルをダウンロード
ollama pull llama3.1:8b

3. システムの実行

オプション1: MeiliSearchを使用する場合 (完全版)

# ターミナル1: MeiliSearchを起動
docker run -it --rm -p 7700:7700 getmeili/meilisearch:v1.5

# ターミナル2: MCPサーバーを実行
cd search_mcp_server
uv run help_customer.py

# ターミナル3: 主要システムを実行
cd vitra_ai
uv run agent.py

オプション2: MeiliSearchを使用しない場合 (シミュレート版)

# 主要システムのみ (モックデータを使用)
cd vitra_ai
uv run agent.py

4. ADK Webインターフェースでのテスト

ADKのWebインターフェースを使用してシステムをテストするには、以下の手順を実行します。

# 1. まず、依存関係をインストール
cd vitra_ai
uv sync

# 2. 仮想環境をアクティブ化
source .venv/bin/activate

# 3. プロジェクトのルートディレクトリに戻る
cd ..

# 4. ADK Webを実行 (プロジェクトディレクトリの上位ディレクトリで実行する必要があります)
adk web

⚠️ 重要提示

adk web コマンドは、常にプロジェクトディレクトリの親ディレクトリで実行する必要があり、プロジェクトディレクトリ内では実行しないでください。

✨ 主な機能

デモンストレーションされる概念

1. エージェントの階層構造

• エージェントを階層的構造で組織する方法
• 専門エージェント間のタスクの委任
• 複数のサブシステムの協調

2. MCPプロトコル

• 外部ツールの実装
• エージェントとサービス間の通信
• 操作のロギングと監査

3. マルチモデル統合

• 異なるLLMの同時使用
• タスクの種類による専門化
• エージェントごとのパラメータ設定

4. カスタムツール

• ドメイン固有のツールの作成
• ファイルへのデータの永続化
• 外部システムのシミュレーション

📦 インストール

MCPサーバーのカスタマイズ

MeiliSearchの代替案

search_mcp_server/help_customer.py ファイルは、他のデータソースを使用するように簡単に変更できます。

1. ローカルJSONファイル

import json

@mcp.tool()
def search_products_by_terms(terms: str):
    with open("products.json", "r") as f:
        products = json.load(f)
    # 単純な用語検索を実装
    results = [p for p in products if terms.lower() in p['name'].lower()]
    return {"hits": results}

2. 外部REST API

@mcp.tool()
def search_products_by_terms(terms: str):
    # 商品APIの例
    response = requests.get(f"https://api.mercadolibre.com/sites/MLB/search?q={terms}")
    return response.json()

3. SQLiteデータベース

import sqlite3

@mcp.tool()
def search_products_by_terms(terms: str):
    conn = sqlite3.connect("products.db")
    cursor = conn.execute("SELECT * FROM products WHERE name LIKE ?", (f"%{terms}%",))
    results = cursor.fetchall()
    conn.close()
    return {"hits": results}

4. Elasticsearch

from elasticsearch import Elasticsearch

es = Elasticsearch([{'host': 'localhost', 'port': 9200}])

@mcp.tool()
def search_products_by_terms(terms: str):
    response = es.search(
        index="products",
        body={"query": {"match": {"name": terms}}}
    )
    return response

📚 ドキュメント

プロジェクトの構造

multi_agent_lab/
├── vitra_ai/                    # 主要エージェントシステム
│   ├── agent.py                 # ルートエージェントの設定
│   ├── prompt.py                # プロンプトと指示
│   ├── sub_agents/              # 専門エージェント
│   │   ├── shop_mate/           # 商品専門家
│   │   ├── seller/              # 販売専門家
│   │   └── health_mate/         # 健康相談員
│   ├── vitra_doc/               # システムのログ
│   └── pyproject.toml           # 依存関係
├── search_mcp_server/           # MCPツールサーバー
│   ├── help_customer.py         # ツールの実装
│   ├── log/                     # 操作のログ
│   └── pyproject.toml           # 依存関係
└── README.md                    # このファイル

🧪 実験と学習

変更の提案

1. 新しいエージェントの追加: 顧客サポートエージェントを作成
2. 新しいツールの実装: 実際のAPIとの統合を追加
3. モデルの実験: 他のLLMをテストまたはパラメータを調整
4. ロギングの改善: JSONを使用した構造化ロギングを実装
5. バリデーションの追加: エージェント間のデータバリデーションを実装

注意点

• ハードコードされたパス: パスは固定されているため、環境に合わせて調整してください。
• 認証: トークンは教育目的で公開されています。
• エラーハンドリング: 最低限の実装で、デモンストレーションにのみ適しています。
• パフォーマンス: 本番環境向けに最適化されていません。

📖 追加リソース

• Google ADK Documentation
• MCP Protocol Specification
• LiteLLM Documentation

🤝 コントリビューション

これは教育用のプロジェクトです！自由に以下のことを行ってください。

• フォークして実験する
• 教育的な改善案を提案する
• 使用例を追加する
• バグや不整合を報告する

💡 使用建议

このプロジェクトは学習ツールです。概念を理解し、変更を試し、教育上のニーズに合わせて調整してください！ 🚀