EDU-12 — Flow xây dựng & Luồng chạy Agent

Đề gốc: DE-BAI.md

⚠️ Toàn bộ file này là đề xuất thiết kế của nhóm, không phải nội dung đề. Đề chỉ nêu tech stack và yêu cầu đầu ra ở mức gợi ý, không quy định flow làm việc. Sửa thoải mái.

Phần A — Flow xây dựng (build order)

A.1. Vấn đề của flow tuyến tính

Flow ban đầu (Requirement → Design → DB → Model → Repository → Service → Agent → API → UI) đúng về thứ tự phụ thuộc, nhưng đặt AI Agent ở gần cuối.

Rủi ro của đề này không nằm ở CRUD. Repository/Service là phần chắc chắn làm được. Rủi ro nằm ở câu hỏi: RAG trên tài liệu tuyển sinh có đạt nổi accuracy ≥85% không? Nếu chunking sai, reranker không hiệu quả, hoặc tài liệu gốc lộn xộn → phải đổi cả hướng thiết kế. Theo flow tuyến tính thì tới tuần 5–6 mới phát hiện.

→ Tách 2 nhánh chạy song song sau bước thiết kế.

A.2. Flow đề xuất

Đặc tả yêu cầu (Requirement Specification)
        │
        ▼
Thiết kế hệ thống (Architecture Design)
        ├── Thiết kế DB
        ├── Thiết kế API (API Spec)
        ├── Thiết kế Agent          ← xem Phần B
        ├── Thiết kế Prompt/Workflow
        └── Thiết kế UI                      ← nhóm đang ở đây
        │
        ├──────────────────────┬──────────────────────────┐
        ▼                      ▼
   ┌─ NHÁNH 1: RAG CORE ─┐  ┌─ NHÁNH 2: APP ─────────┐
   │  (ưu tiên, làm sớm) │  │                        │
   │                     │  │  Xây dựng Database     │
   │  Thu thập tài liệu  │  │        ▼               │
   │  tuyển sinh chính   │  │  Model (Entity/ORM)    │
   │  thức               │  │        ▼               │
   │        ▼            │  │  Repository            │
   │  Ingestion pipeline │  │  (Data Access)         │
   │  parse → chunk →    │  │        ▼               │
   │  embed → pgvector   │  │  Service               │
   │        ▼            │  │  (Business Logic)      │
   │  Retrieve + Rerank  │  │                        │
   │        ▼            │  └────────────────────────┘
   │  Bộ test có nhãn    │              │
   │  (~100–200 câu)     │              │
   │        ▼            │              │
   │  Eval script        │              │
   │  answer rate +      │              │
   │  accuracy           │              │
   │        ▼            │              │
   │  ĐO ACCURACY TRẦN   │              │
   │  (chưa cần API/UI)  │              │
   └─────────┬───────────┘              │
             │                          │
             └──────────┬───────────────┘
                        ▼
                  AI Agent (tích hợp)
                  ├── Tools
                  ├── Memory
                  ├── Planner / Router
                  ├── LLM
                  └── Workflow + Guardrails
                        ▼
                  API (Controller)
                        ▼
                  Hook / SDK / Client
                        ▼
                  UI
                        ▼
                  Deploy (Docker + cloud)
                        ▼
                  Chạy lại eval trên hệ thống thật
                  → đối chiếu KPI

A.3. Vì sao tách nhánh 1 ra

Chỉ cần script Python + notebook. Không cần FastAPI, không cần Next.js, không cần DB app.
Chạy được trong 2–3 ngày → biết sớm đề có khả thi không.
Nếu accuracy trần đã dưới 85% khi chưa có nhiễu từ hệ thống → phải xử lý ngay ở tầng dữ liệu (chunking, chất lượng tài liệu, reranker), không phải ở tầng code.
Bộ test có nhãn xây một lần, dùng lại xuyên suốt: lúc tinh chỉnh RAG, lúc tích hợp Agent, lúc nghiệm thu.

A.4. Ba mảng dễ bị bỏ sót

Mảng	Vì sao cần	Thuộc bước nào
Ingestion pipeline	RAG không có gì để trả lời nếu chưa nạp tài liệu. Khác với “Xây dựng Database” (schema user/conversation/handover)	Nhánh 1, đầu tiên
Eval harness + bộ test có nhãn	Đề lấy answer rate ≥70% / accuracy ≥85% làm KPI. Không tự sinh ra ở đâu khác	Nhánh 1, làm sớm
Deploy Docker + cloud	Nằm trong yêu cầu “Cơ bản” của đề	Cuối, nhưng dựng khung sớm

Phần B — Luồng chạy Agent (runtime flow)

Lưu ý: thứ tự build ≠ luồng chạy. Trong sơ đồ build, Tools / Memory / Planner / LLM / Workflow là danh sách thành phần cần code. Dưới đây là trình tự thực thi khi người dùng chat.