使用说明

集成FastMCP的多Agent RAG系统

A. 多智能体人工智能系统 以...构建 快速API 使用以下命令回答常见问题 检索增强生成（RAG），提供 天气信息，并管理任务通过一个 FastMCP Todo服务器。系统使用 LangGraph 对于代理编排， 色度数据库 用于向量存储，并通过解耦完全对接溪流前端。

系统架构

┌─────────────────────────────────────────────────────────────────────┐
│                        STREAMLIT FRONTEND                          │
│                    (Decoupled Microservice)                         │
│            Chat UI │ Weather UI │ Todo Manager UI                   │
└───────────────────────────────┬─────────────────────────────────────┘
                                │  HTTP/REST (JSON)
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         FASTAPI BACKEND                            │
│                                                                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌──────────────────┐  │
│  │ Auth API │  │ Chat API │  │Weather API│  │   Todo API       │  │
│  │ /auth/*  │  │ /chat    │  │ /weather  │  │   /todos/*       │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  └────────┬─────────┘  │
│       │              │              │                  │            │
│       │         ┌────▼──────────────┴──────────────────┘            │
│       │         │                                                   │
│  JWT Auth   ┌───▼────────────────────────────────────┐             │
│  Middleware │    PARENT AGENT (LangGraph Orchestrator) │             │
│             │                                         │             │
│             │   ┌──────────┐  ┌─────────────────────┐│             │
│             │   │Intent    │  │  Conditional Router  ││             │
│             │   │Detection │──▶  faq → RAG Agent     ││             │
│             │   │(LLM)    │  │  weather → Tool Agent ││             │
│             │   └──────────┘  │  todo → Tool Agent   ││             │
│             │                 └─────────────────────┘│             │
│             └─────┬────────────────────┬─────────────┘             │
│                   │                    │                            │
│          ┌────────▼──────┐    ┌────────▼───────────┐               │
│          │   RAG AGENT   │    │    TOOL AGENT      │               │
│          │               │    │                    │               │
│          │ 1. Semantic   │    │  ┌──────────────┐  │               │
│          │    Search     │    │  │ Weather Tool │  │               │
│          │ 2. Context    │    │  │ (Open-Meteo) │  │               │
│          │    Building   │    │  └──────────────┘  │               │
│          │ 3. LLM Answer │    │  ┌──────────────┐  │               │
│          │    Generation │    │  │ Todo Tools   │  │               │
│          └───────┬───────┘    │  │ (FastMCP)    │  │               │
│                  │            │  └──────┬───────┘  │               │
│          ┌───────▼───────┐    └─────────┼──────────┘               │
│          │   ChromaDB    │              │                           │
│          │ Vector Store  │    ┌─────────▼──────────┐               │
│          │ (FAQ Data)    │    │  FastMCP Todo      │               │
│          └───────────────┘    │  Server (PostgreSQL)│              │
│                               └─────────┬──────────┘               │
│                                         │                          │
│                               ┌─────────▼──────────┐               │
│                               │   PostgreSQL DB    │               │
│                               │  (Users + Todos)   │               │
│                               └────────────────────┘               │
└─────────────────────────────────────────────────────────────────────┘

系统设计

微服务架构

该应用程序遵循 微服务架构 具有两个可独立部署的服务：

服务	技术	港口	责任
后端	FastAPI	8000	API服务器、代理编排、RAG、MCP
前端	Streamlit	8501	用户界面，仅通过REST API进行通信
数据库	PostgreSQL	5432	用户和待办事项的持久存储

前端是 松耦合 --它只知道后端的URL，并且只通过HTTP REST调用进行通信。没有共享代码，没有共享状态。

多智能体系统（LangGraph）

代理系统由以下部分构建 LangGraph，实现有向状态图：

                    ┌─────────────────┐
                    │  detect_intent  │  (Entry Point)
                    │  (LLM-based)    │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ Conditional     │
                    │ Router          │
                    └──┬──────┬───┬───┘
                       │      │   │
            "faq"      │      │   │  "unknown"
                       │      │   │
              ┌────────▼┐  ┌──▼───▼─────┐  ┌───────────┐
              │rag_node │  │ tool_node  │  │unknown_node│
              │         │  │            │  │            │
              └────┬────┘  └─────┬──────┘  └─────┬──────┘
                   │             │               │
                   └─────────────┴───────────────┘
                                 │
                               [END]

父代理（编排器）：接收查询，使用LLM对意图进行分类(faq, weather, todo, unknown)，然后路由到适当的专家。
RAG代理：在ChromaDB上执行语义搜索，从前k个结果构建上下文，并使用LLM生成基础答案。
工具代理：根据分类意图调度天气API或FastMCP todo工具。

RAG管道

CSV Data → LangChain Documents → OpenAI Embeddings → ChromaDB Vector Store
                                                            │
User Query → Embedding → Similarity Search (top-4) → Context Building → LLM → Answer

数据源：常见问题CSV文件（BigRock的386对问答）
嵌入：OpenAI text-embedding-3-small
矢量存储：ChromaDB（内存+可选持久化）
LLM：GPT-4.1迷你版（可配置）
后备方案：如果不存在相关上下文，则返回“我找不到答案”

FastMCP集成

Todo服务作为 FastMCP 3.x服务器 工具通过MCP协议公开。Todos坚持 PostgreSQL 通过SQLAlchemy：

create_task --创建新的待办事项
list_tasks --列出所有任务（带筛选器）
get_task --按ID检索任务
update_task --修改任务标题/描述/状态
delete_task --删除任务

后端使用 FastMCP客户端 使用内存内传输（同一进程内的MCP调用没有网络跃点），同时还公开REST API端点以进行直接访问。该代理还支持 基于关键字的任务解析 --用户可以按名称而不是ID引用任务。

JWT身份验证

所有API端点（除 /auth/* 和健康检查）受到保护 JWT承载令牌身份验证.

流量：

POST /auth/register 或 POST /auth/login → 返回JWT
包括 Authorization: Bearer <token> 在后续请求中
令牌在每个受保护的端点上都经过验证

数据流

User Input → Streamlit → POST /chat → JWT Validation → Orchestrator
  → Intent Detection (LLM) → Route to Agent → Execute → Return Response
  → Streamlit renders answer

技术栈

组件	技术
后端API	FastAPI，Uvicorn
代理框架	LangGraph、LangChain
LLM	OpenAI GPT-4.1迷你版
嵌入	OpenAI文本嵌入3-small
矢量数据库	ChromaDB
数据库	PostgreSQL、SQLAlchemy、Alembic
MCP服务器	FastMCP 3.x
天气API	Open-Meteo（免费，无密钥）
身份验证	JWT（python jose）
前端	流式传输
HTTP客户端	httpx（异步），请求
测试	Pytest
容器化	Docker，Docker Compose

项目结构

Multi_Agent_RAG_With_FastMCP/
├── docker-compose.yml          # Orchestrates backend + frontend containers
├── README.md
├── data/
│   ├── faqs.csv                # FAQ dataset (question/answer pairs)
│   └── faqs 3.xlsx             # Original Excel source
│
├── backend/
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── requirements.txt
│   ├── pytest.ini
│   ├── alembic.ini             # Alembic config (URL overridden by env.py)
│   ├── .env                    # Secret variables (gitignored)
│   ├── .env.example            # Template for env vars
│   ├── alembic/                # Database migrations
│   │   ├── env.py              # Migration environment (reads DATABASE_URL)
│   │   └── versions/           # Migration scripts
│   ├── app/
│   │   ├── main.py             # FastAPI entry point, CORS, lifespan
│   │   ├── config.py           # Settings from env vars
│   │   ├── database.py         # SQLAlchemy engine, session, Base
│   │   │
│   │   ├── models/             # ORM models
│   │   │   ├── __init__.py     # Exports User, Todo
│   │   │   ├── user.py         # User model
│   │   │   └── todo.py         # Todo model
│   │   │
│   │   ├── auth/               # Authentication module
│   │   │   ├── routes.py       # POST /auth/login, /auth/register
│   │   │   ├── controllers.py  # Login/register logic
│   │   │   └── jwt_handler.py  # JWT create/verify, FastAPI dependency
│   │   │
│   │   ├── chat/               # Chat module
│   │   │   ├── routes.py       # POST /chat
│   │   │   └── controllers.py  # Delegates to orchestrator
│   │   │
│   │   ├── weather/            # Weather module
│   │   │   ├── routes.py       # GET /weather
│   │   │   └── controllers.py  # Delegates to tool agent
│   │   │
│   │   ├── todo/               # Todo module
│   │   │   ├── routes.py       # CRUD /todos/*
│   │   │   └── controllers.py  # Proxies to FastMCP client
│   │   │
│   │   ├── agents/             # Multi-agent system
│   │   │   ├── orchestrator.py # Parent agent (LangGraph state graph)
│   │   │   ├── rag_agent.py    # RAG pipeline agent
│   │   │   └── tool_agent.py   # Weather + Todo agent
│   │   │
│   │   ├── rag/                # RAG infrastructure
│   │   │   ├── loader.py       # CSV → LangChain Documents
│   │   │   └── vectorstore.py  # ChromaDB build/query
│   │   │
│   │   └── mcp/                # FastMCP integration
│   │       ├── todo_server.py  # FastMCP server with CRUD tools (PostgreSQL)
│   │       └── client.py       # FastMCP client (in-memory transport)
│   │
│   └── tests/
│       ├── conftest.py         # Shared fixtures
│       ├── test_auth.py        # Auth API tests
│       ├── test_weather.py     # Weather API tests
│       ├── test_todos.py       # Todo API tests
│       └── test_chat.py        # Chat API tests
│
└── frontend/
    ├── Dockerfile
    ├── .dockerignore
    ├── requirements.txt
    ├── .env
    ├── .env.example
    ├── config.py               # Frontend configuration
    ├── api_client.py           # HTTP client for backend API
    ├── app.py                  # Streamlit application
    └── .streamlit/
        └── config.toml         # Streamlit server config

安装说明

先决条件

Python 3.12+
OpenAI API密钥
PostgreSQL 16+（或使用包含它的Docker）
（可选）Docker和Docker Compose

本地开发（无Docker）

1.后端设置

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your OPENAI_API_KEY and DATABASE_URL

# Run database migrations
alembic upgrade head

# Run the backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API文件可在 http://localhost:8000/docs （Swagger用户界面）。

2.前端设置

cd frontend

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env

# Run the frontend
streamlit run app.py --server.port 8501

前端可在 http://localhost:8501.

3.默认凭据

用户名	密码
管理员	admin123

您还可以通过UI或API注册新帐户。

Docker设置

快速开始

# From the project root
cp backend/.env.example backend/.env
# Edit backend/.env with your OPENAI_API_KEY

docker-compose up --build

这将启动三项服务：

PostgreSQL 在本地主机：5432（通过Docker卷持久化）
后端在http://localhost:8000（API+Swagger UI位于 /docs)
前端在http://localhost:8501

后端容器在启动时自动运行Alembic迁移。

Docker网络

这 docker-compose.yml 覆盖某些 .env 容器网络的价值观：

DATABASE_URL → 指向 db:5432 而不是 localhost:5432
BACKEND_URL → 前端使用 http://backend:8000 内部地
FAQ_CSV_PATH → /data/faqs.csv （安装自 ./data)

你的 .env 保持 localhost 因此，本地开发（没有Docker）仍然有效。

停止服务

docker-compose down
# To also remove volumes (clears DB and ChromaDB data):
docker-compose down -v

API 文档

后端运行后，交互式API文档位于：

Swagger 用户界面: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

端点摘要

方法	端点	身份验证	标签	描述
职位	`/auth/login`	否	身份验证	登录并获取JWT令牌
职位	`/auth/register`	否	身份验证	注册新用户并获取JWT
职位	`/chat`	是	聊天	向编排器代理发送查询
得到	`/weather`	是	天气	获取城市的当前天气
职位	`/todos`	是	待办事项	创建新任务
得到	`/todos`	是	待办事项	列出所有任务
得到	`/todos/{task_id}`	是	待办事项	获取特定任务
PUT	`/todos/{task_id}`	是	待办事项	更新任务
删除	`/todos/{task_id}`	是	待办事项	删除任务
得到	`/`	否	健康	健康检查
得到	`/health`	否	健康状况	详细的健康检查

示例用法

# 1. Login (uses form-encoded data for OAuth2 compatibility)
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -d 'username=admin&password=admin123' \
  | jq -r '.access_token')

# 2. Chat (FAQ query)
curl -X POST http://localhost:8000/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "What domains are available from BigRock?"}'

# 3. Weather
curl -X GET "http://localhost:8000/weather?city=London" \
  -H "Authorization: Bearer $TOKEN"

# 4. Create a todo
curl -X POST http://localhost:8000/todos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "description": "Milk, eggs, bread"}'

测试

运行快乐路径测试套件：

cd backend
pytest tests/ -v

测试套件包括：

认证API：注册、登录、重复处理、JWT验证
天气API：默认城市、自定义城市、身份验证强制
所有API：创建、列出、更新、删除任务、执行身份验证
聊天API：常见问题解答/天气/待办事项查询（模拟编排器进行隔离）

特工深潜

父代理（编排器）

文件: backend/app/agents/orchestrator.py

使用LangGraph StateGraph 具有键入状态(AgentState).LLM将用户的意图分为以下几类： faq, weather, todo，或 unknown基于分类，条件边路由到适当的专家节点。

RAG代理

文件: backend/app/agents/rag_agent.py

接收原始查询
执行 similarity_search ChromaDB（前4名结果）
将检索到的文档格式化为上下文块
向GPT-4.1 Mini发送上下文+查询，并附上严格的接地说明
返回生成的答案（或回退消息）

工具代理

文件: backend/app/agents/tool_agent.py

发送至：

天气工具：呼叫 开放气象API （免费，不需要API密钥）。使用两步流程：对城市名称进行地理编码→ 获取当前天气。
Todo工具：呼叫 FastMCP Todo服务器 通过内存中的MCP客户端。支持基于关键字的任务解析——用户可以通过名称/描述而不是ID来引用任务。

配置参考

所有机密和配置都存储在 backend/.env:

变量	描述	默认值
`OPENAI_API_KEY`	OpenAI API密钥	（必需）
`OPENAI_MODEL`	LLM型号名称	`gpt-4.1-mini`
`JWT_SECRET_KEY`	JWT签名密码	（必填）
`JWT_ALGORITHM`	JWT算法	`HS256`
`JWT_ACCESS_TOKEN_EXPIRE_MINUTES`	令牌到期时间（分钟）	`30`
`DATABASE_URL`	PostgreSQL连接字符串	（必填）
`WEATHER_DEFAULT_CITY`	天气查询的默认城市	`London`
`CHROMA_PERSIST_DIR`	ChromaDB数据目录	`./chroma_db`
`CHROMA_COLLECTION_NAME`	ChromaDB集合名称	`faq_collection`
`FAQ_CSV_PATH`	常见问题CSV文件的路径	`../data/faqs.csv`

许可证

看许可证了解详情。