Multi-Agent Task Assistant with A2A & MCP-inspired Architecture

A2A と MCP に着想を得たアーキテクチャによるマルチエージェントタスクアシスタント

このプロジェクトでは、記事の草稿作成やウェブ調査などのタスク向けに設計されたマルチエージェントシステムを紹介します。エージェント間の連携には、独自のエージェント間（A2A）通信プロトコルを採用し、外部ツールサーバーとの連携には、Model Context Protocol（MCP）に着想を得たアーキテクチャを採用しています。このシステムは、Python、Langchain、Anthropic LLM、FastAPI、Docker を使用して構築されています。

概要

Task Assistant では、特定のトピックに関する記事の草稿作成や、ウェブ調査を依頼できます。ユーザーの入力はまず「Supervisor LLM」によって検証・処理されます。検証済みのタスクは Task Manager Agent が管理し、専門エージェントである Article Draft Agent と Researcher Agent にサブタスクを割り当てます。これらのエージェントは、専用の「MCP Tool Servers」を通じて、LLM によるテキスト生成、ウェブ検索、クラウドストレージなどの外部機能を利用します。ユーザーインターフェースには Streamlit アプリケーションを使用しています。

• 各言語で入力された内容を英語に出力する仕様に変更されています。

システムの使用例はこちらをご覧ください。

重要：Google Cloud 認証（google_credentials.json）

Cloud Storage MCP Server が Google Cloud Storage と連携するには、サービスアカウントを設定し、その JSON キーを用意する必要があります。

1. サービスアカウントの作成： Google Cloud Platform（GCP）プロジェクトで、新しいサービスアカウントを作成します。
2. 権限の付与： 対象の GCS バケットからの読み取りと書き込みを許可するために、必要なロール／権限をこのサービスアカウントに割り当てます（たとえば「Storage Object Admin」、または特定のバケットに対する「Storage Object Creator」と「Storage Object Viewer」のような、より限定的な権限）。
3. JSON キーの生成： このサービスアカウントの JSON キーを作成し、ダウンロードします。
4. キーの配置と名前の変更： ダウンロードした JSON キーファイルをこのプロジェクトのルートディレクトリに配置し、名前を google_credentials.json に変更します。

⚠️ セキュリティに関する注意： この google_credentials.json ファイルには機密性の高い認証情報が含まれています。バージョン管理システムに絶対にコミットしないでください（まだ追加されていない場合は、.gitignore ファイルに追加してください）。docker-compose.yml ファイルでは、このファイルをプロジェクトのルートから cloud-storage-mcp サービスにマウントするよう設定されています。

システムアーキテクチャ

機能

• 記事の草稿作成： 指定されたトピックとスタイルに基づいて記事の草稿を生成し、Google Cloud Storage に保存して、公開 URL を提供します。
• ウェブ調査： トピックに関する模擬的なウェブ調査を行い、調査結果を要約したリストを返します。
• Supervisor LLM による入力検証： ユーザーの入力はエージェントに割り当てられる前に LLM によって前処理され、安全性が検証され、英語に翻訳されます。
• エージェント間（A2A）通信： エージェントがタスクを割り当て、ステータスの更新を送信し、結果を返すための独自プロトコルです。
• Model Context Protocol（MCP）に着想を得たツール機能： 専門サーバーが、MCP に似たリクエスト／レスポンス方式を通じて、LLM による生成、Cloud Storage、Web Search などのツールを公開します。
• 非同期タスク処理： タスクは非同期で処理され、UI はステータスの更新をポーリングします。
• マイクロサービスアーキテクチャ： 各コンポーネントは Docker を使用してコンテナ化され、Docker Compose でオーケストレーションされます。

LLM モデルの使用

このプロジェクトでは、さまざまな機能に複数の Anthropic Claude モデルを活用しています。

• スーパーバイザー LLM（入力の検証と処理）：

  • モデル： claude-3-7-sonnet-20250219
  • コンポーネント： Streamlit UI（ui/streamlit/app.py）から直接呼び出されます。
  • 目的： タスクを割り当てる前に、ユーザー入力（トピック、スタイル）を検証、サニタイズ、有害なコンテンツの確認、言語の特定、英語への翻訳を行います。

• 記事ドラフトエージェント（中核となるエージェントのロジック）：

  • モデル： claude-3-haiku-20240307
  • コンポーネント： agents/article_draft/main.py
  • 目的： Langchain エージェントの意思決定プロセス（使用するツールの決定、操作の順序、ツールの出力に基づく最終回答の作成など）を担います。

