Bỏ qua tới nội dung
Ông T.vn

12-factor-agents: 12 nguyên tắc làm phần mềm LLM đủ tốt để dùng thật — hướng dẫn đọc và áp dụng

11 phút đọcCập nhật

Bài này là một góc nhìn khác về humanlayer/12-factor-agents — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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 →

12-factor-agents: 12 nguyên tắc làm phần mềm LLM đủ tốt để dùng thật — hướng dẫn đọc và áp dụng

Tóm tắt nhanh

12-factor-agents là một bộ tài liệu (không phải phần mềm cài về chạy) gồm 12 nguyên tắc giúp bạn xây ứng dụng dùng LLM đủ tin cậy để đưa cho khách hàng thật. Bạn chỉ cần tải repo về hoặc đọc trực tiếp trên GitHub, không cần cài gói hay có API key. Phần khó nhất không nằm ở cài đặt mà ở việc áp dụng từng nguyên tắc vào sản phẩm của bạn.

12-Factor Agents là một bộ nguyên tắc viết bằng tài liệu, trả lời một câu hỏi: làm sao xây phần mềm chạy bằng LLM mà đủ tốt để đưa cho khách hàng thật dùng. Tác giả đặt tên theo tinh thần "12 Factor Apps" nổi tiếng trong giới làm web. Repo này không phải một thư viện bạn cài rồi gọi hàm. Nó là một cuốn hướng dẫn mở, có thể góp ý và đóng góp trên GitHub.

Vấn đề tác giả gặp khá quen thuộc. Nhiều đội muốn thêm "agent" vào sản phẩm, chọn một framework có sẵn, làm nhanh tới mức 70-80% chất lượng rồi kẹt. Muốn vượt 80% thì phải mổ xẻ framework, prompt và luồng chạy bên trong, và nhiều đội cuối cùng làm lại từ đầu. Tác giả nói đã trò chuyện với ít nhất 100 người làm SaaS và thấy phần lớn sản phẩm gọi là "AI agent" thực chất chủ yếu là code thường, với vài bước LLM chèn đúng chỗ.

Repo hiện có khoảng 27.000 sao và 2.000 fork. Điểm đáng giá nhất là hướng đi thực tế: bạn không cần bỏ sản phẩm đang có để viết lại bằng một framework agent. Bạn lấy từng nguyên tắc nhỏ, độc lập, rồi áp vào hệ thống hiện tại. Ai nên đọc: lập trình viên mới, người làm sản phẩm, chủ doanh nghiệp có đội kỹ thuật muốn đưa AI vào quy trình mà không phụ thuộc hoàn toàn vào một framework.

Danh sách tuyển chọn

humanlayer/12-factor-agents

Bộ 12 nguyên tắc kỹ thuật để xây phần mềm dùng LLM đủ tin cậy cho khách hàng thật, viết theo tinh thần 12 Factor Apps. Hiện có khoảng 27.000 sao.

★ 27kTypeScript
Xem repo trên GitHub

I.12-Factor Agents làm được gì

