多智能体实验室
项目介绍
多代理实验室 🤖
📚 教育目的
该项目专为教育和演示目的而开发，旨在通过使用Google ADK（代理开发工具包）来展示多代理系统的基本概念。
⚠️ 重要提示这不是一个生产示例！这是一个教学实验室，用于理解：
- 如何实现分层的代理架构
- 专门代理之间的集成
- 使用MCP（模型上下文协议）协议
- 由AI代理执行工具
- 多个语言模型之间的协调
🏗️ 系统架构
概述
该系统模拟了一个提供健康咨询服务的电子商务平台，其中不同的专业代理协同工作以服务客户。
根代理（主协调员）
├── 购物助手（产品专家）
│ └── 帮助客户（MCP接口）
├── 销售代理（销售专家）
│ ├── 创建订单（订单创建）
│ ├── 计费（账单处理）
│ └── 库存管理（库存控制）
└── 健康助手（健康顾问）
├── 营养专家（营养/皮肤护理专家）
└── 运动专家（运动建议专家）
🧩 实现组件
一 Vitra AI（主系统）
- 根代理 主协调员，负责分配任务给子代理
- 专用提示 每个代理的具体指令
- 多种模型：Gemini、Claude 和 Llama 通过 LiteLLM
二 搜索MCP服务器（工具服务器）
- 搜索产品 与搜索系统（MeiliSearch）接口
- 支付计划 融资选项的模拟
- 日志记录 所有操作的记录以供审计
三 专业子代理
购物助手
- 功能 推荐和搜索产品
- 工具 访问MCP服务器进行查询
- 模型：Claude 3.5 Sonnet
销售代理
- 功能 完整的订单处理
- 子代理：
- 创建订单 订单的创建和管理
- 计费 发票生成
- 库存管理 库存控制
- 工具 自定义电子商务功能
健康助手
- 功能 健康和保健咨询
- 子代理：
- 营养专家 皮肤护理和营养
- 运动专家 运动建议和锻炼
- 模型：Gemini 2.5 Flash 和 Flame 3.1 8B
🚀 如何执行项目
预备条件
- Python 3.13+
- UV（Python包管理器）
- 在7700端口运行的MeiliSearch（可选 - 见下文替代方案）
1. 安装依赖项
# 克隆仓库
git clone <你的仓库>
cd multi_agent_lab
# 安装主系统的依赖项
cd vitra_ai
uv sync
# 安装MCP服务器的依赖项
cd ../search_mcp_server
uv sync
2. 配置模型
确保已配置API密钥：
# 对于Claude（Anthropic）
export ANTHROPIC_API_KEY="你的密钥"
# 对于Gemini（Google）
export GOOGLE_API_KEY="你的密钥"
# 对于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应该始终在一个比项目文件夹高一级的文件夹中运行，而不是在项目文件夹内部。
🔧 自定义MCP服务器
MeiliSearch的替代方案
文件search_mcp_server/help_customer.py可以轻松修改以使用其他数据源：
一 本地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}
二 外部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()
三 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}
四 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 # 本文件
🎯 展示的概念
一 代理层次结构
- 如何组织分层的代理结构
- 专门代理之间的任务委托
- 多个子系统的协调
二 MCP协议
- 外部工具的实现
- 代理和服务之间的通信
- 操作的日志记录和审计
三 多模型集成
- 同时使用不同的大语言模型
- 任务类型的专门化
- 按代理设置参数
四 自定义工具
- 创建特定领域的工具
- 数据在文件中的持久化
- 外部系统的模拟
🧪 实验与学习
修改建议
- 添加新的代理 创建客户服务代理
- 实现新工具 添加与真实API的集成
- 实验模型 测试其他大语言模型或调整参数
- 改进日志 实现结构化的JSON日志
- 添加验证 实现在代理之间进行数据验证
注意事项
- 硬编码路径：路径固定，需适应您的环境
- 认证：为了教育目的，令牌暴露在外
- 错误处理：最小实现，仅适用于演示
- 性能：未针对生产优化
📖 额外资源
🤝 贡献
这是一个教育项目！随意：
- 分叉并实验
- 建议教学改进
- 添加用例示例
- 报告错误或不一致之处
记住这个项目是一个学习工具。使用它来理解概念，实验修改，并适应您的教育需求！换句话说，就是这么回事。🚀