• リサーチャーエージェント（中核となるエージェントのロジック）：

  • モデル： claude-3-haiku-20240307
  • コンポーネント： agents/researcher/main.py
  • 目的： リサーチタスクにおける Langchain エージェントの意思決定と、search_web ツールで得られた調査結果の要約を担います。

• クリエイティブ LLM MCP サーバー（テキスト生成ツール）：

  • モデル： claude-3-5-sonnet-20241022
  • コンポーネント： mcp_servers/creative_llm/main.py
  • 目的： Article Draft Agent が記事コンテンツの作成に使用する generate_text ツールを提供します。

• ウェブ検索 MCP サーバー（シミュレートされたウェブ検索ツール）：

  • モデル： claude-3-haiku-20240307
  • コンポーネント： mcp_servers/web_search/main.py
  • 目的： Researcher Agent がクエリに基づくシミュレートされた検索結果の生成に使用する search_web ツールを提供します。

注：Task Manager Agent と Cloud Storage MCP Server は、中核となる処理で LLM を直接使用しません。

アーキテクチャ

システムは、次の主要なコンポーネントで構成されています。

1. Streamlit UI（streamlit-ui）： ユーザーがタスクを送信し、結果を確認するためのウェブインターフェースです。Supervisor LLM の呼び出しも行います。
2. Supervisor LLM（外部呼び出し）： UI から直接呼び出され、ユーザー入力の検証、サニタイズ、翻訳を行う Anthropic Claude モデルです。
3. Task Manager エージェント（task-manager）：
   • UI から検証済みのタスクを受け取ります。
   • A2A プロトコルを使用して、適切なワーカーエージェントにタスクを割り当てます。
   • タスクのステータスを追跡し、UI に更新情報を提供します。
   • A2A プロトコルを介してワーカーエージェントから結果を受け取ります。
4. ワーカーエージェント：
   • Article Draft エージェント（article-draft-agent）： 記事コンテンツの生成（Creative LLM MCP サーバーを使用）とアップロード（Cloud Storage MCP サーバーを使用）を担当する Langchain エージェントです。
   • Researcher エージェント（researcher）： 調査（Web Search MCP サーバーを使用）を担当する Langchain エージェントです。
5. MCP ツールサーバー：
   • Creative LLM MCP サーバー（creative-llm-mcp）： Anthropic LLM を利用する generate_text ツールを提供します。
   • Cloud Storage MCP サーバー（cloud-storage-mcp）： Google Cloud Storage 用の upload_file、download_file、delete_file ツールを提供します。
   • Web Search MCP サーバー（web-search-mcp）： Anthropic LLM を使用してウェブ検索結果をシミュレートする search_web ツールを提供します。
6. 通信プロトコル：
   • カスタム A2A プロトコル： protocols/messages.py で定義されています（例：A2AMessage、A2APayloadAssignTask）。HTTP 経由で Task Manager とワーカーエージェント間の通信に使用されます。
   • MCP に着想を得たカスタムプロトコル： protocols/messages.py で定義されています（例：MCPToolCall、MCPToolResult）。Langchain ツールが（tools/mcp_tool_adapter.py を介して）HTTP 経由で MCP ツールサーバーと通信するために使用されます。

概要フロー（記事タスクの例）：

1. ユーザーが Streamlit UI から記事のトピックやスタイルを送信します。
2. UI が入力の検証と処理のために Supervisor LLM を呼び出します。
3. 承認された場合、UI は task-manager エージェントにリクエストを送信します。
4. task-manager は「write_article_draft」タスクを article-draft-agent に割り当てます（A2A）。
5. article-draft-agent は generate_text_tool を使用します。
   • ツールは creative-llm-mcp サーバー（MCP）を呼び出し、記事コンテンツを生成します。
6. 続いて、article-draft-agent は upload_file_tool を使用します。
   • ツールは cloud-storage-mcp サーバー（MCP）を呼び出し、コンテンツをアップロードして公開 URL を取得します。
7. article-draft-agent は公開 URL を task-manager に返します（A2A）。
8. UI は task-manager にステータスをポーリングし、URL を取得してコンテンツを読み込み、表示します。

使用されている主要なテクノロジー

• Python 3.9
• フレームワークとライブラリ：
  • FastAPI：エージェントと MCP サーバーの API の構築に使用します。
  • Uvicorn：FastAPI 用の ASGI サーバーです。
  • Langchain と Langchain-Anthropic：LLM を利用するエージェントとツールの構築に使用します。
  • Anthropic Python SDK：Supervisor LLM と LLM ツールに使用します。
  • Pydantic：プロトコルのデータ検証と設定管理に使用します。
  • Streamlit：ユーザーインターフェースに使用します。
  • Requests：HTTP 通信に使用します。
  • Google Cloud Storage SDK（google-cloud-storage）：ファイルストレージに使用します。
