12-factor-agents: 12 nguyên tắc xây agent AI đủ tin cậy — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
12-factor-agents là một bộ tài liệu mã nguồn mở của Dex (HumanLayer), tóm tắt 12 nguyên tắc để xây phần mềm chạy bằng mô hình ngôn ngữ lớn (LLM) đủ tin cậy cho khách hàng thật. Đây là hướng dẫn thiết kế để đọc, không phải công cụ để cài. Bạn chỉ cần tải repo về hoặc đọc trực tiếp trên GitHub, nên gần như không có độ khó về cài đặt.
12-factor-agents là một bộ tài liệu mã nguồn mở, tóm tắt 12 nguyên tắc để xây phần mềm chạy bằng mô hình ngôn ngữ lớn (LLM) đủ tốt để đưa cho khách hàng thật dùng. Nó không phải một framework hay một lệnh bạn cài vào máy. Nó là một cuốn "sổ tay thiết kế", lấy cảm hứng từ bộ nguyên tắc 12 Factor Apps nổi tiếng trong thế giới phần mềm web.
Tác giả là Dex, người sáng lập HumanLayer. Anh kể mình đã thử gần như mọi framework agent hiện có. Anh cũng nói chuyện với nhiều founder đang làm sản phẩm AI. Phần lớn những người này tự dựng hệ thống chứ không dùng framework. Lý do: framework giúp đạt khoảng 70-80% chất lượng rất nhanh, nhưng muốn vượt mốc đó thì phải đào ngược vào prompt và luồng chạy bên trong, và nhiều đội đành làm lại từ đầu.
Ai nên đọc? Lập trình viên đang làm chatbot hoặc trợ lý AI cho sản phẩm có sẵn, người quản lý sản phẩm cần hiểu "agent tốt" nghĩa là gì, và bạn nào mới vào nghề muốn tránh những lỗi thiết kế phổ biến. Điểm đáng giá nhất: repo nói thẳng rằng các sản phẩm AI tốt thường là phần mềm bình thường, chỉ chèn bước LLM vào đúng chỗ. Hiện repo có khoảng 27135 sao và 2048 fork.
humanlayer/12-factor-agents
Bộ 12 nguyên tắc xây phần mềm dùng LLM đủ tốt để đưa cho khách hàng thật, viết dưới dạng tài liệu đọc được ngay, không cần cài đặt.
I.12-factor-agents làm được gì
Vì là tài liệu, "làm được gì" ở đây nghĩa là "dạy bạn được gì". Repo gồm một bài mở đầu về lịch sử phần mềm, 12 nguyên tắc (factor) và một phần phụ lục. Mỗi nguyên tắc nằm trong một file Markdown riêng.
- Biến câu chữ thành lệnh gọi công cụ (factor 1). Ý chính: LLM đọc yêu cầu bằng ngôn ngữ tự nhiên rồi xuất ra dữ liệu có cấu trúc, còn code thường của bạn mới là bên thực thi. Nhờ vậy bạn kiểm soát được cái gì thật sự chạy.
- Tự nắm prompt và context (factor 2, 3). Đừng giao hẳn prompt và nội dung đưa vào cửa sổ ngữ cảnh cho thư viện bên ngoài. Tự quản lý thì bạn chỉnh được chất lượng đầu ra. README còn chỉ riêng factor 3 cho ai quan tâm "context engineering".
- Công cụ chỉ là dữ liệu có cấu trúc (factor 4). Gọi "công cụ" nghe phức tạp, nhưng bản chất là LLM trả về một khối dữ liệu theo khuôn, rồi code của bạn quyết định làm gì tiếp.
- Thống nhất trạng thái chạy và trạng thái nghiệp vụ (factor 5). Giúp bạn không phải quản lý hai nơi lưu thông tin khác nhau.
- Khởi chạy, tạm dừng, chạy tiếp bằng API đơn giản (factor 6). Phù hợp các việc dài hơi, cần chờ người duyệt.
- Liên hệ con người bằng chính lệnh gọi công cụ (factor 7). Khi agent cần hỏi ý kiến hay xin duyệt, đó cũng chỉ là một bước như mọi bước khác.
- Tự nắm luồng điều khiển (factor 8). Bạn quyết định khi nào lặp, khi nào dừng, khi nào chờ.
- Nén lỗi vào cửa sổ ngữ cảnh (factor 9). Lỗi xảy ra thì đưa phần gọn, đủ ý cho LLM để nó tự sửa.
- Agent nhỏ, tập trung (factor 10). Nhiều agent nhỏ làm đúng một việc thường dễ quản hơn một agent làm tất cả.
- Kích hoạt từ mọi nơi (factor 11). Gặp người dùng ở nơi họ đang có mặt.
- Agent là một "stateless reducer" (factor 12). Mỗi lượt chạy nhận trạng thái cũ và sự kiện mới, trả ra trạng thái mới.
- Factor 13 (phụ lục). Lấy trước mọi ngữ cảnh có thể cần (pre-fetch).
Ngoài ra repo có thư mục workshops/, packages/, hack/ và drafts/. README không giải thích các thư mục này, nên bạn mở ra xem tự do nếu cần.
II.Cần chuẩn bị gì
Tư liệu không nêu yêu cầu cài đặt nào, vì đây chủ yếu là tài liệu đọc. Cụ thể:
- Không có yêu cầu hệ điều hành, phiên bản Node hay Python nào được ghi trong README.
- Không cần API key, tài khoản hay phần cứng đặc biệt để đọc.
- Để tải về, bạn cần Git trên máy. Nếu không muốn cài Git, bạn có thể đọc trực tiếp trên trang GitHub của repo.
- Ngôn ngữ chính của repo là TypeScript. Tác giả nói các ý tưởng này áp dụng được trong Python hoặc ngôn ngữ nào bạn thích. Vì vậy dù bạn không dùng TypeScript, nội dung vẫn dùng được.
Nếu bạn muốn thử code thực hành trong repo (ví dụ ở workshops/ hay packages/), README chưa nói rõ cần gì. Bạn xem file hướng dẫn trong từng thư mục đó, hoặc Makefile ở gốc repo.
Đọc tài liệu thì không tốn phí và không cần key nào. Nhưng nếu sau này bạn tự dựng agent theo các nguyên tắc này và gọi dịch vụ LLM, chi phí và API key là chuyện riêng của dịch vụ bạn chọn. Đừng dán key vào code rồi đưa lên GitHub công khai.
III.Cài đặt từng bước
README chưa ghi cách cài, vì repo là tài liệu chứ không phải phần mềm. "Cài" ở đây thực chất là tải về và đọc. Bạn làm theo các bước sau:
- Mở terminalMở PowerShell (Windows) hoặc Terminal (Mac/Linux) ở thư mục bạn muốn lưu
- Tải repoDùng git clone để lấy toàn bộ tài liệu về máy
- Vào thư mụcDùng cd để đi vào thư mục vừa tải
- Xem mục lụcMở README.md để thấy danh sách 12 nguyên tắc
- Đọc từng factorMở các file trong thư mục content theo thứ tự
A.Mở terminal đúng chỗ
Trên Windows, bấm phím Windows, gõ "PowerShell" rồi Enter. Trên Mac, mở ứng dụng Terminal. Chọn một thư mục dễ nhớ, ví dụ thư mục Documents của bạn. Người mới hay quên bước này nên tải xong không biết file nằm đâu.
B.Tải repo về máy
Lệnh dưới đây sao chép toàn bộ repo từ GitHub về máy bạn, vào một thư mục mới tên 12-factor-agents.
git clone https://github.com/humanlayer/12-factor-agents.gitNếu máy báo không nhận ra lệnh git, nghĩa là bạn chưa cài Git. Khi đó cài Git rồi mở lại terminal, hoặc bỏ qua bước này và đọc thẳng trên trang GitHub.
C.Đi vào thư mục vừa tải
cd 12-factor-agentsLệnh này đưa terminal vào bên trong thư mục repo. Từ đây bạn thấy các mục như README.md, content/, workshops/.
D.Xem mục lục và các file nội dung
Mở README.md bằng trình soạn thảo bất kỳ (Notepad, VS Code…). Phần đầu có danh sách 12 factor. Nội dung chi tiết nằm trong thư mục content/. Để xem danh sách file trong thư mục này:
Get-ChildItem contentTrên Mac/Linux dùng ls content. Các file có tên theo mẫu như factor-03-own-your-context-window.md, nên bạn dễ tìm đúng factor mình cần. Đọc được bằng bất kỳ trình xem Markdown nào, hoặc xem trên GitHub cho đẹp hơn.
E.Muốn thử code mẫu thì sao?
README không có lệnh chạy code. Repo có một Makefile ở gốc, nhưng tư liệu không nói nó chạy những gì, nên mình không đoán. Bạn mở file đó và các thư mục workshops/, packages/ để xem hướng dẫn riêng nếu có. README cũng nhắc có một thảo luận về công cụ create-12-factor-agent (chạy bằng npx hoặc uvx) đang được bàn trong mục Discussions của repo. Đây là hướng đang phát triển, chưa phải thứ README hướng dẫn dùng ngay.
IV.Kiểm tra đã chạy được chưa
Vì không có phần mềm để chạy, "thành công" ở đây đơn giản hơn:
- Sau
git clone, trong thư mục hiện tại có thư mục12-factor-agents. - Sau
cd 12-factor-agents, bạn thấy các mục nhưREADME.md,content,workshops. - Mở
README.mdra đọc được danh sách 12 factor, và mở được file trongcontent/.
Nếu cả ba điều trên đúng, bạn đã "cài" xong. Phần còn lại là đọc và áp dụng.
V.Dùng vào việc thật
Tài liệu này có giá trị khi bạn mang nó vào công việc. Dưới đây là vài cách dùng cụ thể.
A.Dev kiểm tra lại vòng lặp agent đang có
Bối cảnh: bạn là lập trình viên đang làm chatbot hỗ trợ khách cho công ty, chạy tạm ổn nhưng thỉnh thoảng "đi lạc". README mô tả agent cơ bản là một vòng lặp: LLM chọn bước tiếp theo, code chạy bước đó, kết quả được thêm vào ngữ cảnh, lặp cho đến khi xong. Đoạn mã mô tả trong README (là giả mã minh họa) như sau:
initial_event = {"message": "..."}
context = [initial_event]
while True:
next_step = await llm.determine_next_step(context)
context.append(next_step)
if (next_step.intent === "done"):
return next_step.final_answer
result = await execute_step(next_step)
context.append(result)Bạn so vòng lặp này với code của mình rồi đọc factor 3 (tự nắm cửa sổ ngữ cảnh), factor 8 (tự nắm luồng điều khiển) và factor 9 (nén lỗi). Kết quả: bạn biết chỗ nào đang giao hẳn cho thư viện, chỗ nào nên tự cầm lại.
Agent tốt phần lớn chỉ là phần mềm bình thường, có chèn bước LLM đúng chỗ.
Ông T
B.Nhờ chính AI đọc giúp và góp ý cho dự án của bạn
Bối cảnh: bạn không rành kỹ thuật sâu nhưng muốn biết sản phẩm AI của đội mình có "đạt chuẩn" không. Bạn mở một file factor, dán vào công cụ AI bạn quen dùng, kèm mô tả quy trình hiện tại. Prompt mẫu:
Đây là một nguyên tắc về xây agent AI: [dán nội dung file factor].
Đây là quy trình chatbot của mình: [mô tả 5-10 dòng].
Hãy chỉ ra chỗ nào quy trình của mình chưa theo nguyên tắc này và đề xuất cách sửa nhỏ nhất.Kết quả: một danh sách chỗ cần cải thiện, bám sát từng nguyên tắc. Lưu ý đây là gợi ý để bạn xem xét, không phải kết luận chắc chắn.
C.Quản lý sản phẩm dùng 12 factor làm danh sách kiểm tra
Bối cảnh: bạn là quản lý sản phẩm, nhà cung cấp đề xuất "agent tự động làm hết". Bạn lấy tên 12 factor làm bảng câu hỏi: ai nắm prompt, ai nắm luồng điều khiển, khi lỗi thì xử lý ra sao, khi cần người duyệt thì gọi người bằng cách nào (factor 7), agent tạm dừng và chạy tiếp được không (factor 6). Kết quả: bạn đặt được câu hỏi đúng và nhận ra sớm giải pháp nào chỉ là demo đẹp.
D.Đội nhỏ chia nhau đọc rồi chọn điều áp dụng trước
Bối cảnh: đội 3-4 người đang thêm tính năng AI vào sản phẩm có sẵn. Mỗi người đọc 3 factor, trình bày ngắn, rồi cả đội chọn 1-2 nguyên tắc dễ làm nhất để áp dụng vào tuần sau. Tác giả cũng khuyên làm theo hướng này: lấy các khái niệm nhỏ, độc lập rồi đưa vào sản phẩm sẵn có, thay vì viết lại toàn bộ bằng một framework mới. Kết quả: cải thiện từng chút mà không phải làm lại từ đầu.
VI.Lỗi hay gặp và cách xử lý
A.Máy báo không nhận ra lệnh git
Bạn chưa cài Git hoặc terminal được mở trước khi cài. Cài Git, đóng terminal, mở lại rồi chạy lại lệnh git clone. Cách khác là xem trực tiếp trên trang GitHub, không cần Git.
B.Tải về nhưng không biết file ở đâu
Thư mục 12-factor-agents được tạo ở nơi terminal đang đứng lúc bạn chạy git clone. Lần sau hãy cd vào thư mục bạn muốn trước khi tải. Muốn biết đang ở đâu, trong PowerShell gõ pwd.
C.Tìm thấy file nhưng đọc ra toàn ký tự lạ
File .md là Markdown, mở bằng Notepad vẫn đọc được nhưng hơi lộn xộn. Mở bằng VS Code (có xem trước Markdown) hoặc xem trên GitHub sẽ dễ đọc hơn.
D.Đọc xong vẫn không biết bắt đầu từ đâu
Đây là lỗi rất hay gặp với loại tài liệu nguyên tắc. Đừng đọc hết một lượt. Chọn một vấn đề đang gặp: nếu chất lượng đầu ra không ổn định, xem factor 2, 3 và 9. Nếu cần người duyệt, xem factor 6 và 7. Áp dụng một điều rồi mới đọc tiếp.
E.Tìm cách chạy mà không thấy lệnh cài
Đúng là README không có. Đây là tài liệu, không phải gói để cài bằng npm hay pip. Nếu bạn cần code thực hành, xem thư mục workshops/ và packages/ hoặc theo dõi thảo luận về create-12-factor-agent trong mục Discussions của repo.
VII.Có nên dùng không
Điểm mạnh: nội dung miễn phí, ngắn gọn từng factor, có lý lẽ rõ ràng, và tác giả nói thẳng rằng đây không phải chê các framework mà là kinh nghiệm để làm tốt hơn. Ý tưởng áp dụng được cho nhiều ngôn ngữ, không bị gắn vào một công cụ cụ thể. Theo README, nội dung và hình ảnh dùng giấy phép CC BY-SA 4.0, còn code dùng giấy phép Apache 2.0.
Giới hạn: đây là tài liệu về nguyên tắc, không có nút bấm để chạy ngay. Bạn cần biết lập trình ở mức nào đó để áp dụng. Ví dụ trong repo thiên về TypeScript. README cũng không nói về MCP, và các trang tham khảo bên ngoài của repo có thể đã cũ. Cần lưu ý repo đã lâu chưa được cập nhật, nên hãy đọc như một bộ tư tưởng thiết kế chứ không phải tài liệu kỹ thuật mới nhất về từng công cụ.
Khi nào nên chọn cách khác: nếu bạn chỉ muốn một công cụ làm việc ngay không cần viết code, hãy tìm ứng dụng hoặc nền tảng agent có sẵn. Nếu bạn muốn một framework trọn gói để chạy thử nhanh, repo này không cung cấp. Còn nếu bạn đang xây sản phẩm AI cho khách thật và muốn tránh bẫy "đạt 80% rồi kẹt", thì đây là tài liệu đáng đọc trước khi chọn kiến trúc.
Câu hỏi thường gặp
12-factor-agents có miễn phí không?
Có. Đây là repo công khai trên GitHub, bạn đọc hoặc tải về không mất phí. README ghi nội dung và hình ảnh dùng giấy phép CC BY-SA 4.0, còn code dùng Apache 2.0.
Có phải cài phần mềm hay cần GPU không?
Để đọc tài liệu thì không cần cài phần mềm nào ngoài Git (nếu muốn tải về) và không cần GPU. README không nêu yêu cầu phần cứng. Với phần code mẫu ở các thư mục khác, tư liệu hiện chưa có thông tin về yêu cầu.
Chạy trên Windows được không?
Đọc tài liệu thì được, vì chỉ là file Markdown. Lệnh git clone chạy trong PowerShell trên Windows bình thường. README không nói gì thêm về hệ điều hành cho phần code.
Repo này khác gì một framework agent như LangChain?
Nó không phải framework. Tác giả cho rằng nhiều framework giúp đạt khoảng 70-80% chất lượng nhanh nhưng khó vượt xa hơn vì phải đào vào bên trong. Repo đưa ra các nguyên tắc nhỏ, độc lập để bạn áp dụng vào sản phẩm sẵn có.
Tôi không biết TypeScript thì có dùng được không?
Được. Tác giả dùng TypeScript là chính nhưng nói rõ các ý tưởng này áp dụng được trong Python hoặc bất kỳ ngôn ngữ nào. Phần lớn nội dung là cách thiết kế, không phụ thuộc ngôn ngữ.
Dữ liệu của tôi có an toàn không?
Repo chỉ là tài liệu nên bạn không đưa dữ liệu nào vào đó. Khi bạn tự dựng agent theo nguyên tắc và gọi dịch vụ LLM, mức an toàn phụ thuộc vào dịch vụ bạn chọn. Tư liệu của repo chưa có thông tin riêng về chuyện này.
Repo còn được cập nhật không?
Theo thông tin hiện có, repo đã lâu chưa được cập nhật. Nội dung nguyên tắc vẫn đọc được, nhưng các link tham khảo bên ngoài có thể đã cũ.


