Medical Agents Aop Server

🚀 医療エージェントAOPサーバー

swarmsライブラリのAOP（エージェントオーケストレーションプロトコル）を使用して、複数の専門医療エージェントをMCPツールとしてデプロイするための本番環境対応テンプレートです。このサーバーは、エージェントを呼び出し可能なツールとして公開し、MCP互換のクライアントがそれらを検出して実行できるようにします。

✨ 主な機能

• 複数の専門分野に特化した医療エージェント（検査室、ICD - 10マッピング、治療オプション、薬物相互作用、画像トリアージ、臨床ノート要約）
• 各エージェントをMCPツールとして登録する単一のAOPサーバー
• 適切なデフォルト設定、安全に関する文言、および構造化された出力
• カスタマイズとMCPクライアント使用の明確な例

📦 インストール

pip install -r requirements.txt

🚀 クイックスタート

このリポジトリには、6つの医療エージェントを登録する実行可能なサーバーが app.py として含まれています。

python app.py

デフォルトでは、サーバーはポート 8000 で起動し、各エージェントを agent_name を使用してMCPツールとして登録します。サーバー名（MedicalAgentServer）と登録されたツールを示すログが表示されます。

💻 使用例

基本的な使用法

# サーバーを起動する基本的なコード
python app.py

高度な使用法

# AOP設定のカスタマイズ例
deployer = AOP(
    server_name="MedicalAgentServer",
    port=8010,
    host="0.0.0.0",
    verbose=True,
    log_level="DEBUG",
    queue_enabled=True,
    max_workers_per_agent=2,
    max_queue_size_per_agent=500,
    processing_timeout=60,
    retry_delay=2.0,
)

📚 ドキュメント

AOP設定のカスタマイズ（ポート、ホスト、ログ、キュー）

app.py では、AOPインスタンスは以下のように作成されます。

deployer = AOP(
    server_name="MedicalAgentServer",
    description="...",
    port=8000,
    verbose=True,
    log_level="INFO",
)

以下の設定を調整できます。

• port：リスニングポートを変更します（例：port=8010）
• host：外部にバインドします（例：host="0.0.0.0"）
• verbose と log_level：ログレベルを増減します（"DEBUG"、"INFO"、"WARNING"、"ERROR"）
• 高スループットのためのキューオプション：
  • queue_enabled=True
  • max_workers_per_agent=2
  • max_queue_size_per_agent=500
  • processing_timeout=60
  • retry_delay=2.0

エージェントの追加または変更

エージェントは、明確なシステムプロンプトとメタデータで定義され、サーバーに追加されます。一度に1つまたは複数のエージェントを追加できます。

最小限の例（単一エージェント）：

from swarms import Agent

my_agent = Agent(
  agent_name="My-Custom-Agent",
  agent_description="Explains X and summarizes Y for educational purposes",
  model_name="claude-haiku-4-5",
  max_loops=1,
  dynamic_temperature_enabled=True,
  system_prompt="""You are a helpful specialist...""",
  tags=["custom"],
  capabilities=["explanation"],
  role="worker",
)

deployer.add_agent(my_agent)

一括登録（このリポジトリで使用されている方法）：

agents = [agent_a, agent_b, agent_c]
deployer.add_agents_batch(agents)

ツール名について：

• デフォルトでは、ツール名は agent.agent_name と同じになります。分かりやすく安定した名前を選んでください（例："Blood-Data-Analysis-Agent"）。
• add_agent(agent, tool_name="...", tool_description="...") でツール名と説明を上書きできます。

MCPを通じたエージェントの使用方法

サーバーが起動すると、各エージェントはMCPツールとして公開されます。すべてのツールは共通のパラメータセットを受け付けます。

• task（必須）：主な指示またはプロンプト
• img（オプション）：単一の画像パス/URI
• imgs（オプション）：画像パス/URIのリスト
• correct_answer（オプション）：検証または比較用

すべてのツールは以下の形式で返します。

{
  "result": "string",
  "success": true,
  "error": null
}

公式MCP Pythonクライアントの使用

公式の mcp Pythonクライアント（ストリーミング可能なHTTPトランスポート）を使用して、このAOPサーバーに接続し、ツールを検出してエージェントを呼び出すことができます。

インストール：

pip install mcp

ツールの一覧表示とエージェントの呼び出し：

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

AOP_URL = "http://localhost:8000/mcp"  # ホスト/ポートを変更した場合は調整してください

