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 文檔

🤝 貢獻

這是一個教育項目！歡迎你：

• 進行復刻並進行實驗
• 提出教學改進建議
• 添加使用示例
• 報告錯誤或不一致之處

💡 使用建議

本項目是一個學習工具，你可以利用它來理解概念、嘗試修改並根據自己的教育需求進行調整！🚀