Multi Agent Lab

🚀 多智能体实验室 🤖

本项目专为 教育和演示目的 而开发，旨在使用 Google ADK（智能体开发套件）阐释多智能体系统的基本概念。

⚠️ 重要提示：这并非生产环境示例，而是一个教学实验室，用于理解以下内容：

• 如何实现智能体的分层架构
• 专业智能体之间的集成
• MCP（模型上下文协议）的使用
• 人工智能智能体执行工具的操作
• 多个语言模型之间的协调

✨ 主要特性

• 教育演示：专注于多智能体系统基础概念的教育与展示。
• 系统模拟：模拟具备健康咨询功能的电子商务场景，多个专业智能体协同工作服务客户。
• 多模型支持：支持使用 Gemini、Claude 和 Llama 等多种语言模型。
• 灵活配置：可根据需求选择不同的数据来源，如 MeiliSearch、本地 JSON 文件、外部 REST API、SQLite 数据库和 Elasticsearch。
• 实验性强：提供丰富的实验建议，便于用户深入理解和探索多智能体系统。

📦 安装指南

前置要求

• Python 3.13+
• UV（Python 包管理器）
• MeiliSearch 在 7700 端口运行（可选 - 见下文替代方案）

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 网络界面进行测试

若要使用 ADK 的网络界面测试系统，请执行以下操作：

# 1. 首先，安装依赖
cd vitra_ai
uv sync

# 2. 激活虚拟环境
source .venv/bin/activate

# 3. 返回项目根目录
cd ..

# 4. 运行 ADK 网络界面（需在项目文件夹的上一级目录运行）
adk web

⚠️ 重要提示

adk web 命令必须在项目文件夹的父目录中运行，而不是在项目文件夹内部。

💻 使用示例

基础用法

# 此项目主要通过命令行运行，以下是运行主系统的基础命令
cd vitra_ai
uv run agent.py

高级用法

# 若要使用 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

🚀 快速开始

本系统模拟了一个具备健康咨询功能的电子商务场景，不同专业智能体协同工作以服务客户。系统架构如下：

根智能体（主协调器）
├── 购物助手（产品专家）
│   └── 帮助客户（MCP 接口）
├── 销售智能体（销售专家）
│   ├── 创建订单（订单创建）
│   ├── 计费（账单处理）
│   └── 管理库存（库存管理）
└── 健康助手（健康顾问）
    ├── 营养专家（营养/皮肤专家）
    └── 健身专家（运动专家）

🔧 技术细节

系统架构概述

系统模拟了一个具备健康咨询功能的电子商务场景，不同专业智能体协同工作以服务客户。

组件实现

1. Vitra AI（主系统）

• 根智能体：主协调器，将任务分配给子智能体。
• 专业提示：为每个智能体提供特定指令。
• 多种模型：通过 LiteLLM 使用 Gemini、Claude 和 Llama 模型。

2. 搜索 MCP 服务器（工具服务器）

• 产品搜索：与搜索系统（MeiliSearch）的接口。
• 付款计划：模拟融资选项。
• 日志记录：记录所有操作以进行审计。

3. 专业子智能体

• 购物助手：负责产品推荐和搜索，使用 Claude 3.5 Sonnet 模型，通过 MCP 服务器进行查询。
• 销售智能体：负责完整的订单处理，包含创建订单、计费和管理库存等子智能体，使用自定义的电子商务功能。
• 健康助手：提供健康和保健咨询，包含营养专家和健身专家子智能体，使用 Gemini 2.5 Flash 和 Llama 3.1 8B 模型。

系统运行流程

系统通过不同智能体之间的协作完成任务，根智能体作为主协调器，根据客户需求将任务分配给相应的子智能体。子智能体通过 MCP 协议与外部工具和服务进行交互，实现产品搜索、订单处理、健康咨询等功能。

数据存储与管理

系统支持多种数据存储方式，包括 MeiliSearch、本地 JSON 文件、外部 REST API、SQLite 数据库和 Elasticsearch。用户可以根据需求选择合适的数据存储方式。

模型配置与使用

系统使用多种语言模型，如 Gemini、Claude 和 Llama，通过 LiteLLM 进行管理。用户需要配置相应的 API 密钥才能使用这些模型。

错误处理与日志记录

系统实现了基本的错误处理和日志记录功能，通过日志记录所有操作以进行审计。但错误处理功能较为简单，仅适用于演示目的。

性能与优化

系统未针对生产环境进行优化，主要用于教育和演示目的。在实际应用中，需要对系统进行性能优化和安全加固。

📚 详细文档

自定义 MCP 服务器

MeiliSearch 替代方案

search_mcp_server/help_customer.py 文件可轻松修改以使用其他数据源：

1. 本地 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}

2. 外部 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()

3. 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}

4. 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                    # 本文件

演示概念

1. 智能体层次结构

• 如何将智能体组织成层次结构
• 专业智能体之间的任务分配
• 多个子系统的协调

2. MCP 协议

• 外部工具的实现
• 智能体与服务之间的通信
• 操作的日志记录和审计

3. 多模型集成

• 同时使用不同的大语言模型
• 根据任务类型进行专业化处理
• 按智能体配置参数

4. 自定义工具

• 创建特定领域的工具
• 将数据持久化到文件中
• 模拟外部系统

实验与学习

修改建议

1. 添加新智能体：创建一个客户服务智能体。
2. 实现新工具：添加与真实 API 的集成。
3. 尝试模型：测试其他大语言模型或调整参数。
4. 改进日志记录：使用 JSON 实现结构化日志记录。
5. 添加验证：实现智能体之间的数据验证。

注意事项

• 硬编码路径：路径是固定的，请根据你的环境进行调整。
• 身份验证：为教学目的，令牌是公开的。
• 错误处理：实现较为简单，仅适用于演示。
• 性能：未针对生产环境进行优化。

额外资源

• Google ADK 文档
• MCP 协议规范
• LiteLLM 文档

🤝 贡献

这是一个教育项目！欢迎你：

• 进行复刻并进行实验
• 提出教学改进建议
• 添加使用示例
• 报告错误或不一致之处

💡 使用建议

本项目是一个学习工具，你可以利用它来理解概念、尝试修改并根据自己的教育需求进行调整！🚀