async def main():
    async with streamablehttp_client(AOP_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 1) 利用可能なツール（登録されたエージェント）の一覧を表示
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])

            # 2) ツール名で特定のエージェントを呼び出す
            tool_name = "Blood-Data-Analysis-Agent"  # 登録した任意のエージェント名に置き換えてください
            result = await session.call_tool(
                tool_name,
                arguments={
                    "task": "Interpret this CBC: WBC 15.2, HGB 10.1, PLT 420",
                    # このサーバーのスキーマに従ったオプションの追加項目:
                    # "img": "/path/to/image.png",
                    # "imgs": ["/path/a.png", "/path/b.png"],
                    # "correct_answer": "..."
                },
            )
            print("Agent result:", result)  # CallToolResult

asyncio.run(main())

注意事項

• AOP_URL は、このリポジトリのサーバー構成に基づき、デフォルトで http://localhost:8000/mcp となります。
• すべてのエージェントは同じ入力パラメータを共有します：task（必須）、およびオプションの img、imgs、correct_answer。

（MCPクライアントの）使用例

このリポジトリには、examples/ ディレクトリに公式のMCPストリーミング可能なHTTPクライアントを使用した実行可能な例が含まれています。

• examples/get_server_info.py：利用可能なツールと、公開されている場合のAOPエージェント名を表示
• examples/list_tools.py：すべての登録されたツール（エージェント）を一覧表示
• examples/call_agent.py：task を指定して特定のエージェントを呼び出す
• examples/discover_and_call.py：エージェントを検出し、1つを呼び出す（指定されたタグがある場合はそれを優先）
• examples/queue_management.py：特定のエージェントのキューの統計情報を表示/一時停止/再開/クリア
• examples/search_agents.py：キーワード/フィールドでエージェントを検索

セットアップ：

pip install -r requirements.txt
# オプション: 別のサーバーを指定する
export AOP_URL="http://localhost:8000/mcp"

実行：

# ツールの一覧表示
python examples/list_tools.py

# エージェントを呼び出す（環境変数で設定、CLIフラグは不要）
export AGENT_NAME="Blood-Data-Analysis-Agent"
export AGENT_TASK="Interpret this CBC..."
# オプション:
# export AGENT_IMG="/path/to/image.png"
# export AGENT_IMGS="/path/a.png,/path/b.png"
# export AGENT_CORRECT_ANSWER="..."
python examples/call_agent.py

# エージェントを検出して呼び出す（環境変数で設定）
export PREFER_TAG="research"
export FALLBACK_NAME="Blood-Data-Analysis-Agent"
export TASK="Provide a brief summary of CBC interpretation basics."
python examples/discover_and_call.py

# キュー管理（統計情報|一時停止|再開|クリア）
export AGENT_NAME="Blood-Data-Analysis-Agent"
export QUEUE_ACTION="stats"
python examples/queue_management.py

# エージェントを検索する（環境変数で設定）
export SEARCH_QUERY="research"
# オプション: export SEARCH_FIELDS="name,description,tags,capabilities"
python examples/search_agents.py

検出とキュー管理ツール

キューベースの実行が有効になっている場合、サーバーはMCPクライアントが呼び出せる管理および検出ツールも公開します。

• discover_agents(agent_name: Optional[str])：エージェントに関する情報（名前、説明、タグ、機能）を取得
• get_agent_details(agent_name: str)：エージェントの詳細な構成と検出情報
• get_agents_info(agent_names: List[str])：複数のエージェントの一括詳細情報
• list_agents()：利用可能なエージェント名のリスト
• search_agents(query: str, search_fields: Optional[List[str]])：キーワード検索
• get_queue_stats(agent_name: Optional[str])：キューの統計情報
• pause_agent_queue(agent_name: str)、resume_agent_queue(agent_name: str)、clear_agent_queue(agent_name: str)
• get_task_status(agent_name: str, task_id: str)

これらは、マルチエージェントワークフローにおける動的なエージェント検出、監視、および運用管理に役立ちます。

安全性と適用範囲

• すべてのエージェントは、教育目的で非診断的な出力を生成するように設計されています。
• 応答は、指示を避け、適切な場合は不確実性を強調します。
• 出力は常に許可を得た臨床医や信頼できる情報源で検証してください。

トラブルシューティング

• ポートが既に使用中の場合：AOPコンストラクタの port を変更するか、ポートを解放してください。
• 認証/モデルの問題：指定された model_name 用に環境を構成していることを確認してください（APIキー、エンドポイント）。
• クライアントでツールが表示されない場合：クライアントからサーバーにアクセスできること、およびエージェントが登録されていることを確認してください（ログ、list_agents）。
• 高スループットの場合：キュー設定を有効にし、max_workers_per_agent を増やしてください。

📄 ライセンス

このプロジェクトは LICENSE で指定された条件に基づいてライセンスされています。

🔗 参考文献

• swarms.structs.aop のAOPクラスとメソッド（このリポジトリは docs.txt の機能を反映しています）
• 具体的なエージェント定義とサーバー設定については app.py を参照してください。