Content
# Enterprise Customer Service Agent V2
An AI Agent backend project for enterprise customer service scenarios, covering user queries, intent understanding, task planning, knowledge base retrieval, short-term/long-term memory, tool invocation, human confirmation, business system execution, link tracking, and result storage.
Compared to V1, V2 introduces LangGraph, HIL (checkpoint / interrupt / resume), MCP business service boundaries, short-term and long-term memory, model cost governance, and observability and evaluation capabilities.
## Architecture
Core execution link:
```text
User / Operations Console / Business Frontend
-> API Gateway / FastAPI
-> Request validation, tenant identification, rate limiting, authentication
-> LangGraph Customer Service State Graph
-> Load short-term session memory
-> Read long-term user memory
-> Standardize user queries and identify intents
-> Planner breaks down complex tasks
-> RAG retrieves after-sales knowledge base
-> Select models based on cost strategy
-> Large model initial decision
-> Direct response
-> Generate tool invocations
-> Trigger human confirmation interruption
-> ToolRegistry executes business tools
-> MCP Client
-> After-sales MCP service
-> Order / Logistics / Work Order / Coupon / Search system
-> Large model secondary summary of tool results
-> Write messages, memories, audit logs, and metrics
-> Return answers, link tracking, knowledge evidence, tool results, confirmation status
```
The core principle is to let large models handle understanding, reasoning, and decision-making, while backend tools and MCP services handle real business actions, constrained by tenant isolation, human confirmation, idempotence control, and audit logs.
## Cost Governance
V2's cost governance goal is not simply to reject services, but to dynamically adjust operating strategies when tenant daily usage approaches or exceeds the budget, ensuring the customer service link remains available:
- When downgrading models, reduce task complexity, avoid complex planning, multi-tool chains, and long reasoning, and prioritize deterministic rules for controllable judgments.
- Use lower-cost models with clearer structured prompts, reducing model flexibility and improving intent identification and tool parameter generation stability.
- Continue using strict parameter validation for tool invocations; if critical fields like order numbers, reasons, or confirmation tokens are missing, ask for clarification or interrupt instead of directly executing business actions.
- For ambiguous references like "this," "that," "just now," or "above," prioritize rewriting questions or supplementing short-term memory to prevent low-cost model misunderstandings.
- High-risk actions do not reduce safety standards with model downgrades; operations like refunds, compensation, exchanges, or transfers to human agents still require human confirmation, idempotence control, and audit records.
- Cost strategies adjust models, RAG recall numbers, historical windows, rerank, and cache priorities, not just replacing one cheaper model name.
## Tech Stack
- Python 3.11+
- FastAPI
- Pydantic v2
- SQLAlchemy 2.x Async ORM
- MySQL
- Redis
- Qdrant / Milvus
- LangGraph
- MCP Python SDK
- OpenAI-compatible Chat Completions API
- OpenAI-compatible Embeddings API
- LangSmith
- Prometheus / Grafana
- pytest
- ruff
## Project Structure
```text
enterprise-customer-service-agent-v2/
Dockerfile
docker-compose.yml
pyproject.toml
requirements.txt
assets/
sample_knowledge/
scripts/
check_env.py
init_db.py
seed_sample_data.py
ingest_docs.py
run_dev.py
run_after_sales_mcp_server.py
mcp_services/
after_sales_server/
src/customer_service_app/
api/
core/
domain/
infrastructure/
cache/
db/
embeddings/
llm/
mcp/
observability/
search/
vector_store/
prompts/
services/
tools/
workflows/
web/
tests/
```
## Configuration
Copy environment variable template:
```bash
cp .env.example .env
```
Main configurations:
```dotenv
APP_ENV=production
PUBLIC_API_BASE_URL=https://api.example.com
ALLOWED_ORIGINS=https://console.example.com
LLM_PROVIDER=openai_compatible
LLM_API_KEY=<your-llm-api-key>
LLM_BASE_URL=https://llm-provider.example.com/v1
LLM_MODEL=<chat-model-name>
EMBEDDING_PROVIDER=openai_compatible
EMBEDDING_API_KEY=<your-embedding-api-key>
EMBEDDING_BASE_URL=https://embedding-provider.example.com/v1
EMBEDDING_MODEL=<embedding-model-name>
EMBEDDING_DIMENSION=1024
DATABASE_URL=mysql+aiomysql://<user>:<password>@<mysql-host>:3306/<database>?charset=utf8mb4
REDIS_URL=redis://:<password>@<redis-host>:6379/0
VECTOR_STORE_PROVIDER=qdrant
QDRANT_URL=https://qdrant.example.com
QDRANT_API_KEY=<your-qdrant-api-key>
QDRANT_COLLECTION=customer_service_knowledge
MILVUS_URI=https://milvus.example.com
MILVUS_TOKEN=<your-milvus-token>
MILVUS_COLLECTION=customer_service_knowledge
MCP_AFTER_SALES_ENABLED=true
MCP_AFTER_SALES_URL=https://mcp-after-sales.example.com/mcp
MCP_APPROVAL_SIGNING_SECRET=<random-signing-secret>
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=<your-langsmith-api-key>
PROMETHEUS_ENABLED=true
```
## Deployment
The main service can be deployed as a FastAPI application, relying on the following independent infrastructure and business services:
- MySQL: stores sessions, messages, orders, after-sales work orders, confirmation records, audit logs, and long-term memory.
- Redis: handles semantic caching, operational locks, rate limiting strategies, and lightweight counting.
- Qdrant / Milvus: handles after-sales knowledge base vector retrieval.
- After-sales MCP service: provides order, logistics, refund, compensation, exchange, and transfer to human agent business capabilities.
- LangSmith / Prometheus / Grafana: provides link tracking, metrics, dashboards, and operational analysis.
Typical startup sequence:
```bash
python scripts/check_env.py
python scripts/init_db.py
python scripts/seed_sample_data.py
python scripts/ingest_docs.py sample_knowledge --tenant-id <tenant-id>
python scripts/run_after_sales_mcp_server.py
uvicorn customer_service_app.main:app --host 0.0.0.0 --port <port>
```
For containerized deployment, inject environment variables through the target platform and use the project's Dockerfile or Compose template to start services.
## MCP Service
The after-sales MCP service exposes after-sales capabilities as independently managed business tools:
- `query_order_status`
- `query_logistics_status`
- `query_price_protection`
- `query_customer_profile`
- `create_refund_case`
- `create_compensation_case`
- `create_exchange_case`
- `transfer_to_human`
Read-only tools can be executed directly after completing tenant and user verification. Write tools require signature confirmation tokens and idempotence keys to prevent repeated execution of confirmed actions.
## API Example
```bash
curl -X POST "https://api.example.com/api/v1/chat" \
-H "Content-Type: application/json" \
-d '{
"tenant_id": "tenant_001",
"user_id": "user_001",
"conversation_id": null,
"question": "My order 202606040001 has been signed, but the product is damaged. I want to apply for a refund or compensation.",
"history": [],
"metadata": {}
}'
```
## Testing
```bash
pytest -q
ruff check src tests scripts mcp_services/after_sales_server/src
```
## License
MIT