Repo không chạy thay bạn việc gì cả. Giá trị của nó là một bộ khung tư duy gồm 12 "factor" (nguyên tắc), mỗi nguyên tắc có một file riêng trong thư mục content/. Dưới đây là ý chính của từng cái, theo cách hiểu thực tế.

  • Factor 1 - Natural Language to Tool Callsbiến câu nói tự nhiên thành lời gọi công cụ có cấu trúc. Nhờ vậy câu "tạo link thanh toán 750 đô cho khách" thành dữ liệu mà code của bạn xử lý được.
  • Factor 2 - Own your promptstự nắm prompt của mình thay vì để framework giấu đi. Bạn sửa được, thử được, kiểm soát được.
  • Factor 3 - Own your context windowtự quyết định đưa gì vào ngữ cảnh gửi cho LLM. README nhắc riêng nguyên tắc này cho ai quan tâm "context engineering".
  • Factor 4 - Tools are just structured outputscông cụ chỉ là đầu ra có cấu trúc của LLM, còn việc thực thi là code thường của bạn.
  • Factor 5 - Unify execution state and business stategộp trạng thái chạy của agent với trạng thái nghiệp vụ, đỡ phải quản lý hai nơi.
  • Factor 6 - Launch/Pause/Resume with simple APIsagent cần khởi động, tạm dừng, chạy tiếp qua API đơn giản.
  • Factor 7 - Contact humans with tool callshỏi con người cũng là một lời gọi công cụ, nên việc xin duyệt hay hỏi thêm thông tin trở thành bước bình thường.
  • Factor 8 - Own your control flowtự nắm luồng điều khiển, không giao toàn bộ cho vòng lặp của framework.
  • Factor 9 - Compact Errors into Context Windownén lỗi gọn lại trước khi đưa vào ngữ cảnh.
  • Factor 10 - Small, Focused Agentsagent nhỏ, tập trung một việc.
  • Factor 11 - Trigger from anywherecho phép kích hoạt agent từ nhiều nơi, gặp người dùng ở nơi họ đang ở.
  • Factor 12 - Make your agent a stateless reducercoi agent như hàm không giữ trạng thái riêng.

Ngoài ra có bài lịch sử phần mềm ("A Brief History of Software") để hiểu bối cảnh, và một mục bổ sung là Factor 13 về việc lấy sẵn mọi ngữ cảnh có thể cần (pre-fetch). Tác giả cũng nói rõ ví dụ chủ yếu viết bằng TypeScript, nhưng các ý tưởng áp dụng được cho Python hay ngôn ngữ khác.

II.Cần chuẩn bị gì

Vì đây là tài liệu, phần chuẩn bị rất nhẹ:

  • Một trình duyệt để đọc trực tiếp trên GitHub, hoặc Git nếu bạn muốn tải về máy.
  • Biết đọc tiếng Anh ở mức cơ bản. Tài liệu gốc bằng tiếng Anh. README chưa nói gì về bản dịch.
  • Kiến thức lập trình cơ bản sẽ giúp bạn hiểu ví dụ. Tác giả nói các khái niệm này có thể được áp dụng bởi kỹ sư phần mềm khá, không cần nền tảng AI.

README không yêu cầu hệ điều hành cụ thể, không nêu phiên bản Node hay Python, không cần tài khoản hay API key, không cần GPU để đọc tài liệu. Nếu sau này bạn thực hành theo các ví dụ trong thư mục workshops/ hoặc packages/, hãy đọc hướng dẫn riêng trong đó, vì README gốc chưa liệt kê yêu cầu cho phần đó.

III.Cài đặt từng bước

README chưa ghi cách cài đặt nào, vì repo là bộ tài liệu chứ không phải gói phần mềm. Bạn có hai cách dùng: đọc ngay trên GitHub, hoặc tải về máy để đọc offline và tìm kiếm nhanh. Phần dưới hướng dẫn cách tải về.

  1. Mở terminalMở PowerShell (Windows) hoặc Terminal (macOS/Linux) ở thư mục bạn muốn lưu
  2. Tải repoDùng git clone để lấy toàn bộ tài liệu về máy
  3. Vào thư mụcDùng cd để đứng trong thư mục repo
  4. Xem nội dungLiệt kê thư mục content để thấy các file factor
  5. Đọc theo thứ tựBắt đầu từ README rồi tới từng factor

A.Mở terminal đúng chỗ

Bạn cần Git đã cài trên máy. Mở terminal rồi đi tới thư mục bạn muốn lưu (ví dụ thư mục Documents). Người mới hay vấp ở đây: lệnh git clone sẽ tạo thư mục mới ngay tại nơi bạn đang đứng, nên hãy kiểm tra bạn đang ở đâu trước khi chạy.

B.Tải repo về máy

Lệnh dưới đây tải toàn bộ repo về một thư mục tên 12-factor-agents.

Terminal
git clone https://github.com/humanlayer/12-factor-agents.git

