Medical Agents Aop Server

🚀 醫療代理AOP服務器

這是一個可用於生產環境的模板，藉助swarms庫中的AOP（代理編排協議），將多個專業醫療代理部署為MCP工具。此服務器將代理作為可調用工具公開，任何兼容MCP的客戶端都能發現並執行這些工具。

🚀 快速開始

本倉庫的app.py文件中包含一個可直接運行的服務器，它會註冊六個醫療代理。

python app.py

默認情況下，服務器會在端口8000啟動，並使用代理的agent_name將每個代理註冊為MCP工具。你會看到日誌顯示服務器名稱（MedicalAgentServer）和已註冊的工具。

✨ 主要特性

• 多個專注於特定領域的醫療代理（實驗室檢測、ICD - 10映射、治療方案、藥物相互作用、影像分診、臨床筆記總結）
• 單個AOP服務器，將每個代理註冊為MCP工具
• 合理的默認設置、安全提示和結構化輸出
• 清晰的自定義和MCP客戶端使用示例

📦 安裝指南

pip install -r requirements.txt

💻 使用示例

基礎用法

運行服務器

python app.py

使用MCP Python客戶端（官方）

安裝客戶端：

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設置（端口、主機、日誌記錄、隊列）

在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

示例：

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,
)

添加或修改代理

代理通過清晰的系統提示和元數據進行定義，然後添加到服務器。你可以一次添加一個或多個代理。

最小示例（單個代理）：

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="...")覆蓋工具名稱和描述。

運行示例腳本

本倉庫在examples/目錄中包含了使用官方MCP可流式HTTP客戶端的可運行示例。

設置：

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使用代理

服務器運行後，每個代理都會作為MCP工具公開。所有工具都接受一組通用參數：

• task（必需）：主要指令或提示
• img（可選）：單個圖像路徑/URI
• imgs（可選）：圖像路徑/URI列表
• correct_answer（可選）：用於驗證或比較

所有工具返回：

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

發現和隊列管理工具

啟用基於隊列的執行時，服務器還會公開管理和發現工具，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