MCP agent dev kit

🏦 MCP和RAG的银行人工智能代理

使用Google ADK构建的生产就绪银行客户服务人工智能代理，具有以下特点：

• MCP（模型上下文协议） 用于安全的交易数据访问
• RAG（检索增强生成） 银行产品信息
• 本地大语言模型 通过奥利玛提供支持（Qwen 3 VL 235B）
• RESTful API 使用JWT身份验证

______________________________________________________________________

📋 目录

1. 特性
2. 建筑
3. 先决条件
4. 安装
5. 数据库设置
6. 运行代理
7. API使用
8. 测试
9. 项目结构
10. 故障排除

______________________________________________________________________

✨ 特性

核心能力

• ✅ 客户信息检索 -按ID获取客户详细信息
• ✅ 交易记录 -查看最近N笔交易
• ✅ 账户余额 -实时余额查询
• ✅ 产品搜索 -基于RAG的银行产品推荐
• ✅ 安全认证 -MCP API密钥验证
• ✅ RESTful API -JWT身份验证端点

技术特性

• 🔒 安全数据访问 -只读MCP服务器
• 🤖 本地大语言模型 -注重隐私（Ollama Qwen 3 VL）
• 📊 真实银行数据 -来自全面的CSV数据集
• 🔍 向量搜索 -ChromaDB用于产品知识
• 🚀 快速响应 -优化数据库查询

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────┐
│                    User Interface                        │
│            (ADK Web UI / REST API)                       │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────┐
│              Banking AI Agent (ADK)                       │
│         Model: Qwen 3 VL 235B (Ollama)                   │
└─────┬────────────────────────────────────────────────────┘
      │
      ├──────────────────────┬──────────────────────────────┐
      │                      │                              │
      ▼                      ▼                              ▼
┌────────────┐    ┌─────────────────┐         ┌────────────────┐
│ MCP Server │    │   RAG System    │         │   REST API     │
│ (stdio)    │    │   (ChromaDB)    │         │   (FastAPI)    │
├────────────┤    ├─────────────────┤         ├────────────────┤
│ - Customer │    │ - Products      │         │ - /auth/login  │
│ - Txns     │    │ - Embeddings    │         │ - /agent/query │
│ - Balance  │    │ - Vector Search │         │ - JWT Auth     │
└─────┬──────┘    └─────────────────┘         └────────────────┘
      │
      ▼
┌──────────────────────────────────────────────────────────┐
│              SQLite Database                              │
│   ├── customers (20 records)                             │
│   └── transactions (20 records)                          │
└──────────────────────────────────────────────────────────┘

______________________________________________________________________

📦 先决条件

所需软件

• python：3.10或更高
• 紫外线：Python包安装程序(pip install uv)
• 奥拉玛：本地法学硕士(下载)
• SQLite：预装Python

Ollama模型

下载Qwen 3 VL型号：

ollama pull qwen3-vl:235b-cloud

______________________________________________________________________

🚀 安装

1.克隆或创建项目结构

# Create project directory
mkdir banking_ai_agent
cd banking_ai_agent

# Initialize uv project
uv init

2.安装依赖项

# Install all required packages
uv add google-adk litellm ollama python-dotenv pandas sentence-transformers chromadb fastapi uvicorn python-jose

3.激活虚拟环境

窗户：

.venv\Scripts\activate

macOS/Linux：

source .venv/bin/activate

4.创建ADK应用程序结构

adk create app

选择选项 2 （不要使用Gemini-使用本地LLM）

5.设置项目结构

创建以下目录结构：

banking_ai_agent/
├── .venv/
├── app/
│   ├── agent.py
│   ├── __init__.py
│   └── .env
├── src/
│   ├── api/
│   │   ├── main.py
│   │   ├── models.py
│   │   └── auth.py
│   ├── mcp/
│   │   ├── server.py
│   │   ├── create_db.py
│   │   └── db/
│   └── rag/
│       ├── extract_products.py
│       ├── create_vector_db.py
│       ├── product_knowledge.py
│       └── products/
├── data/
│   └── Comprehensive_Banking_Database.csv
├── .env
├── pyproject.toml
└── README.md

6.环境配置

创建 .env 项目根目录中的文件：

MCP_API_KEY=banking-dev-token-2026
OLLAMA_BASE_URL=http://localhost:11434

复制到 app/.env:

cp .env app/.env

______________________________________________________________________

💾 数据库设置

步骤1：准备数据

放置您的 Comprehensive_Banking_Database.csv 在 data/ 文件夹。

CSV格式：

Customer ID,First Name,Last Name,Age,Gender,Address,City,...
1,Joshua,Hall,45,Male,Address_1,Fort Worth,...
2,Mark,Taylor,47,Female,Address_2,Louisville,...
...

步骤2：创建数据库

python src/mcp/create_db.py

预期产量：

Loading data from data/Comprehensive_Banking_Database.csv...
Loaded 20 rows
Columns: ['Customer ID', 'First Name', 'Last Name', ...]

✅ Database created successfully!
   Total customers: 20
   Total transactions: 20
   Location: src/mcp/db/banking.db

Sample customers:
   - ID: 1, Name: Joshua Hall
   - ID: 2, Name: Mark Taylor
   - ID: 3, Name: Joseph Flores

步骤3：验证数据库（可选）

sqlite3 src/mcp/db/banking.db

# Run queries
SELECT * FROM customers LIMIT 3;
SELECT * FROM transactions WHERE customer_id = 1;
.exit

______________________________________________________________________

🔍 RAG设置（产品知识库）

步骤1：从数据库中提取产品