• コンテナ化：
  • Docker
  • Docker Compose
• クラウドサービス：
  • Anthropic API（Claude モデル）
  • Google Cloud Storage

プロジェクト構成

├── agents/
│   ├── article_draft/
│   │   ├── Dockerfile
│   │   └── main.py
│   ├── researcher/
│   │   ├── Dockerfile
│   │   └── main.py
│   └── task_manager/
│       ├── Dockerfile
│       └── main.py
├── mcp_servers/
│   ├── cloud_storage/
│   │   ├── Dockerfile
│   │   └── main.py
│   ├── creative_llm/
│   │   ├── Dockerfile
│   │   ├── main.py
│   └── web_search/
│       ├── Dockerfile
│       └── main.py
├── protocols/
│   └── messages.py       # Pydantic models for A2A and MCP communication
├── tools/
│   ├── generate_text_tool.py
│   ├── mcp_tool_adapter.py # Client for calling MCP tool servers
│   ├── research_tool.py
│   └── upload_file_tool.py
├── ui/
│   └── streamlit/
│       ├── Dockerfile
│       ├── app.py
│       └── requirements.txt
├── .env                    # For API keys and environment variables (create this)
├── config.py               # Internal service URLs
├── docker-compose.yml      # Docker Compose orchestration
└── google_credentials.json # Google Cloud service account key (create this)

前提条件

• Docker と Docker Compose がインストールされていること。
• Anthropic API キーがあること。
• 以下を備えた Google Cloud プロジェクトがあること：
  • Google Cloud Storage API が有効になっていること。
  • GCS バケットが作成されていること。
  • GCS バケットへの書き込み権限を持つサービスアカウントキー（google_credentials.json）があること。

プロジェクトのセットアップと実行

1. リポジトリのクローン（例）：

   git clone https://github.com/ogulcanakca/article-assistant
   cd article-assistant
   

2. .env ファイルの作成： プロジェクトのルートに .env ファイルを作成し、認証情報と設定を追加します。

   ANTHROPIC_API_KEY="sk-ant-..."
   GOOGLE_API_KEY="AIzaSy..." # 他のGoogleサービスで必要な場合。サービスアカウントを使用してGCSのみを利用する場合は省略できます
   GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
   CLOUD_STORAGE_BUCKET_NAME="your-gcs-bucket-name" # article_draft_agentで使用
   

   • CLOUD_STORAGE_BUCKET_NAME は、記事の保存先となるGCSバケットの名前です。

3. Google Cloud 認証情報の追加： ダウンロードした Google Cloud サービスアカウントのキー ファイルをプロジェクトのルートに置き、google_credentials.json という名前を付けます。このファイルは docker-compose.yml によって cloud-storage-mcp サービスにマウントされます。

4. 各サービスの requirements.txt の作成： 各サービスのディレクトリ（agents/*、mcp_servers/*、ui/streamlit）に、それぞれの Python 依存関係を記載した requirements.txt ファイルがあることを確認します。例：

   • agents/article_draft/requirements.txt：

     fastapi
     uvicorn
     langchain
     langchain-anthropic
     requests
     # pydanticは通常、FastAPI/Langchainの推移的依存関係です
     

   • mcp_servers/cloud_storage/requirements.txt：

     fastapi
     uvicorn
     google-cloud-storage
     requests
     

   • ui/streamlit/requirements.txt：

     streamlit
     requests
     anthropic
     

   (各 main.py ファイルで実際にインポートされている内容に応じて、これらのリストを調整してください。)

5. Docker Compose でのビルドと実行： プロジェクトのルートディレクトリから、次を実行します。

   docker-compose up --build
   

6. UI へのアクセス： サービスが起動したら、Web ブラウザーを開いて次の URL にアクセスします。 http://localhost:8501

7. サービスの停止：

   docker-compose down
   

注意事項

• web-search-mcp サーバーは現在、LLM を使ってWeb検索結果をシミュレートしています。実際のライブ検索は実行しません。
• 必要な環境変数（特に API キーと GCS バケット名）が .env ファイルに正しく設定され、docker-compose.yml で各サービスに渡されていることを確認してください。
• .env 内の GOOGLE_API_KEY は、他の Google サービスを API キーで直接使用する場合に備えて記載しています。Google Cloud Storage では、cloud-storage-mcp サービスの主な認証方法として google_credentials.json のサービスアカウントが使用されます。

タスク 1 とタスク 2 の例