Nếu báo "git is not recognized" nghĩa là máy chưa cài Git. Bạn cài Git rồi mở lại terminal.

C.Vào thư mục repo

Terminal
cd 12-factor-agents

Lệnh cd chuyển terminal vào thư mục vừa tải. Từ giờ mọi lệnh sau sẽ chạy trong thư mục này.

D.Xem các file nội dung

Terminal
ls content

Thư mục content/ chứa các file Markdown của từng factor, như factor-03-own-your-context-window.md. Bạn mở bằng trình soạn thảo bất kỳ, hoặc đọc ngay trên GitHub cho dễ nhìn. Ngoài ra repo còn có các thư mục packages/, workshops/, hack/ và một file Makefile. README gốc chưa giải thích chúng dùng để làm gì, nên nếu cần hãy mở trực tiếp các file đó trong repo để xem.

E.Về công cụ create-12-factor-agent

README có nhắc tới npx/uvx create-12-factor-agent, nhưng chỉ ở dạng lời mời đóng góp qua một luồng thảo luận trên GitHub. README chưa ghi cách cài hay cách chạy công cụ này, nên mình không đưa lệnh nào ở đây. Bạn nên vào mục Discussions của repo để theo dõi tình hình.

Repo này chỉ là tài liệu. Bạn không cần nhập API key hay mật khẩu nào để đọc. Nếu một trang nào đòi bạn dán key vào chỗ lạ để "cài 12-factor-agents", hãy dừng lại.

IV.Kiểm tra đã chạy được chưa

Vì không có gì để "chạy", việc kiểm tra rất đơn giản:

  • Thư mục 12-factor-agents đã xuất hiện trên máy sau khi git clone.
  • Lệnh ls content in ra danh sách file Markdown của các factor.
  • Bạn mở được file README.md và thấy danh sách 12 factor cùng bài lịch sử phần mềm.

Nếu cả ba điều trên đúng thì bạn đã sẵn sàng. Cách tốt nhất để biết mình đã hiểu là thử diễn đạt lại vòng lặp agent trong README bằng lời của bạn. Đây là đoạn code mà README dùng để mô tả "agent là một vòng lặp" (README viết lẫn cú pháp, nên hãy coi nó là mã minh hoạ ý tưởng, đừng chép nguyên vào để chạy):

Python
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)

Ý nghĩa: ngữ cảnh ban đầu là một sự kiện (tin nhắn người dùng, cron, webhook...). LLM chọn bước tiếp theo dưới dạng JSON có cấu trúc. Code thường thực thi bước đó, kết quả được thêm vào ngữ cảnh, và vòng lặp lặp lại cho tới khi LLM báo "done". Hiểu được đoạn này là bạn đã nắm nền để đọc 12 factor.

V.Dùng vào việc thật

Phần này không phải lệnh chạy, mà là cách bạn đưa nguyên tắc vào công việc. Các ví dụ dưới đây là cách áp dụng, bám theo nội dung từng factor ở mức tên gọi và ý chính trong README.

A.Dev mới muốn thêm tính năng AI vào sản phẩm đang có

Bạn là lập trình viên ở một công ty nhỏ, sếp muốn "thêm AI" vào phần mềm quản lý đơn hàng. Cám dỗ là chọn một framework agent rồi viết lại cả luồng. Thay vào đó, hãy làm theo tinh thần README: chỉ lấy một khái niệm nhỏ, ví dụ Factor 1 và Factor 4, để biến yêu cầu bằng lời của nhân viên thành một lời gọi có cấu trúc, còn phần thực thi vẫn là code cũ của bạn. Kết quả: bạn có một tính năng AI hoạt động mà không phải đập đi xây lại.

Cách nhanh nhất để có phần mềm AI tốt trong tay khách hàng là lấy những khái niệm nhỏ, mô-đun hoá từ việc xây agent, rồi đưa vào sản phẩm sẵn có.

Ông T

B.Chủ doanh nghiệp đánh giá một giải pháp agent từ nhà cung cấp

