Content
# Tool List
> **Project Version**: v0.4.0
> **Project Positioning**: Full-stack AI intelligent customer service backend system, covering LLM Agent, RAG retrieval enhancement, long-term memory and user profiling, MCP standard protocol, Web chat interface
## I. Project Overview
This project is an intelligent customer service agent backend service for e-commerce scenarios, supporting users to query orders, track logistics, query complaint tickets, and retrieve company policy knowledge base through natural language. The system also provides three external interfaces:
| Interface Layer | Path | Purpose |
| --- | --- | --- |
| Web Chat UI | `GET /` | Graphical chat interface for direct browser use |
| REST API | `POST /api/chat` | Standard HTTP JSON interface for frontend/third-party invocation |
| MCP SSE | `GET /mcp/sse` + `POST /mcp/messages` | MCP standard protocol for AI client invocation such as Claude Desktop |
## II. Key Technology Stack
```
┌─────────────────────────────────────────────────────┐
│ Web Framework Layer │
│ FastAPI 0.138 + Uvicorn 0.34 + Pydantic 2.10 │
├─────────────────────────────────────────────────────┤
│ AI / Agent Layer │
│ LangChain 0.3 + LangChain-OpenAI + DeepSeek │
├─────────────────────────────────────────────────────┤
│ Long-Term Memory / User Profiling │
│ SQLite (sqlite3) + FastAPI BackgroundTasks │
│ + LLM-driven Preference Extraction Pipeline │
├─────────────────────────────────────────────────────┤
│ RAG Retrieval Layer │
│ FAISS 1.14 + Sentence-Transformers 3.4 │
│ (all-MiniLM-L6-v2) + LangChain-Community │
├─────────────────────────────────────────────────────┤
│ MCP Protocol Layer │
│ mcp 1.28 + sse-starlette 3.4 │
├─────────────────────────────────────────────────────┤
│ Tools & Infrastructure │
│ Loguru (logging) + python-multipart + httpx │
└─────────────────────────────────────────────────────┘
```
### 2.1 FastAPI (Web Framework)
**Selection Reason**: Asynchronous native support, automatic OpenAPI document generation, Pydantic deep integration, type safety.
- `lifespan` context manager: manage application startup/shutdown lifecycle
- `CORSMiddleware`: allow cross-domain (friendly for frontend debugging)
- Custom HTTP middleware: generate `request_id` for each request and inject log context
- Three sub-routes: `chat_ui` (HTML page), `chat` (Agent API), `mcp_router` (SSE long connection)
### 2.2 LangChain + DeepSeek (LLM Agent)
**Selection Reason**: LangChain provides a unified Agent abstraction layer (`create_tool_calling_agent`), DeepSeek compatible with OpenAI protocol, high cost-performance.
- **Model**: `deepseek-chat`, called through `ChatOpenAI(base_url="https://api.deepseek.com")`
- **Agent Mode**: Tool-Calling Agent (native Function Calling), not the old ReAct text template
- **AgentExecutor Configuration**: `temperature=0.3` (customer service scenario requires stability), `max_iterations=5`, `handle_parsing_errors=True` (automatic format error repair)
- **Session Management**: `InMemoryChatMessageHistory`, store multi-turn dialogue context with `conversation_id` as key
- **System Prompt**: carefully designed structured prompt words, defining persona ("Xiaozhi"), tool selection priority, reply specification
### 2.3 RAG (Retrieval-Augmented Generation)
**Process**: `faq.md → TextLoader → RecursiveCharacterTextSplitter → HuggingFaceEmbeddings → FAISS`
| Component | Technology Selection | Description |
| --- | --- | --- |
| Document Loading | `TextLoader` (LangChain) | Read Markdown files |
| Text Chunking | `RecursiveCharacterTextSplitter` | chunk_size=500, overlap=100 |
| Vectorization | `all-MiniLM-L6-v2` (384 dimensions) | Lightweight, multi-language, CPU available |
| Vector Storage | FAISS (IndexFlatL2) | Meta's open-source vector retrieval library, no GPU dependency |
| Persistence | `faiss_index/` directory | `index.faiss` + `index.pkl` disk files |
**Why RAG is Important**: Solve LLM's two major pain points: "hallucinations" and "lack of private knowledge". When users ask "who pays for return shipping", Agent does not rely on memory to fabricate, but retrieves the original text of "1.3 Shipping Rules" from the vector library.
### 2.4 MCP (Model Context Protocol)
**Selection Reason**: Anthropic's proposed AI tool calling standard protocol, allowing any MCP client (Claude Desktop, Codex, etc.) to discover and call the tools of this system.
- **Server**: `FastMCP` (high-level API of the mcp package)
- **Transport Layer**: SSE (Server-Sent Events) — `GET /mcp/sse` establishes a long connection, `POST /mcp/messages` receives JSON-RPC messages
- **Register Tools**: 4 `@mcp.tool()`, sharing the same set of underlying services with LangChain Tool
### 2.5 Log System (Loguru)
- Three-way output: console (colored DEBUG) + file (daily rotation, 30-day retention) + error file (90-day retention)
- Full-chain tracking: `logger.contextualize(request_id=xxx)` ensures all logs of the same request carry the same ID
- Bottom-line mechanism: `logger.configure(extra={"request_id": "-"})` prevents KeyError when non-HTTP context invocation reports
### 2.6 Long-Term Memory & User Profiling
**Selection Reason**: Short-term memory (session history) disappears with session end; long-term memory spans conversations, continuously accumulating user preferences, allowing Agent to evolve from a "one-time tool" to a "private secretary who understands you more and more".
**Architecture**:
```
Each conversation end (BackgroundTasks asynchronously):
Conversation record → LLM analysis → extract preference JSON → SQLite persistence
│
Next conversation start (run_agent synchronous injection):
Agent input ← 【User Profile】← JSON deserialization ←──┘
```
| Component | Technology Selection | Description |
| --- | --- | --- |
| Storage | Python's built-in `sqlite3` | Zero external dependency, single-file database `data/user_memory.db` |
| Table Structure | `user_profiles(user_id TEXT PK, facts TEXT, updated_at)` | facts is JSON format, adapting to the flexible changes of profile fields |
| Extraction Method | DeepSeek LLM asynchronous call | Specialized Prompt guides LLM to extract 6 types of features from conversations |
| Asynchronous Mechanism | FastAPI `BackgroundTasks` | Memory extraction as a background task, **not blocking HTTP response** |
| Injection Timing | Synchronous query in `run_agent()` | Read SQLite before each conversation, inject profile into Agent input |
| Merging Strategy | New key append, existing key override | JSON-level merge, latest information priority |
**6 Dimensions Extracted by LLM**:
1. **Logistics Preference** — Preferred express company, delivery time preference
2. **Consumption Habit** — Frequently purchased categories, price sensitivity, preference for promotions
3. **Communication Style** — Like concise or detailed, whether impatient
4. **Personal Information** — Address preference, location, membership level
5. **Complaint Tendency** — Easily complain about what issues, complaint frequency
6. **Other Features** — Any fixed attributes worth recording
**Prompt Design Key Points**:
- Temperature set to `0.1` (extremely low), ensuring JSON output stability and parsing
- Pass existing profile to avoid repeated extraction
- Force JSON output format `{"facts": {...}}`
- Return `{}` to skip writing when no valid features
## III. Project Architecture Diagram
```
┌──────────────────────┐
│ MCP Client │
│ (Claude Desktop, etc.) │
└──────┬───────┬───────┘
│ SSE │ POST
▼ ▼
┌──────────┐ POST /api/chat ┌──────────────────────────────┐
│ Web UI │ ────────────────▶ │ FastAPI :8000 │
│ / │ ◀──────────────── │ │
└──────────┘ {reply, conv_id}│ /mcp/sse ─── mcp_router ────┤
│ /mcp/msg ─── mcp_router ────┤
│ /api/chat ── chat router ───┤
│ / ── chat_ui ──────┤
└─────────────┬────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ [Synchronous] │ [Asynchronous BackgroundTasks] │
▼ ▼ │
┌──────────────────────┐ ┌──────────────────────┐ │
│ agent/core.py │ │ memory_manager.py │ │
│ Tool-Calling Agent │ │ LLM profile extraction│ │
│ + short-term session │ │ → SQLite write │ │
│ history + long-term │ │ ← conversation history│ │
│ profile injection ←─────┼───│ ← profile read │ │
└──────┬──────┬──────┬──┘ └──────────┬───────────┘ │
│ │ │ │ │
┌──────────▼┐ ┌──▼──────▼──┐ ┌────────▼──────────┐ │
│ RAG Tool │ │ Business Tools│ │ user_memory.db │ │
│ (Knowledge│ │ Order/Logistics│ │ (SQLite profile │ │
│ Base) │ │ Complaint │ │ storage) │ │
└─────┬─────┘ └──────┬──────┘ └───────────────────┘ │
│ │ │
┌─────▼─────┐ ┌──────▼────────┐ │
│ FAISS │ │ mock_services │ │
│ all-MiniLM│ │ (mock backend │ │
│ │ │ data) │ │
└─────┬─────┘ └───────────────┘ │
│ │
┌─────▼─────┐ │
│faq.md │ │
│(Policy │ │
│ Document) │ │
└───────────┘ │
```
**Synchronous Channel (User Perception) + Asynchronous Channel (Background Silent)**:
1. **Web UI** → `/api/chat` → `agent/core.py` (profile injection → reply) → BackgroundTasks → `memory_manager.py` (profile extraction)
2. **REST API** → Same as above
3. **MCP Client** → `/mcp/sse` → `mcp_server.py` → Directly call Services
## 4. Project File List
```
AgentService/
├── .env.example # Environment variable template (DeepSeek API Key, etc.)
├── .mcp.json # MCP client connection configuration
├── requirements.txt # Python dependency list (6 groups, 16 packages)
├── run.py # Development environment startup entry
├── mcp_server.py # MCP Server (4 Tool registrations)
├── app/
│ ├── main.py # FastAPI entry + middleware + route registration
│ ├── core/
│ │ └── logger.py # Loguru log configuration (3 output paths + full-chain tracking)
│ └── routers/
│ ├── chat.py # /api/chat conversation interface + /api/chat/session/{id} session management
│ ├── chat_ui.py # / Web chat interface (inline HTML+CSS+JS)
│ └── mcp_router.py # /mcp/sse + /mcp/messages MCP SSE transmission
├── agent/
│ ├── core.py # LangChain Agent core (DeepSeek + Tool Calling + session management + profile injection)
│ └── memory_manager.py # Long-term memory manager (SQLite + LLM profile extraction + BackgroundTasks)
├── tools/
│ └── agent_tools.py # 4 LangChain Tools (order/logistics/complaint/RAG)
├── services/
│ └── mock_services.py # 3 Mock business functions (simulating backend data)
├── rag/
│ └── retriever.py # RAG pipeline (FAISS + all-MiniLM-L6-v2)
├── models/
│ └── schemas.py # Pydantic data models
├── data/
│ ├── faq.md # E-commerce FAQ knowledge base (5 categories of policy documents)
│ └── user_memory.db # SQLite user profile database (generated at runtime)
├── faiss_index/ # FAISS vector index persistence directory (generated at runtime)
└── logs/ # Log file directory (generated at runtime)
```
---
## 5. Quick Start
```bash
# 1. Configure API Key
cp .env.example .env
# Edit .env: DEEPSEEK_API_KEY=sk-your-real-key
# 2. Install dependencies
pip install -r requirements.txt
# 3. Start service
python run.py
# 4. Usage
# - Web UI: http://localhost:8000/
# - API documentation: http://localhost:8000/docs
# - MCP connection configuration: view .mcp.json
# - Health check: http://localhost:8000/health
# 5. Test (requires a real API Key to obtain LLM response)
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"user_id":"U10086","message":"Who bears the return shipping cost?"}'
```
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available