Content
# Tool List
> Based on LangChain ReAct Agent + RAG + Streamlit
---
# Must Read
Please make sure to install the required environment configurations, and replace the `gaodekey` in `config/agent.yml` with your actual Gaode API key (you can also change it to a more implicit method according to your needs).
## 📖 Project Introduction
**Zhisaotong Robot Intelligent Customer Service** is an AI intelligent agent application for sweeping robot/ sweeping and mopping integrated robot users. The system uses Streamlit to build a lightweight front-end web page, and the back-end is based on LangChain to build ReAct (Reasoning + Acting) Agent, integrating the following core capabilities:
- **RAG Enhanced Retrieval**: Store product manuals, FAQs, maintenance guides and other documents in vectorized form, and prioritize retrieval of knowledge base when AI answers to ensure accurate and reliable answers.
- **Gaode MCP Service**: Call Gaode Map API to get user location and weather information in real-time.
- **Summary Report Mode**: The middleware dynamically switches system prompts by identifying specific intentions, and automatically generates usage reports in Markdown format.
- **Multi-Round Tool Calling**: Agent can autonomously 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 side to enhance interaction experience.
- **Complete Logs and History**: Equipped with structured logs (files + console) and conversation history records.
---
## ✨ 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 Service** | Gaode Map REST API (weather, IP location) |
| **Dynamic Prompts** | Middleware automatically switches system prompts based on context signals |
| **Deduplication Mechanism** | MD5 hash tracking of processed documents to avoid duplicates |
| **Logs** | Daily file logging, output to console and file |
---
## 🏗 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 & Logging │ │
│ │ ├─ log_before_model Model Call Pre-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/
│ ├──扫地机器人100问.pdf
│ ├──扫地机器人100问2.txt
│ ├──扫拖一体机器人100问.txt
│ ├──故障排除.txt
│ ├──维护保养.txt
│ ├──选购指南.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
It is recommended to use **Python 3.10+** (the code uses `tuple[str, str]` and other 3.10+ type annotation syntax).
### Main Dependency Packages
| Package | Purpose |
|------|------|
| `streamlit` | Front-end Web Framework |
| `langchain` | Agent / Chain / Tool Framework |
| `langchain-core` | LangChain Core Abstraction |
| `langchain-community` | Integration with Tongyi Qianwen, DashScope Embedding, etc. |
| `langgraph` | Graph-based Agent Execution Engine (including `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 Parsing |
### 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 large model and DashScope Embedding, and you need to configure the system environment variable:
```bash
OPENAI_API_KEY="your_open_api_key"
```
> You can obtain the 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
```
> You can apply for a Web Service API Key from [Gaode Open Platform](https://console.amap.com/).
### 3. Model Configuration
Edit `config/rag.yml` to adjust the model used:
```yaml
# config/rag.yml
chat_model_name: qwen3-max # Dialogue Large 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 by retrieval
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
Directly ask questions about the sweeping robot's use, maintenance, troubleshooting, and other issues, and the Agent will prioritize retrieval of relevant information from the knowledge base to answer:
```
User: How often do I need to replace the filter of the sweeping robot?
User: What is the difference between the sweeping robot and the sweeping and mopping integrated robot?
User: What should I do if the sweeping robot's suction power becomes weaker?
```
### Weather and Location Query
The Agent can call Gaode API to get real-time information:
```
User: What is the weather like today in the city where I am?
```
### Usage Report Generation
The Agent will automatically detect the report generation intention, switch to the report prompt, and call external data to generate a usage report in Markdown format:
```
User: Help me generate my usage report
User: Give me a usage analysis and maintenance suggestion for the sweeping robot
```
---
## 🛠 Tool List
The Agent is equipped with the following 7 tools:
| Tool Name | Description |
|--------|------|
| `rag_summarize` | Retrieve reference materials from the vector knowledge base to answer product-related questions |
| `get_weather` | Get real-time weather for a specified city (Gaode API) |
| `get_user_location` | Get the user's location through IP (Gaode API) |
| `get_user_id` | Get the current user ID |
| `get_current_month` | Get the current month |
| `fetch_external_data` | Get the usage records of a specified user for a specified month from an external system |
| `fill_context_for_report` | Trigger report mode and notify the middleware to switch to the report generation prompt |
---
## 🔄 Middleware Mechanism
The Agent's three middlewares are responsible for monitoring, logging, and dynamic prompt switching:
```
monitor_tool Tool call monitoring
├─ Record each tool call name and parameter
├─ Record tool call success/failure status
└─ Detect fill_context_for_report call and set context["report"] to True
log_before_model Pre-model call logging
└─ Record current message count and latest message content
report_prompt_switch Dynamic prompt switching
├─ context["report"] == True → Use report generation prompt
└─ context["report"] == False → Use main ReAct prompt
```
---
## 📋 Log Description
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 level logs
- **File**: Output DEBUG and above level logs (more detailed)
---
## 📚 Knowledge Base
Knowledge base documents are stored in the `data/` directory, supporting `.txt` and `.pdf` formats. The system will automatically vectorize the documents and store them in the Chroma database (`chroma_db/`) when started for the first time. Processed documents are tracked by MD5 hash, and duplicate entries will not be added after restarting.
**Built-in Knowledge Base Documents:**
| File | Content |
|------|------|
| `扫地机器人100问.pdf` | Sweeping Robot FAQ (PDF) |
| `扫地机器人100问2.txt` | Sweeping Robot Supplementary Q&A |
| `扫拖一体机器人100问.txt` | Sweeping and Mopping Integrated Robot FAQ |
| `故障排除.txt` | Troubleshooting Guide |
| `维护保养.txt` | Daily Maintenance and保养 Instructions |
| `选购指南.txt` | Purchase Suggestions and Selection Guide |
If you need to expand the knowledge base, simply add new `.txt` or `.pdf` files to the `data/` directory, and the system will automatically load them after restarting.
---
## 🔮 Future Optimization Directions
- Replace the vector database from Chroma with Redis (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 the open-source free projects of Black Horse Programmers, Alibaba Cloud, and Gaode Map, etc.