Bạn không code, nhưng đang nghe một đơn vị chào giải pháp "AI agent". Bạn đọc phần "Why 12-factor agents?" và tự đặt câu hỏi cho họ. Prompt có sửa được không (Factor 2)? Khi agent cần duyệt thì có hỏi người thật không (Factor 7)? Tạm dừng và chạy tiếp được không (Factor 6)? Kết quả: bạn có danh sách câu hỏi cụ thể để phân biệt sản phẩm làm tử tế với sản phẩm chỉ có vẻ ngoài.

C.Nhân viên vận hành muốn agent biết hỏi ý kiến trước khi làm việc quan trọng

Đội bạn muốn một agent soạn email trả lời khách, nhưng không muốn nó tự gửi khi chưa ai xem. Factor 7 gợi ý coi việc liên hệ con người là một lời gọi công cụ, và Factor 6 cho phép tạm dừng rồi chạy tiếp qua API đơn giản. Bạn đưa hai ý này cho đội kỹ thuật làm tiêu chí. Kết quả: agent dừng ở bước cần duyệt, người có thẩm quyền bấm xác nhận, rồi quy trình đi tiếp.

D.Dev dùng làm checklist khi review code agent

Sau khi đã có một agent chạy tạm được, bạn mở từng factor như một danh sách kiểm tra. Ngữ cảnh gửi cho LLM có do mình kiểm soát không (Factor 3)? Lỗi có được nén gọn trước khi đưa lại cho LLM không (Factor 9)? Agent có đang ôm quá nhiều việc không (Factor 10)? Kết quả: bạn tìm ra chỗ yếu để sửa theo thứ tự ưu tiên, thay vì vá lung tung.

VI.Lỗi hay gặp và cách xử lý

Tìm lệnh cài mà không thấy. Đây là lỗi hiểu nhầm phổ biến nhất. Repo là tài liệu, không có lệnh cài gói. Bạn chỉ cần clone hoặc đọc trực tiếp trên GitHub.

git không nhận ra lệnh. Máy chưa cài Git hoặc terminal chưa nhận. Cài Git, đóng hẳn terminal rồi mở lại. Trong lúc chờ, bạn vẫn đọc được toàn bộ nội dung trên trình duyệt.

Clone xong nhưng không thấy thư mục. Có thể bạn đang đứng ở thư mục khác với dự tính. Chạy ls (hoặc dir trên Windows) để xem thư mục 12-factor-agents nằm ở đâu, rồi cd vào đúng chỗ.

Chép đoạn code trong README rồi chạy báo lỗi. Đoạn vòng lặp là mã minh hoạ ý tưởng, trộn cú pháp (ví dụ dùng === và await ở ngoài hàm), nên không chạy nguyên bản được. Hãy dùng nó để hiểu cấu trúc, rồi tự viết lại bằng ngôn ngữ và thư viện bạn đang dùng.

Đọc xong thấy khó áp dụng. Đừng cố làm cả 12 factor cùng lúc. README khuyên lấy từng khái niệm nhỏ. Hãy chọn một factor gần nhất với vấn đề bạn đang gặp, áp dụng, đo kết quả rồi mới sang cái tiếp theo.

VII.Có nên dùng không

Điểm mạnh. Tài liệu miễn phí, ngắn gọn từng factor, có động cơ rõ ràng: giúp bạn đưa AI vào sản phẩm thật mà không phải lệ thuộc framework. Tác giả cũng nói rõ họ không công kích các framework, chỉ muốn người xây dựng có thêm lựa chọn khi cần kiểm soát sâu. Với khoảng 27.000 sao, đây là một tài liệu được nhiều người quan tâm.

Giới hạn. Đây không phải công cụ dùng ngay. Bạn không nhận được ứng dụng chạy sẵn, và README chưa có cách cài hay hướng dẫn cho người không biết lập trình. Nội dung bằng tiếng Anh. Ví dụ chủ yếu dùng TypeScript. README cũng ghi là tác giả không bàn về MCP trong tài liệu này. Thông tin cập nhật cho thấy repo lâu rồi chưa có thay đổi mới, nên một số nhận định về hệ sinh thái AI có thể đã cũ so với hiện tại.

