# 2. Kiến trúc Dual-Agent Flow

Để xử lý mượt mà 5 Mode tâm lý khách hàng, hệ thống Lead Search không sử dụng 1 Agent nguyên khối (Monolith) cồng kềnh, mà chia ra làm **Hai Agent phối hợp** với nhau (Classifier và Stylist).

Sự phân cực này giúp hệ thống:
1. **Tiết kiệm chi phí (Cost):** Chỉ có Agent làm nhiệm vụ chốt sale cuối cùng mới dùng Model xịn (Nặng), còn lại Model định tuyến dùng con nhỏ (Nhẹ).
2. **Tốc độ (Latency):** Định tuyến siêu tốc, không bị chèn ép Context Window.

---

## 🏛 Sơ đồ Luồng Hai Tầng (Dual-Agent Architecture)

![Kiến trúc Dual-Agent](lead_search_arch.svg)

> Sơ đồ trên minh họa quá trình một tin nhắn của người dùng đi qua 2 trạm kiểm soát trước khi tạo ra câu trả lời cuối cùng.

---

## 🕵️ AI #1: Classifier Agent (Ngòi nổ)

**Vị trí:** `backend/agent/lead_stage_agent/graph.py` -> `_classifier_node()`
**Đặc điểm:** Dùng Model nhỏ, nhẹ, output ép kiểu JSON (Structured Output).

Nhiệm vụ của Classifier giống như một **Lễ tân / Người chẩn bệnh**:
1. Đọc tin nhắn mới nhất và `InsightJSON` (Hồ sơ cũ) của khách.
2. Quyết định khách đang ở Mode nào (1 trong 5 Mode).
3. **Quyết định gọi Tool hay không:**
   - Nếu khách chỉ chào hỏi (Mode 1) -> **Early Exit**: Pass thẳng qua cho Stylist để vỗ về khách, KHÔNG chọc vào Database tìm đồ.
   - Nếu khách tìm đồ -> Kích hoạt cơ chế **Split Query** (Tách truy vấn) và truyền vào `ProductSearchEngine`.

---

## 👗 AI #2: Stylist Agent (Kẻ chốt sale)

**Vị trí:** `backend/agent/lead_stage_agent/graph.py` -> `_stylist_node()`
**Đặc điểm:** Dùng Model lớn, Nặng, sở hữu `STYLIST_SYSTEM_PROMPT` với hàng loạt quy tắc cấm kỵ (Guardrails).

Nhiệm vụ của Stylist giống như một **Best Seller thực thụ**:
1. Nhận toàn bộ data đổ về từ `ProductSearchEngine` (Nếu Classifier có gọi Tool).
2. Nhận tone giọng/chỉ thị dựa trên 5 Mode.
3. Sinh ra đoạn văn bản tư vấn (Draft AI Reply) thuyết phục nhất có thể, sử dụng data `ai_matches` để gợi ý combo.
4. **Cập nhật Bộ nhớ (Update Insight):** Ghi chép lại xem khách vừa xem cái gì (`LATEST_PRODUCT_INTEREST`), ngân sách khách có bao nhiêu (`CONSTRAINS`), để ván sau Classifier đọc mà định tuyến tiếp.

---

> [!NOTE]
> Sự tương tác giữa Classifier và Stylist thông qua `LeadStageState` là hạt nhân của LangGraph. Bất cứ khi nào bạn thấy AI hành xử sai (ví dụ: đòi số điện thoại quá sớm), 90% lỗi nằm ở việc Classifier chẩn đoán sai Mode, dẫn đến Stylist chốt sale sai thời điểm.
