12-factor agents là gì: 12 nguyên tắc xây AI agent chạy thật

Thử hình dung buổi demo agent chăm sóc khách hàng trước ban giám đốc. Năm câu hỏi mẫu, agent trả lời trơn tru, cả phòng vỗ tay. Tuần sau đưa cho khách thật: một khách hỏi lòng vòng mười câu, agent quên mất câu đầu, rồi tự tin hứa giảm giá 50%.

Demo đẹp và chạy thật là hai chuyện khác nhau. 12-factor agents là bộ nguyên tắc viết ra để lấp đúng khoảng cách đó.

Đọc nhanh trong 30 giây

12-factor agents là bộ 12 nguyên tắc thiết kế do Dex Horthy, người sáng lập HumanLayer, công bố ngày 03/04/2025 trên GitHub.

Mục tiêu: xây phần mềm dùng mô hình ngôn ngữ đủ ổn định để giao cho khách hàng thật.

Không phải thư viện để cài, mà là tài liệu đọc rồi áp vào code tự viết hoặc framework đang dùng.

Hợp với đội kỹ thuật đang chèn AI vào phần mềm có sẵn và trưởng nhóm cần khung rà soát agent.

12-factor agents là gì?

12-factor agents là bộ hướng dẫn thiết kế, đặt tên theo phương pháp 12 Factor App nổi tiếng trong giới làm web, viết dưới dạng tài liệu mở tại humanlayer/12-factor-agents. Anh chị đọc, đối chiếu với hệ thống của mình, rồi tự chọn nguyên tắc nào áp dụng.

Tác giả kể đã thử gần như mọi framework agent và nói chuyện với nhiều nhà sáng lập làm sản phẩm AI. Điều ông ngạc nhiên: phần lớn sản phẩm tự gọi là "AI agent" chủ yếu là code thông thường, chỉ chèn bước gọi mô hình ngôn ngữ ở đúng chỗ, và đa số đội tự viết thay vì dùng framework.

Ví von cho dễ hình dung: một nhà hàng không giao cả bếp cho một đầu bếp thiên tài làm gì tùy ý. Họ có quy trình cố định, chỉ để đầu bếp quyết ở vài khâu cần tay nghề. Agent tốt cũng vậy: phần lớn là phần mềm chạy theo luật, AI chỉ quyết ở chỗ cần.

Agent thật ra là một vòng lặp

Tài liệu mô tả agent cơ bản là một vòng lặp bốn bước:

Vòng lặp agent bốn bước và các điểm lập trình viên tự nắm quyền theo 12-factor agents

Vòng lặp cơ bản và những chỗ tài liệu khuyên anh chị tự cầm lái.

Mô hình chọn bước tiếp theo, trả về dạng JSON có cấu trúc (gọi là tool calling).
Code thông thường thực hiện bước đó.
Kết quả được thêm vào ngữ cảnh của mô hình.
Lặp lại tới khi mô hình báo xong.

Cách này hứa hẹn viết ít code hơn. Nhưng tác giả cho rằng ngữ cảnh càng dài, mô hình càng dễ lạc, giống agent ở đầu bài quên câu hỏi đầu tiên. Vì thế phần lớn nguyên tắc xoay quanh việc trả quyền kiểm soát về cho lập trình viên.

Như học lái xe: học viên cầm vô lăng, nhưng thầy ngồi ghế phụ có phanh riêng. AI được lái, còn chân phanh vẫn nằm ở phía code của anh chị.

12 nguyên tắc nói gì?

Danh sách đầy đủ theo README, tôi diễn giải lại bằng lời thường:

Bảng 12 nguyên tắc của 12-factor agents kèm giải thích ngắn bằng tiếng Việt

Mười hai nguyên tắc trên một trang, in ra dán cạnh bàn được.

#	Nguyên tắc	Hiểu nhanh
1	Natural Language to Tool Calls	Biến câu nói của người dùng thành lệnh có cấu trúc
2	Own your prompts	Tự viết và quản lý prompt, đừng phó mặc framework
3	Own your context window	Tự quyết đưa gì vào ngữ cảnh mô hình
4	Tools are just structured outputs	Công cụ chỉ là đầu ra JSON, code của anh chị mới thực thi
5	Unify execution state and business state	Gộp trạng thái chạy agent với dữ liệu nghiệp vụ
6	Launch/Pause/Resume with simple APIs	Khởi động, tạm dừng, chạy tiếp bằng API đơn giản
7	Contact humans with tool calls	Hỏi người thật cũng là một lệnh công cụ
8	Own your control flow	Tự viết luồng điều khiển của vòng lặp
9	Compact Errors into Context Window	Nén lỗi gọn rồi đưa lại cho mô hình tự sửa
10	Small, Focused Agents	Agent nhỏ, làm một việc
11	Trigger from anywhere	Gọi agent từ nơi người dùng đang làm việc
12	Make your agent a stateless reducer	Agent nhận trạng thái, trả trạng thái mới, không giữ gì riêng

Ngoài 12 điều chính, tài liệu thêm một mục phụ là lấy trước mọi ngữ cảnh có thể cần, và phần kết luận "mọi thứ đều là context engineering".

Ba nguyên tắc nên áp dụng ngay