Giấy phép. Thông tin hệ thống không ghi rõ, nhưng README ghi nội dung và hình ảnh theo CC BY-SA 4.0, còn code theo Apache 2.0. Nếu bạn định dùng lại hoặc dịch nội dung, hãy đọc kỹ file LICENSE trong repo.

Khi nào chọn cách khác. Nếu bạn cần một công cụ cài và chạy ngay để làm một việc cụ thể (viết báo cáo, tự động hoá bảng tính), hãy tìm một repo dạng ứng dụng hoặc skill. Nếu bạn muốn một framework sẵn để thử ý tưởng nhanh, các framework agent vẫn hợp lý, miễn là bạn biết giới hạn của chúng khi lên môi trường thật. Còn nếu bạn là người đang xây sản phẩm có AI cho khách hàng và muốn hiểu vì sao nhiều dự án kẹt ở mức 80%, thì đây là tài liệu đáng đọc.

4.2/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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

12-factor-agents có miễn phí không?

Tài liệu công khai trên GitHub nên đọc và tải về không mất phí. README ghi nội dung theo giấy phép CC BY-SA 4.0 và code theo Apache 2.0. Muốn dùng lại hay dịch, bạn nên đọc kỹ file LICENSE trong repo.

Repo này có phải phần mềm để cài và chạy không?

Không. Đây là bộ nguyên tắc dạng tài liệu về cách xây ứng dụng dùng LLM. README không ghi lệnh cài gói nào. Bạn chỉ cần đọc trên GitHub hoặc clone về máy.

Có cần GPU hay API key không?

Để đọc tài liệu thì không. README không yêu cầu GPU, tài khoản hay API key. Nếu bạn làm theo các ví dụ hoặc workshop trong repo, hãy xem hướng dẫn riêng ở đó vì README gốc chưa liệt kê yêu cầu.

Dùng được trên Windows không?

Đọc tài liệu thì dùng được trên mọi hệ điều hành, kể cả Windows, vì chỉ là file Markdown và trang GitHub. Lệnh git clone cũng chạy được trong PowerShell nếu máy đã có Git. README chưa nói gì về yêu cầu hệ điều hành cho các phần code.

12-factor-agents khác gì các framework agent như LangChain?

Theo tác giả, repo không phải framework mà là các nguyên tắc để bạn tự áp dụng vào sản phẩm sẵn có. Tác giả nói đã thử nhiều framework và thấy khó vượt mức 80% chất lượng khi dùng cho tính năng hướng tới khách hàng. Ý của repo là lấy từng khái niệm nhỏ thay vì viết lại tất cả bằng một framework.

Tôi không biết lập trình thì đọc được không?

Bạn đọc được phần ý tưởng, nhất là phần lý do vì sao nhiều dự án agent kẹt chất lượng. Tuy vậy, ví dụ trong repo chủ yếu là code TypeScript và nội dung bằng tiếng Anh. README chưa có bản dành riêng cho người không rành kỹ thuật.

Repo có còn được cập nhật không?

Thông tin hiện có cho biết repo lâu rồi chưa cập nhật. README vẫn mời đóng góp và góp ý qua GitHub. Bạn nên xem lịch sử commit và mục Discussions để biết tình hình mới nhất.

Chuyển nhanh tới mục

  1. I.12-Factor Agents làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Mở terminal đúng chỗ
    2. B.Tải repo về máy
    3. C.Vào thư mục repo
    4. D.Xem các file nội dung
    5. E.Về công cụ create-12-factor-agent
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev mới muốn thêm tính năng AI vào sản phẩm đang có
    2. B.Chủ doanh nghiệp đánh giá một giải pháp agent từ nhà cung cấp
    3. C.Nhân viên vận hành muốn agent biết hỏi ý kiến trước khi làm việc quan trọng
    4. D.Dev dùng làm checklist khi review code agent
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.