Content
# Tool List
> Based on LangChain ReAct Agent + RAG + Streamlit
---
# Getting Started
Please make sure to install the required environment configurations, and replace the `gaodekey` in the `config/agent.yml` file with your actual Gaode API key (or use a more implicit method).
## 📖 Project Overview
**Zhisaotong Robot Intelligent Customer Service** is an AI-powered intelligent agent application designed for robot vacuum cleaner users. The system uses Streamlit to build a lightweight front-end web page, and the back-end is built on LangChain's ReAct (Reasoning + Acting) Agent, integrating the following core capabilities:
- **RAG Enhanced Retrieval**: Store product manuals, FAQs, and maintenance guides in a vectorized database, and retrieve relevant information to ensure accurate and reliable answers.
- **Gaode MCP Service**: Call Gaode Map API to retrieve user location and weather information in real-time.
- **Summary Report Mode**: Dynamically switch system prompts based on specific intents, and automatically generate usage reports in Markdown format.
- **Multi-Round Tool Calls**: The Agent can plan and call equipped tools in multiple rounds until user needs are met.
- **Streaming Response**: The final result is presented in a streaming manner on the web page, improving interactive experience.
- **Comprehensive Logging and History**: Equipped with structured logging (file + console) and conversation history.
---
## ✨ Core Features
| Feature | Description |
|------|------|
| **LLM** | Alibaba Cloud Tongyi Qianwen `qwen3-max` (via `ChatTongyi`) |
| **Embedding** | Alibaba Cloud DashScope `text-embedding-v4` |
| **Vector Database** | Chroma (local persistence) |
| **Agent Framework** | LangChain ReAct Agent + LangGraph |
| **Front-end** | Streamlit Web interface, supporting conversation history |
| **External Services** | Gaode Map REST API (weather, IP location) |
| **Dynamic Prompts** | Middleware automatically switches system prompts based on context signals |
| **Deduplication Mechanism** | MD5 hash tracking for processed documents to avoid duplicates |
---
## 🏗 System Architecture
```
┌──────────────────────────────────────────────┐
│ Streamlit Front-end (app.py) │
│ - Conversation History - Streaming Display - Session Management │
└──────────────────────┬───────────────────────┘
│
┌──────────────────────▼───────────────────────┐
│ ReAct Agent (agent/react_agent.py) │
│ ┌─────────────────────────────────────────┐ │
│ │ Middleware Layer (middleware.py) │ │
│ │ ├─ monitor_tool Tool Call Monitoring and Logging │ │
│ │ ├─ log_before_model Model Call Logging │ │
│ │ └─ report_prompt_switch Dynamic Prompt Switching │ │
│ └─────────────────────────────────────────┘ │
│ Toolset: rag_summarize / get_weather / │
│ get_user_location / get_user_id / │
│ get_current_month / fetch_external_data│
│ fill_context_for_report │
└──┬──────────────┬───────────────┬────────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌─────────────┐ ┌────────────────┐
│ RAG Service │ │ Gaode API │ │ External CSV Data │
│(rag/) │ │ Weather / Location │ │ data/external/ │
└────┬─────┘ └─────────────┘ └────────────────┘
│
┌────▼─────────────────────────┐
│ Chroma Vector Database (chroma_db/)│
│ Embedding: text-embedding-v4 │
│ Knowledge Base Documents (data/) │
│ ├─ PDF / TXT Documents │
│ └─ chunk_size=200, k=3 │
└──────────────────────────────┘
```
---
## 📂 Directory Structure
```
zhisaotong-Agent/
├── app.py # Streamlit Front-end Entry
├── agent/
│ ├── react_agent.py # ReAct Agent Core Logic
│ └── tools/
│ ├── agent_tools.py # Tool Function Definitions
│ └── middleware.py # Agent Middleware
├── rag/
│ ├── rag_service.py # RAG Retrieval Summary Service
│ └── vector_store.py # Chroma Vector Database Management
├── model/
│ └── factory.py # Model Factory (LLM + Embedding)
├── utils/
│ ├── config_handler.py # YAML Configuration Loader
│ ├── logger_handler.py # Logging Tool
│ ├── prompt_loader.py # Prompt Loader
│ ├── file_handler.py # Document Loader (PDF/TXT)
│ └── path_tool.py # Path Tool
├── config/
│ ├── agent.yml # Agent Configuration (Gaode API Key, etc.)
│ ├── rag.yml # Model Name Configuration
│ ├── chroma.yml # Vector Database Configuration
│ └── prompts.yml # Prompt File Paths
├── prompts/
│ ├── main_prompt.txt # Main ReAct Prompt
│ ├── rag_summarize.txt # RAG Summary Prompt
│ └── report_prompt.txt # Report Generation Prompt
├── data/
│ ├── robot_vacuum_cleaner_100_questions.pdf
│ ├── robot_vacuum_cleaner_100_questions_2.txt
│ ├── robot_vacuum_cleaner_and_mop_100_questions.txt
│ ├── troubleshooting.txt
│ ├── maintenance_and保养.txt
│ ├── purchasing_guide.txt
│ └── external/
│ └── records.csv # User Usage Records (External Data)
├── chroma_db/ # Chroma Persistence Directory (auto-generated)
├── logs/ # Log File Directory (auto-generated)
└── md5.text # Document MD5 Deduplication Record
```
---
## 📦 Environment Dependencies
### Python Version
Recommended **Python 3.10+** (code uses type annotations like `tuple[str, str]`).
### Main Dependencies
| Package | Purpose |
|------|------|
| `streamlit` | Front-end Web Framework |
| `langchain` | Agent / Chain / Tool Framework |
| `langchain-core` | LangChain Core Abstraction |
| `langchain-community` | Tongyi Qianwen, DashScope Embedding, etc. integrations |
| `langgraph` | Graph-based Agent Execution Engine (with `Runtime`) |
| `langchain-chroma` | LangChain and Chroma Vector Database Integration |
| `chromadb` | Chroma Vector Database |
| `dashscope` | Alibaba Cloud DashScope SDK (Embedding / LLM) |
| `pypdf` / `pypdf2` | PDF Document Loader |
| `pyyaml` | YAML Configuration File Parser |
### One-Click Deployment (Recommended)
```bash
python -m pip install -r requirements.txt
```
---
## ⚙️ Configuration Instructions
### 1. Alibaba Cloud API Key
This project uses Alibaba Cloud Tongyi Qianwen and DashScope Embedding, requiring configuration of system environment variables:
```bash
OPENAI_API_KEY="your_open_api_key"
```
> Obtain API Key from [Alibaba Cloud Bailian Platform](https://bailian.console.aliyun.com/).
### 2. Gaode Map API Key
Edit `config/agent.yml` and replace `gaodekey` with your Gaode Map Web Service API Key:
```yaml
# config/agent.yml
external_data_path: data/external/records.csv
gaodekey: your_gaode_key! # ← Replace here
gaode_base_url: https://restapi.amap.com
gaode_timeout: 5
```
> Apply for Web Service-type API Key from [Gaode Open Platform](https://console.amap.com/).
### 3. Model Configuration
Edit `config/rag.yml` to adjust used models:
```yaml
# config/rag.yml
chat_model_name: qwen3-max # Dialogue Model
embedding_model_name: text-embedding-v4 # Vectorization Model
```
### 4. Vector Database Configuration
Edit `config/chroma.yml` to adjust RAG retrieval parameters:
```yaml
# config/chroma.yml
collection_name: agent
persist_directory: chroma_db
k: 3 # Number of most relevant documents returned
data_path: data
md5_hex_store: md5.text
allow_knowledge_file_type: ["txt", "pdf"]
chunk_size: 200 # Text chunk size
chunk_overlap: 20 # Chunk overlap length
```
---
## 🚀 Quick Start
### 1. Clone Project
```bash
git clone https://github.com/bamboo-moon/zhisaotong-Agent.git
cd zhisaotong-Agent
```
### 2. Install Dependencies
```bash
python -m pip install -r requirements.txt
```
### 3. Configure API Key
```bash
# Set Alibaba Cloud DashScope API Key
export DASHSCOPE_API_KEY="your_dashscope_api_key"
# Configure Gaode Map API Key in config/agent.yml
```
### 4. Start Application
```bash
streamlit run app.py
```
The browser will automatically open `http://localhost:8501`, and you can start chatting with the Zhisaotong Robot Intelligent Customer Service.
---
## 💬 Usage
After starting, users can perform the following operations in the web chat interface:
### Product Consultation
Ask questions about robot vacuum cleaners, maintenance, troubleshooting, etc. The Agent will prioritize retrieving relevant information from the knowledge base to answer:
```
User: How often should I replace the filter of my robot vacuum cleaner?
User: What is the difference between a robot vacuum cleaner and a robot vacuum-mop?
User: What should I do if my robot vacuum cleaner's suction power is weak?
```
### Weather and Location Query
The Agent can call Gaode API to retrieve real-time information:
```
User: What is the weather like in my city today?
```
### Usage Report Generation
The Agent will automatically detect report generation intent, switch to report prompts, and generate Markdown-format usage reports using external data:
```
User: Generate my usage report
User: Provide me with a usage analysis and maintenance suggestion for my robot vacuum cleaner
```
---
## 🛠 Tool List
The Agent is equipped with the following 7 tools:
| Tool Name | Description |
|--------|------|
| `rag_summarize` | Retrieve reference materials from vector knowledge base to answer product-related questions |
| `get_weather` | Get real-time weather for a specified city (Gaode API) |
| `get_user_location` | Get user's location through IP (Gaode API) |
| `get_user_id` | Get current user ID |
| `get_current_month` | Get current month |
| `fetch_external_data` | Retrieve specified user's usage records for a specified month from external systems |
| `fill_context_for_report` | Trigger report mode, notify middleware to switch to report generation prompts |
---
## 🔄 Middleware Mechanism
The Agent's three middlewares are responsible for monitoring, logging, and dynamic prompt switching:
```
monitor_tool Tool call monitoring
├─ Record tool call names and parameters
├─ Record tool call success/failure status
└─ Detect fill_context_for_report call, set context["report"] to True
log_before_model Model call logging
└─ Record current message count and latest message content
report_prompt_switch Dynamic prompt switching
├─ context["report"] == True → Use report generation prompts
└─ context["report"] == False → Use main ReAct prompts
```
---
## 📋 Log Instructions
Log files are stored in the `logs/` directory, created automatically by day:
```
logs/
└── agent_20250101.log # Format: {name}_{YYYYMMDD}.log
```
Log format:
```
2025-01-01 12:00:00,123 - agent - INFO - middleware.py:19 - [tool monitor] Executing tool: get_weather
```
- **Console**: Output INFO and above logs
- **File**: Output DEBUG and above logs (more detailed)
---
## 📚 Knowledge Base
Knowledge base documents are stored in the `data/` directory, supporting `.txt` and `.pdf` formats. Upon first startup, the system will automatically vectorize documents and store them in the Chroma database (`chroma_db/`). Processed documents are tracked using MD5 hashes to avoid duplicates.
**Built-in Knowledge Base Documents:**
| File | Content |
|------|------|
| `robot_vacuum_cleaner_100_questions.pdf` | Robot Vacuum Cleaner FAQ (PDF) |
| `robot_vacuum_cleaner_100_questions_2.txt` | Robot Vacuum Cleaner Supplementary Q&A |
| `robot_vacuum_cleaner_and_mop_100_questions.txt` | Robot Vacuum-Mop FAQ |
| `troubleshooting.txt` | Troubleshooting Guide |
| `maintenance_and保养.txt` | Maintenance and保养 Instructions |
| `purchasing_guide.txt` | Purchasing Guide and Selection Guide |
To extend the knowledge base, simply add new `.txt` or `.pdf` files to the `data/` directory, and the system will automatically load them upon restart.
---
## 🔮 Future Optimization Directions
- Replace Chroma with Redis vector database (more suitable for production deployment)
- Complete migration of location and weather functions to Gaode MCP protocol
- Add user authentication and multi-user session isolation
- Support more document formats (Word, Excel, etc.)
---
## 📄 License
This project is for learning and reference purposes only.
Thanks to Black Horse Programmer's open-source free projects, Alibaba Cloud, and Gaode Map's open platforms.
