Bài 5 — Thiết kế agent đầu tiên trên giấy: từ mục tiêu đến tool

Đừng vội mở code. 30 phút thiết kế trên giấy tiết kiệm nhiều ngày sửa lỗi. Bài này cho bạn quy trình 6 bước để đặc tả một agent, dùng ví dụ xuyên suốt: Agent trợ lý xử lý yêu cầu hoàn tiền cho shop online.

Quy trình 6 bước

• Viết mục tiêu một câu, đo được: "Xử lý yêu cầu hoàn tiền của khách: xác minh đủ điều kiện theo chính sách, nếu đủ thì tạo lệnh hoàn tiền, luôn trả lời khách bằng email lịch sự."
• Xác định ranh giới (scope): agent ĐƯỢC làm gì và KHÔNG được làm gì. Ví dụ: được hoàn tối đa 2.000.000đ; trên mức đó phải chuyển người thật.
• Liệt kê tools cần thiết (chính là các hành động):

- tra_don_hang(ma_don) - tra_chinh_sach(loai) (RAG vào tài liệu chính sách) - tao_lenh_hoan_tien(ma_don, so_tien) - chuyen_nguoi_that(ly_do) - gui_email(khach, noi_dung)

• Xác định dữ liệu / memory: chính sách hoàn tiền (long-term qua RAG), lịch sử hội thoại với khách (short-term).
• Vẽ các nhánh quyết định chính: đủ điều kiện? / quá hạn 7 ngày? / vượt hạn mức tiền?
• Định nghĩa điều kiện dừng và fallback: khi nào coi là xong, khi nào bàn giao người thật.

Đặc tả tool cho chắc

Mỗi tool nên ghi rõ: tên, mô tả "khi nào dùng", tham số, và điều gì có thể sai.

tool: tao_lenh_hoan_tien
mo_ta: "Tạo lệnh hoàn tiền cho đơn ĐÃ xác minh đủ điều kiện. Không tự gọi nếu chưa tra chính sách."
tham_so:
  ma_don: string
  so_tien: number  # <= 2.000.000, nếu hơn phải chuyen_nguoi_that
rui_ro: "Không được gọi hai lần cho cùng mã đơn (tránh hoàn tiền trùng)."

Dòng rui_ro cực quan trọng: nó sẽ đi vào system prompt để ràng buộc agent.

Viết System Prompt khung

System prompt là "hiến pháp" của agent. Cấu trúc gợi ý:

Vai trò: Bạn là trợ lý xử lý hoàn tiền của shop X.
Mục tiêu: [mục tiêu một câu ở bước 1].
Quy tắc bắt buộc:
- Luôn tra đơn và tra chính sách TRƯỚC khi tạo lệnh hoàn tiền.
- Nếu số tiền > 2.000.000đ hoặc quá 7 ngày, gọi chuyen_nguoi_that.
- Chỉ dựa trên kết quả tool thật, KHÔNG bịa số liệu.
Định dạng: mỗi bước nêu rõ mình đang làm gì trước khi gọi tool.

Chạy thử "khô" (dry run) trên giấy

Diễn kịch một ca cụ thể: "Khách xin hoàn 500k cho đơn VN200, mua 3 ngày trước, lỗi nhà sản xuất."

• Think: cần tra đơn → Act: tra_don_hang(VN200) → ngày mua 3 ngày trước, tiền 500k. ✔ trong hạn.
• Think: cần tra chính sách lỗi NSX → Act: tra_chinh_sach("loi_nsx") → được hoàn.
• Think: đủ điều kiện, tiền < 2tr → Act: tao_lenh_hoan_tien(VN200, 500000).
• Think: xong → Act: gui_email(...) → dừng.

Nếu dry run gãy ở đâu, sửa thiết kế ở đó — rẻ hơn nhiều so với sửa khi đã code.

Checklist "đã sẵn sàng code"

• [ ] Mục tiêu một câu, đo được?
• [ ] Scope (được/không được) rõ ràng?
• [ ] Mỗi tool có mô tả + rủi ro?
• [ ] Đã có điều kiện dừng và đường fallback về người thật?
• [ ] Đã dry-run ít nhất 2 ca (một ca thuận lợi, một ca ngoại lệ)?

Vì sao dry-run ca ngoại lệ quan trọng hơn ca thuận lợi

Ca thuận lợi hầu như luôn chạy đúng — đó không phải nơi agent hỏng. Rủi ro thật nằm ở ca ngoại lệ: khách xin hoàn 5 triệu (vượt hạn mức), đơn mua 20 ngày trước (quá hạn), hay mã đơn không tồn tại. Hãy diễn kịch riêng cho từng ca này và kiểm tra agent có đi đúng nhánh không: vượt hạn mức phải gọi chuyen_nguoi_that, mã đơn sai phải hỏi lại chứ không bịa. Nếu ở bước nào agent 'nhảy cóc' tới hành động nhạy cảm mà chưa qua bước kiểm tra, đó là lỗ hổng thiết kế cần vá bằng quy tắc trong system prompt — vá ngay trên giấy, khi còn rẻ.

Ghép mọi thứ thành đặc tả một trang

Sản phẩm cuối của bài này là một trang đặc tả bạn có thể đưa cho lập trình viên: mục tiêu một câu, scope (được/không được), bảng tools kèm mô tả và rủi ro, danh sách nguồn dữ liệu RAG, sơ đồ nhánh quyết định, điều kiện dừng và đường fallback. Trang này chính là 'hợp đồng' của agent — khi có tranh cãi về việc 'agent nên làm gì trong ca X', bạn quay lại đặc tả thay vì đoán mò. Đầu tư nửa giờ cho trang này sẽ tiết kiệm nhiều ngày sửa lỗi ở giai đoạn code.

Sai lầm thường gặp

• Mục tiêu mơ hồ ("hỗ trợ khách hàng") — agent không biết đâu là xong.
• Không giới hạn scope — agent tự ý làm việc nhạy cảm như hoàn số tiền lớn.
• Quên đường fallback: gặp ca lạ, agent cố xử lý bừa thay vì bàn giao người thật.
• Bỏ dry run: nhảy vào code rồi mới phát hiện thiếu tool, phải đập đi làm lại.
• Chỉ dry-run ca thuận lợi, bỏ qua ca ngoại lệ — nơi agent thật sự dễ hỏng.

Bản thiết kế trên giấy đã xong. Bài 6 sẽ biến nó thành cấu hình/code agent chạy được.