Số 10, agent nhỏ. Tài liệu khuyên giữ mỗi agent trong khoảng 3 tới 10, cùng lắm 20 bước. Ít bước thì ngữ cảnh ngắn, dễ kiểm thử, dễ tìm lỗi.
Số 7, hỏi người thật bằng tool call. Khi cần xác nhận, agent trả về một ý định như request_human_input kèm câu hỏi, mức khẩn và các lựa chọn. Code của anh chị nhận ý định đó và gửi câu hỏi đi.
Số 8, tự nắm luồng điều khiển. Ví dụ trong tài liệu chia ba loại bước. Hỏi lại người dùng thì dừng vòng lặp chờ trả lời. Lấy danh sách git tag thì chạy luôn rồi đưa kết quả về. Deploy backend là việc rủi ro cao nên dừng chờ người duyệt.

Mẹo

Trước khi viết dòng code nào, lấy giấy vẽ quy trình và tô ba màu: bước AI cần quyết, bước code thường làm được, bước bắt buộc người duyệt. Thường anh chị sẽ thấy phần màu "AI quyết" nhỏ hơn mình tưởng.

Áp vào việc thật: duyệt đề nghị thanh toán

Việc 1: chia nhỏ một agent ôm đồm. Thay vì một agent lớn tự đọc hóa đơn, tự đối chiếu, tự chuyển khoản, anh chị chia ra: một agent nhỏ đọc hóa đơn ra JSON, code thường đối chiếu với đơn mua hàng, bước chuyển tiền luôn dừng lại để kế toán trưởng duyệt. Đó là nguyên tắc 7, 8 và 10 dùng cùng lúc.

So sánh một agent ôm hết việc thanh toán với cách chia agent nhỏ, code thường và người duyệt

Cùng quy trình thanh toán, hai cách thiết kế agent.

Việc 2: rà lại agent đang có. Dùng chính danh sách 12 điều làm phiếu kiểm tra. Ví dụ đưa cho AI prompt sau:

Đây là mô tả agent chăm sóc khách hàng của công ty tôi: [dán mô tả].
Đối chiếu với 12 nguyên tắc 12-factor agents của HumanLayer.
Với từng nguyên tắc, cho biết hệ thống đang đạt, chưa đạt hay không áp dụng, kèm một việc cần sửa.

Agent của anh chị dùng OpenAI thì bài OpenAI Agents SDK: hướng dẫn dùng multi-agent cho thấy cách một framework chia việc cho nhiều agent, để so với lời khuyên "agent nhỏ" ở đây.

Đọc 12-factor agents cần nhớ gì?

Lưu ý

Đây là bản nháp. Chính tác giả ghi tài liệu là tổng hợp sau một năm làm agent và có thể còn thay đổi.

Giấy phép. Tại ngày 03/04/2025, repo chưa có file LICENSE. Muốn chép nguyên văn nội dung vào tài liệu đào tạo nội bộ thì nên hỏi tác giả.

Không có code để cài. Anh chị vẫn phải tự viết hoặc chọn công cụ. Tài liệu chỉ giúp quyết định viết thế nào cho bền.

Nhận xét của chuyên gia

Tôi coi 12-factor agents là tài liệu nên đọc trước khi chọn framework agent, vì nó đặt đúng câu hỏi về độ tin cậy mà các bản demo hay bỏ qua. Rủi ro tôi gặp nhiều nhất khi tư vấn là doanh nghiệp muốn một agent làm hết mọi thứ. Nguyên tắc 10 là lời nhắc tốt để chia nhỏ ngay từ đầu.

Hợp với ai: đội kỹ thuật trong doanh nghiệp đang muốn chèn AI vào phần mềm có sẵn như CRM, ERP, hệ thống ticket; trưởng nhóm cần một khung để rà soát agent do đối tác bàn giao.

Chưa hợp với ai: doanh nghiệp chưa có người viết code. Các nguyên tắc nói về prompt, ngữ cảnh, luồng điều khiển, tức là cần lập trình viên hiểu hệ thống. Chỉ dùng ChatGPT hay công cụ kéo thả thì phần lớn nguyên tắc không áp được trực tiếp.

Cách bắt đầu của tôi: chọn một quy trình đang tốn thời gian, vẽ các bước, đánh dấu bước nào cần AI quyết, bước nào code thường làm được, bước nào bắt buộc người duyệt. Chỉ phần đầu mới giao cho agent.

Một câu để nhớ: agent chạy thật là phần mềm tốt có chút AI, không phải AI giỏi có chút phần mềm.

Câu hỏi thường gặp

12-factor agents có phải là framework không?

Không. 12-factor agents là tài liệu nguyên tắc thiết kế viết dạng Markdown trên GitHub, không có gói để cài. Anh chị áp dụng vào code tự viết hoặc framework đang dùng.

12-factor agents khác gì 12 Factor App?

12 Factor App là bộ nguyên tắc xây ứng dụng web chạy trên cloud. 12-factor agents mượn cách đặt tên và tinh thần đó, nhưng nội dung dành riêng cho phần mềm dùng mô hình ngôn ngữ.

Có cần biết lập trình để áp dụng 12-factor agents không?

Có, ở mức hiểu prompt, JSON và luồng xử lý. Người quản lý không viết code vẫn dùng được danh sách 12 điều làm phiếu hỏi khi nghiệm thu agent.

Xem thêm các mốc khác trong chuỗi dòng thời gian AI.

Nguồn: HumanLayer, 12 Factor Agents, 03/04/2025.