金大哥 - medical-agents-aop-server MCP 详情

article

README

🚀 医疗代理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

medical-agents-aop-server