Bài 2 — Kiến trúc Agent & luồng xử lý end-to-end

Trước khi viết dòng code nào, bạn cần một bản đồ: email đi từ hộp thư đến hành động cuối như thế nào. Bài này dựng kiến trúc chuẩn để mọi bài sau lắp vào.

Luồng 6 tầng của một Agent triage

[1] Ingest    → lấy email mới (IMAP / Gmail API / webhook)
[2] Normalize → trích tiêu đề, người gửi, body sạch, tệp đính kèm
[3] Classify  → LLM gán category + priority + action + owner
[4] Decide    → áp policy: được tự làm hay cần người duyệt
[5] Act       → gắn nhãn, tạo nháp, chuyển tiếp, lưu trữ
[6] Log       → ghi lại mọi quyết định để audit

Mỗi tầng tách rời nhau. Nếu tầng Classify sai, bạn không mất dữ liệu vì tầng Log giữ lại mọi thứ, và tầng Decide chặn hành động nguy hiểm.

Vì sao tách Classify và Act

Đây là nguyên tắc quan trọng nhất: tầng suy luận (LLM) không được trực tiếp thao tác hộp thư. LLM chỉ đề xuất một quyết định JSON. Code truyền thống (tầng Decide + Act) mới thực thi. Lý do:

• LLM có thể "ảo giác" ra một địa chỉ chuyển tiếp không tồn tại.
• Bạn cần kiểm soát: chỉ cho phép hành động trong danh sách trắng.
• Dễ test: bạn test Classify bằng dữ liệu, test Act bằng mock.

Ví dụ hợp đồng dữ liệu giữa các tầng

Tầng Classify nhận đầu vào chuẩn hóa:

{
  "from": "nhacc@supplier.vn",
  "subject": "Hóa đơn tháng 6 đã đến hạn",
  "body": "Kính gửi, hóa đơn 4.2 triệu...",
  "has_attachment": true
}

Và bắt buộc trả về đúng schema:

{
  "category": "Hóa đơn/Tài chính",
  "priority": "Bình thường",
  "action": "label_and_forward",
  "owner": "ke-toan@congty.vn",
  "confidence": 0.86
}

Trường confidence cực kỳ hữu ích: nếu dưới ngưỡng (vd 0.6), tầng Decide sẽ tự động chuyển sang chế độ "cần người duyệt".

Các bước dựng kiến trúc

• Vẽ sơ đồ 6 tầng cho case của bạn trên giấy trước.
• Định nghĩa schema JSON đầu ra của tầng Classify (cố định các trường).
• Liệt kê action hợp lệ thành một enum: label, draft_reply, forward, archive, escalate. Không action nào ngoài danh sách này được thực thi.
• Quyết định trigger: chạy theo lịch (cron mỗi 5 phút) hay theo sự kiện (webhook Gmail push). Người mới nên bắt đầu bằng cron cho đơn giản.
• Thiết kế bảng log với các cột: email_id, category, priority, action, executed (bool), timestamp, human_reviewed.

Khung quyết định tại tầng Decide (pseudocode)

decide(result):
    if result.action not in ALLOWED_ACTIONS:
        return "escalate"          # an toàn: không rõ thì đẩy người
    if result.confidence < 0.6:
        return "needs_review"      # thấp tự tin → chờ duyệt
    if result.category in SENSITIVE:  # HR, pháp lý, hoàn tiền lớn
        return "needs_review"
    return result.action           # được phép tự thực thi

Checklist kiến trúc

• [ ] Sơ đồ 6 tầng đã vẽ.
• [ ] Schema JSON đầu ra cố định.
• [ ] Enum action hợp lệ (danh sách trắng).
• [ ] Ngưỡng confidence để escalate.
• [ ] Danh mục category nhạy cảm luôn cần người.
• [ ] Bảng log audit đã thiết kế.

Sai lầm thường gặp

• Để LLM gọi thẳng API gửi thư. Đây là lỗi nghiêm trọng nhất — mất kiểm soát hoàn toàn. Luôn chèn tầng Decide ở giữa.
• Không có schema cố định, để LLM trả văn xuôi. Kết quả là code parse vỡ liên tục. Ép JSON schema ngay từ đầu.
• Bỏ qua tầng Log. Khi agent làm sai, không có log bạn không biết vì sao và không sửa được.
• Chọn webhook quá sớm. Webhook phức tạp (xác thực, retry, endpoint public). Cron 5 phút đủ tốt cho hầu hết trường hợp lúc đầu.
• Quên trường confidence, khiến mọi email được xử lý như nhau dù agent "đoán mò" hay chắc chắn.

Bài sau: kết nối thực tế vào hộp thư qua IMAP/Gmail API và lấy được email đầu tiên.