🏫 BÀI LAB 3: CHATBOT VS REACT AGENT — TỪ LÝ THUYẾT ĐẾN THỰC THI (MCP ENHANCED)

Mã bài học: DAY03-REACT-AGENT
Hình thức thực hiện: CÁ NHÂN (Mỗi học viên tự làm và tự nộp 1 bài cá nhân)
Quy chuẩn nộp bài: Học viên Fork Repo này về GitHub cá nhân và đổi tên theo đúng cú pháp:
📌 K4-DAY03-HoVaTen-MSSV (Ví dụ: K4-DAY03-NguyenVanA-SV2026001)

---

⚡ 1. QUICKSTART — CÀI ĐẶT MÔI TRƯỜNG & CHẠY THỬ (3 PHÚT)

🐍 Yêu cầu môi trường Python: Python 3.10 – 3.12 (Tránh Python 3.9 do thiếu type hinting hiện đại và Python 3.13 do nhiều thư viện AI chưa hỗ trợ pre-built wheel).

Thực hiện 3 bước lệnh Terminal thiết thực ngay khi clone repo về máy:

Bước 1: Clone Repo & Tạo môi trường ảo

git clone https://github.com//K4-DAY03-HoVaTen-MSSV.git
cd K4-DAY03-HoVaTen-MSSV

python -m venv .venv
# Trên Windows PowerShell:
.venv\Scripts\Activate.ps1
# Trên macOS / Linux / Bash / Zsh:
source .venv/bin/activate

Bước 2: Cài đặt thư viện & Tạo file cấu hình môi trường

pip install -r requirements.txt
# Trên Windows CMD/PowerShell:
copy .env.example .env
copy config\test_cases.example.json config\test_cases.json
# Trên macOS / Linux:
cp .env.example .env
cp config/test_cases.example.json config/test_cases.json

Bước 3: Chạy thử Baseline kiểm tra môi trường

python src/app.py --all

Kỳ vọng Output màn hình:

✅ [MOCK OFFLINE MODE PASS]: Môi trường đã sẵn sàng! 
📊 [KẾT QUẢ TEST SUITE]: 2 Đã chạy (TC01, TC02 mẫu) | 3 Đang chờ viết câu hỏi (TODO)

🔑 QUY ĐỊNH BẮT BUỘC VỀ API KEY VÀ NỘP BÀI (SUBMISSION REQUIREMENT):

1. Giai đoạn gõ code & debug (Miễn phí 0đ): Hệ thống mặc định chạy MockOfflineProvider giúp bạn thực hành gõ code, kiểm thử logic ban đầu hoàn toàn miễn phí, không tốn token, không lo nghẽn mạng.
2. Giai đoạn NỘP BÀI CHÍNH THỨC (Bắt buộc dùng LLM thật): Khi chạy nghiệm thu để lấy dữ liệu dán vào báo cáo docs/trace_eval.md nộp bài, học viên BẮT BUỘC phải mở file .env điền GEMINI_API_KEY (hoặc OPENAI_API_KEY) để Agent giao tiếp với mô hình LLM thật.

⚠️ Lưu ý: Bài nộp chỉ chạy trên Mock Provider mà không kết nối LLM API thật sẽ bị trừ điểm phần nghiệm thu thực tế (Tiêu chí 2 & Tiêu chí 3 trong Rubric).

---

🎯 2. BỨC TRANH TỔNG THỂ & MỤC TIÊU DÀI HẠN (NORTH STAR GOAL)

Mục tiêu cốt lõi của Bài Lab này là giúp học viên tự tay phát triển một Trợ lý Tác tử ReAct (ReAct Agent) hoàn chỉnh.

Thay vì chỉ sinh văn bản hội thoại đơn thuần như Chatbot cơ bản, tác tử (Agent) của bạn sẽ có khả năng:

1. Tự suy luận và chọn công cụ: Chủ động kích hoạt vòng lặp ReAct (Thought -> Action -> Observation) qua giao thức Model Context Protocol (MCP) để truy vấn dữ liệu thực tế.
2. Tổng hợp câu trả lời chính xác: Sử dụng dữ liệu thực tế từ Tool trả về để trả lời sinh viên, tránh hiện tượng ảo giác (Hallucination).