python src/rag/extract_products.py

输出：

✅ Extracted 8 products
   Account types: 2
   Loan types: 3
   Card types: 3

📁 Saved to: src/rag/products/products.json

步骤2：创建矢量数据库

python src/rag/create_vector_db.py

输出：

✅ Created vector database with 8 products
📁 Location: src/rag/products/chroma_db

______________________________________________________________________

🎯 运行代理

方法1:ADK Web界面（推荐）

第一步：启动Olama

# Terminal 1
ollama serve

步骤2：运行ADK Web服务器

# Terminal 2
adk web

输出：

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

步骤3：访问Web UI

打开浏览器： http://127.0.0.1:8000

______________________________________________________________________

方法2：命令行

adk run app

互动聊天：

Running agent app, type exit to exit.
[user]: Show me last transactions for customer 1
[agent]: Hello Joshua Hall! Here are your last 5 transactions:
         1. 12/7/2023 - Withdrawal: $1,457.61
         2. ...

______________________________________________________________________

🌐 API使用

启动API服务器

python src/api/main.py

服务器运行于： http://localhost:8080

API终点

1.身份验证

POST /auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

答复：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

2.查询代理

POST /agent/query
Authorization: Bearer 
Content-Type: application/json

{
  "query": "What's my balance?",
  "customer_id": 1
}

答复：

{
  "status": "success",
  "response": "Your current balance is $1,313.38",
  "data": {
    "customer_id": 1
  }
}

______________________________________________________________________

🧪 测试

测试场景

1.客户信息

Query: "Show me information for customer ID 1"
Expected: Joshua Hall, Age 45, Balance $1,313.38

2.交易历史

Query: "Show last 5 transactions for customer 1"
Expected: List of recent transactions with dates, types, amounts

3.账户余额

Query: "What's the balance for customer 2?"
Expected: Mark Taylor's balance $5,988.46

4.产品搜索

Query: "Tell me about savings accounts"
Expected: Information about savings account features

5.组合查询

Query: "Customer ID 1 first name Joshua show last transaction"
Expected: Extracts ID=1, shows recent transaction

______________________________________________________________________

📁 项目结构

banking_ai_agent/
├── .venv/                          # Virtual environment
├── app/
│   ├── agent.py                    # Main ADK agent
│   ├── __init__.py
│   └── .env                        # Agent environment variables
├── src/
│   ├── api/
│   │   ├── main.py                 # FastAPI application
│   │   ├── models.py               # Pydantic models
│   │   └── auth.py                 # JWT authentication
│   ├── mcp/
│   │   ├── server.py               # MCP stdio server
│   │   ├── create_db.py            # Database initialization
│   │   └── db/
│   │       └── banking.db          # SQLite database
│   └── rag/
│       ├── extract_products.py     # Extract products from DB
│       ├── create_vector_db.py     # Create ChromaDB embeddings
│       ├── product_knowledge.py    # RAG query interface
│       └── products/
│           ├── products.json       # Product data
│           └── chroma_db/          # Vector database
├── data/
│   └── Comprehensive_Banking_Database.csv  # Source data
├── .env                            # Root environment variables
├── pyproject.toml                  # Project dependencies
└── README.md                       # This file

______________________________________________________________________

🛠️ 故障排除

问题1:MCP服务器连接错误

错误：

Cleaning up disconnected session: stdio_session

解决方案： 确保MCP服务器路径正确 app/agent.py:

server_params=StdioServerParameters(
    command="python",
    args=["src/mcp/server.py"],  # ✅ Relative to project root
    ...
)

______________________________________________________________________

问题2：找不到数据库

错误：

Database not found at src/mcp/db/banking.db

解决方案：

python src/mcp/create_db.py

______________________________________________________________________

问题3：找不到Olama模型

错误：

LiteLLM completion() model= qwen3-vl:235b-cloud; provider = ollama_chat
[Error] Model not found

解决方案：

ollama pull qwen3-vl:235b-cloud
ollama list  # Verify installation

______________________________________________________________________

问题4:RAG搜索不可用

错误：

Product search unavailable. Run: python src/rag/create_vector_db.py

解决方案：

python src/rag/extract_products.py
python src/rag/create_vector_db.py

______________________________________________________________________

问题5：反应迟缓

原因： Qwen 3 VL 235B是一个大型型号

解决：

1. 使用较小的型号：

   ollama pull llama3.2:3b

更新 app/agent.py:

   model=LiteLlm(model="ollama_chat/llama3.2:3b")

1. 使用云托管模型：

   model=LiteLlm(model="groq/llama-3.3-70b-versatile")

______________________________________________________________________

📊 示例数据

包含的CSV包含20名客户，他们拥有全面的银行数据：

______________________________________________________________________

🔐 安全说明

1. API密钥：更改生产中的默认API密钥
2. JWT秘密：更新 SECRET_KEY 在 src/api/auth.py
3. 数据库：在生产中使用适当的数据库身份验证
4. 跨域资源共享：限制生产来源(src/api/main.py)

______________________________________________________________________

📝 许可证

这个项目是为了教育目的。银行数据是合成的。

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建特征分支
3. 提交更改
4. 推送到分支
5. 打开拉取请求

______________________________________________________________________

📮 联系

如有疑问或问题，请打开GitHub issue。

______________________________________________________________________

🙏 致谢

• 谷歌ADK -代理开发工具包
• 奥拉玛 -本地LLM运行时
• 色度数据库 -矢量数据库
• 快速API -现代web框架
• 文学硕士 -通用LLM接口

______________________________________________________________________

建于❤️ 使用谷歌ADK、MCP和RAG