humanlayer/12-factor-agents: xây agent đáng tin — hướng dẫn cài đặt và dùng
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 →

Tóm tắt nhanh
humanlayer/12-factor-agents là một bộ hướng dẫn và nguyên tắc thiết kế ứng dụng LLM, tập trung vào prompt, context, tool call, trạng thái và luồng điều khiển. Repo phù hợp cho dev muốn xây agent có chất lượng sản phẩm thay vì chỉ ghép framework. Đây chủ yếu là tài liệu TypeScript-oriented, chưa phải gói cài đặt chạy ngay.
humanlayer/12-factor-agents là một bộ nguyên tắc để xây ứng dụng LLM và AI agent đủ đáng tin khi đưa cho người dùng thật. Repo không tập trung vào một framework duy nhất. Thay vào đó, repo hướng dẫn bạn chia nhỏ các phần quan trọng như prompt, context window, tool call, trạng thái và luồng điều khiển để tự kiểm soát tốt hơn.
Repo phù hợp với lập trình viên đang xây chatbot có hành động, trợ lý nội bộ, quy trình tự động hóa hoặc tính năng AI trong sản phẩm hiện có. Người mới học agent cũng có thể đọc theo từng factor. Điểm đáng giá nhất là cách tiếp cận thực tế: dùng những thành phần nhỏ, rõ ràng trong hệ thống hiện tại thay vì phụ thuộc hoàn toàn vào một framework lớn.
Repo hiện có khoảng 27.144 sao và 2.048 fork. Ngôn ngữ chính là TypeScript. Tuy nhiên, README chủ yếu là tài liệu và ví dụ thiết kế; chưa có hướng dẫn cài đặt một ứng dụng hoàn chỉnh để chạy ngay.
humanlayer/12-factor-agents
Bộ nguyên tắc giúp xây ứng dụng LLM và agent đáng tin, dễ kiểm soát, phù hợp môi trường sản phẩm thật.
I.12-factor-agents làm được gì
A.Giải thích cách agent thực sự hoạt động
README mô tả vòng lặp cơ bản của agent: mô hình nhận context, quyết định bước tiếp theo bằng structured output hoặc tool call, code chạy công cụ, kết quả được đưa lại vào context rồi quy trình lặp lại. Cách giải thích này giúp bạn hiểu phần nào nên giao cho LLM và phần nào nên giữ bằng code xác định.
Đây là nền tảng quan trọng khi bạn muốn tránh tình trạng agent tự do quá mức, khó đoán và khó kiểm thử.
B.Chuyển ngôn ngữ tự nhiên thành tool call
Factor đầu tiên tập trung vào việc để LLM biến yêu cầu của người dùng thành lời gọi công cụ có cấu trúc. Ví dụ, một câu hỏi của khách hàng có thể được chuyển thành thao tác tìm đơn hàng, kiểm tra tồn kho hoặc tạo yêu cầu hỗ trợ.
Lợi ích thực tế là phần code phía sau nhận được dữ liệu có cấu trúc thay vì phải đoán ý từ một đoạn văn tự do. Bạn cũng dễ xác thực tham số và giới hạn quyền của từng công cụ.
C.Tự quản lý prompt và context window
Repo khuyến khích bạn sở hữu prompt và tự quyết định context nào được đưa vào mỗi lần gọi mô hình. Bạn không nên phó mặc toàn bộ việc này cho framework.
Với cách làm đó, đội phát triển có thể biết chính xác prompt nào đang chạy, dữ liệu nào được gửi đi, phần nào cần cắt bớt và thông tin nào cần giữ lại. Điều này đặc biệt hữu ích khi agent phải làm việc qua nhiều bước hoặc xử lý dữ liệu dài.
D.Xem tool như structured output
Một tool call về bản chất là kết quả có cấu trúc mà mô hình tạo ra. Từ góc nhìn này, bạn có thể thiết kế schema, kiểm tra dữ liệu đầu vào và xử lý lỗi giống như với các API thông thường.
Cách tiếp cận này giúp giảm sự phụ thuộc vào “phép màu” của framework. Tool trở thành một hợp đồng rõ ràng giữa mô hình và chương trình.
E.Đồng bộ trạng thái thực thi với trạng thái nghiệp vụ
Agent thường có hai loại trạng thái: trạng thái đang chạy đến bước nào và trạng thái nghiệp vụ như đơn hàng đã được duyệt hay chưa. Repo đề xuất nhìn hai loại trạng thái này cùng nhau.
Khi làm vậy, hệ thống dễ tiếp tục sau khi bị gián đoạn, dễ hiển thị tiến trình cho người dùng và ít gặp lỗi do trạng thái agent không khớp với dữ liệu thật.
F.Tạm dừng, tiếp tục và liên hệ con người
Một agent dùng trong sản phẩm thật không phải lúc nào cũng nên tự quyết định. Một số bước cần người duyệt, xác nhận hoặc bổ sung thông tin.
Các factor về launch, pause, resume và contact humans with tools mô tả cách thiết kế API đơn giản cho những tình huống này. Agent có thể tạm dừng, gửi yêu cầu cho người phụ trách rồi tiếp tục khi nhận được phản hồi.
G.Tự sở hữu control flow
README cảnh báo rằng việc giao toàn bộ luồng điều khiển cho agent có thể khiến hệ thống khó kiểm soát. Bạn nên giữ các quyết định quan trọng, điều kiện dừng, giới hạn thử lại và các nhánh nghiệp vụ bằng code khi cần.
Điều này giúp sản phẩm có hành vi ổn định hơn, nhất là ở những bước liên quan đến tiền, quyền truy cập hoặc dữ liệu khách hàng.
H.Thu gọn lỗi thành context hữu ích
Khi một tool thất bại, agent cần nhận được thông tin lỗi đủ rõ để sửa hoặc chọn hướng khác. Factor 9 nói về việc đưa lỗi trở lại context theo cách ngắn gọn và có ích.
Thay vì đẩy cả stack trace dài cho mô hình, bạn có thể chuyển lỗi thành thông tin như thao tác nào thất bại, nguyên nhân có thể là gì và bước tiếp theo được phép làm gì.
I.Thiết kế agent nhỏ và tập trung
Repo khuyến nghị các agent nhỏ, mỗi agent có phạm vi rõ ràng. Một agent chuyên phân loại yêu cầu, một agent tìm dữ liệu và một agent soạn câu trả lời thường dễ kiểm thử hơn một agent làm mọi việc.
Cách chia này cũng giúp giới hạn prompt, giảm số tool phải cung cấp và dễ thay đổi từng phần khi chất lượng chưa đạt.
J.Kích hoạt từ nhiều nơi
Factor 11 đề cập việc agent có thể được kích hoạt từ nhiều nguồn như tin nhắn người dùng, cron, webhook hoặc một sự kiện trong hệ thống. Phần xử lý cốt lõi nên tách khỏi giao diện kích hoạt.
Nhờ đó, cùng một năng lực có thể dùng trong giao diện chat, quy trình nền hoặc một endpoint nội bộ mà không phải viết lại toàn bộ logic.
K.Mô hình hóa agent như stateless reducer
Factor cuối đề xuất xem agent như một hàm nhận trạng thái và sự kiện rồi tạo ra trạng thái mới. Cách này làm cho hành vi dễ ghi lại, phát lại và kiểm thử hơn.
Bạn có thể lưu các sự kiện, kiểm tra từng lần chuyển trạng thái và khôi phục quy trình khi cần. Đây là tư duy hữu ích cho hệ thống cần audit hoặc xử lý lâu.
II.Cần chuẩn bị gì
Tư liệu được cung cấp không ghi yêu cầu hệ điều hành cụ thể, phiên bản Node.js, phiên bản Python, cơ sở dữ liệu, API key hay phần cứng GPU. README nói tác giả dùng chủ yếu TypeScript, nhưng các ý tưởng có thể áp dụng bằng Python hoặc ngôn ngữ khác.
Repo có cấu trúc gồm README.md, Makefile, thư mục content/, drafts/, hack/, img/, packages/ và workshops/. README không nêu rõ lệnh cài đặt dependency hoặc lệnh chạy ứng dụng. Vì vậy, bạn nên xem Makefile, các file khai báo package trong packages/ và từng workshop để biết yêu cầu cụ thể của phần mình muốn dùng.
Bạn cần có Git nếu muốn tải repo về. Đây là yêu cầu phổ thông để lấy mã nguồn, không phải yêu cầu riêng được README mô tả cho một chương trình chạy agent.
Nếu bạn triển khai một agent dựa trên các nguyên tắc này, hệ thống thực tế có thể cần API key của nhà cung cấp LLM. Tuy nhiên, README được cung cấp không chỉ định nhà cung cấp, tên biến môi trường hay cách lưu key. Không nên tự đoán tên key từ tài liệu này.
III.Cài đặt từng bước
- Tải mã nguồnClone repo về máy để đọc tài liệu và ví dụ
- Mở thư mục repoĐi vào thư mục vừa tải
- Xem cấu trúc dự ánKiểm tra README, Makefile, packages và workshops
- Chọn phần cần dùngĐọc factor hoặc workshop phù hợp với bài toán
- Kiểm tra hướng dẫn riêngChỉ cài dependency khi file tương ứng ghi rõ
A.Tải mã nguồn
Mở Terminal, PowerShell hoặc cửa sổ dòng lệnh tại thư mục bạn muốn lưu dự án. Chạy lệnh clone phổ thông sau:
git clone https://github.com/humanlayer/12-factor-agents.gitLệnh này tạo một thư mục chứa mã nguồn repo. Nếu máy báo không nhận diện git, bạn cần cài Git trước hoặc dùng một công cụ quản lý mã nguồn có hỗ trợ clone.
B.Mở thư mục repo
Sau khi clone xong, đi vào thư mục dự án:
cd 12-factor-agentsBạn cần chạy lệnh này trong đúng thư mục mà lệnh git clone vừa tạo. Người mới thường gặp lỗi vì mở PowerShell ở thư mục khác hoặc gõ sai tên thư mục.
C.Xem tài liệu chính
Mở README.md bằng trình soạn thảo văn bản. Đây là nơi trình bày mục tiêu, vòng lặp agent và danh sách 12 factor. Các bài chi tiết nằm trong thư mục content/.
README không cung cấp lệnh npm install, pnpm install, yarn, pip install hoặc lệnh khởi động ứng dụng. Vì vậy, không nên tự chạy một lệnh cài đặt chỉ vì thấy repo có TypeScript.
D.Kiểm tra Makefile và các gói
Repo có file Makefile, nhưng nội dung Makefile không nằm trong tư liệu được cung cấp. Hãy mở file này để xem nó có các mục tiêu nào. Nếu muốn đọc nhanh trên PowerShell, bạn có thể dùng lệnh phổ thông:
Get-Content MakefileNếu bạn muốn làm việc với phần mã trong packages/, hãy mở file khai báo package bên trong thư mục đó. Chỉ dùng đúng lệnh, phiên bản runtime và biến môi trường được ghi trong file tương ứng. README hiện chưa ghi quy trình cài đặt hoàn chỉnh cho toàn repo.
E.Chọn factor để áp dụng
Bạn không cần cài toàn bộ repo để hiểu phương pháp. Có thể bắt đầu bằng các file trong content/, nhất là các phần về prompt, context window, tool call, control flow và stateless reducer.
Nếu bạn đang xây tính năng AI trong sản phẩm có sẵn, hãy chọn một vấn đề cụ thể trước. Ví dụ, bạn có thể bắt đầu bằng việc tách tool call khỏi prompt hoặc lưu trạng thái thực thi cùng trạng thái nghiệp vụ.
IV.Kiểm tra đã chạy được chưa
Repo này chủ yếu là tài liệu và mã nguồn tham khảo, nên “chạy được” không giống một CLI hay ứng dụng có màn hình khởi động. Kiểm tra đầu tiên là clone thành công và thấy các thành phần như README.md, Makefile, content/, packages/ và workshops/.
Sau đó, mở README và xác nhận bạn đọc được phần “The Short Version: The 12 Factors”. Bạn cũng nên thấy ví dụ vòng lặp Python có các bước nhận context, gọi LLM, kiểm tra ý định done, thực thi bước và thêm kết quả vào context.
Nếu bạn định chạy một package hoặc workshop cụ thể, kết quả mong đợi phải lấy từ README hoặc file hướng dẫn của chính package đó. Tư liệu hiện có không nêu màn hình, URL, lệnh khởi động hay output cụ thể cho một ứng dụng hoàn chỉnh.
V.Dùng vào việc thật
A.Chủ shop muốn trợ lý tra đơn hàng
Một chủ shop có thể dùng các nguyên tắc trong repo để xây trợ lý nhận câu hỏi như “Đơn 1234 đang ở đâu?”. LLM không tự truy cập cơ sở dữ liệu. Thay vào đó, nó tạo một tool call có cấu trúc, chẳng hạn ý định là lookup_order và tham số là mã đơn hàng.
Code của hệ thống kiểm tra mã đơn, gọi dữ liệu đơn hàng rồi trả kết quả có cấu trúc vào context. Agent có thể dùng kết quả đó để soạn câu trả lời cho khách. Nếu mã đơn không tồn tại, lỗi nên được đưa lại dưới dạng ngắn gọn để agent biết cần hỏi lại hoặc báo không tìm thấy.
B.Nhân viên văn phòng muốn tự động hóa phê duyệt
Một nhân viên có thể dùng agent để đọc đề xuất chi phí, lấy thông tin liên quan và chuẩn bị bản tóm tắt. Tuy nhiên, bước duyệt cuối không nên để agent tự quyết định.
Bạn có thể thiết kế một tool liên hệ người phụ trách. Agent tạm dừng khi cần phê duyệt, chờ phản hồi rồi tiếp tục. Trạng thái thực thi và trạng thái nghiệp vụ, như “đang chờ duyệt” hoặc “đã duyệt”, nên được lưu cùng cách nhất quán.
C.Dev xây chatbot hỗ trợ kỹ thuật
Một dev có thể chia chatbot thành agent nhỏ: agent phân loại câu hỏi, agent tìm tài liệu và agent soạn câu trả lời. Mỗi agent chỉ nhận những tool và context cần thiết.
Khi API tìm kiếm lỗi, hệ thống không cần đưa toàn bộ log dài vào prompt. Nó có thể gửi một thông báo ngắn gồm tool bị lỗi, lý do và hành động được phép thử lại. Cách này làm context dễ đọc và giúp việc kiểm thử rõ hơn.
D.Đội sản phẩm thêm AI vào quy trình hiện có
Nếu công ty đã có hệ thống xử lý webhook hoặc cron, bạn có thể kích hoạt cùng một agent từ các nguồn đó thay vì chỉ từ giao diện chat. Ví dụ, một webhook báo có phản hồi mới có thể tạo sự kiện cho agent phân loại và chuyển đến bộ phận phù hợp.
Phần agent nên nhận sự kiện và trạng thái, còn cách kích hoạt nên nằm ở lớp bên ngoài. Khi cần kiểm tra lỗi, đội ngũ có thể phát lại chuỗi sự kiện để xem agent đã chuyển trạng thái như thế nào.
Chất lượng agent đến từ những phần mềm nhỏ, rõ ràng và có thể kiểm soát, không chỉ từ một prompt hay một framework.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Tưởng đây là package cài xong chạy ngay
README không cung cấp quy trình cài đặt ứng dụng hoàn chỉnh. Nếu bạn tìm lệnh khởi động nhưng không thấy, đó không nhất thiết là lỗi máy.
Hãy xem repo như một guide kèm mã nguồn tham khảo. Mở Makefile, packages/ và workshops/ để tìm hướng dẫn riêng cho phần bạn muốn dùng.
B.Tự đoán lệnh cài dependency
Repo dùng TypeScript, nhưng README không nói phải dùng npm, yarn, pnpm hay công cụ nào khác. Chạy nhầm lệnh có thể tạo lockfile hoặc dependency không đúng với phần mã bạn đang xem.
Chỉ chạy lệnh được ghi trong package hoặc workshop tương ứng. Nếu chưa có hướng dẫn, hãy ghi nhận rằng README chưa ghi cách cài thay vì tự bịa lệnh.
C.Đưa quá nhiều dữ liệu vào context
Một agent có thể hoạt động kém khi prompt chứa quá nhiều lịch sử, log hoặc dữ liệu không liên quan. Đây là lỗi dễ gặp khi bạn chỉ nối mọi kết quả vào context.
Hãy áp dụng nguyên tắc sở hữu context window: chọn dữ liệu cần thiết, rút gọn lỗi và giới hạn thông tin theo từng bước. Kết quả nên được thiết kế để agent có thể hành động tiếp.
D.Giao toàn bộ quyền quyết định cho LLM
Mô hình có thể chọn nhầm tool, gửi tham số sai hoặc thực hiện bước không phù hợp với nghiệp vụ. Rủi ro tăng cao khi tool có quyền sửa dữ liệu, gửi thông báo hoặc thực hiện giao dịch.
Hãy kiểm tra schema, giới hạn quyền, đặt điều kiện dừng và yêu cầu người duyệt ở bước nhạy cảm. Những phần quan trọng nên do code xác định kiểm soát.
E.Không lưu trạng thái để tiếp tục
Nếu agent chỉ chạy trong một vòng lặp tạm thời, quy trình có thể mất dấu khi máy chủ khởi động lại hoặc người dùng chưa phản hồi.
Hãy thiết kế trạng thái và sự kiện theo hướng có thể lưu, khôi phục và phát lại. Với các quy trình cần audit, cách tiếp cận stateless reducer trong repo là một hướng đáng đọc.
VII.Có nên dùng không
Nên dùng nếu bạn đang xây ứng dụng LLM thật và muốn hiểu các quyết định kỹ thuật phía sau agent. Repo đặc biệt hữu ích cho dev muốn giữ quyền kiểm soát prompt, context, tool, trạng thái và control flow. Nó cũng phù hợp để tham khảo khi bạn đã có sản phẩm hiện tại và chỉ muốn thêm từng năng lực AI nhỏ.
Điểm mạnh là tư duy thực tế, dễ áp dụng theo từng phần và không bắt bạn phải viết lại toàn bộ hệ thống bằng một framework. Các factor giúp bạn nhìn agent như phần mềm có trạng thái, API, lỗi và giới hạn rõ ràng.
Giới hạn là README không phải hướng dẫn cài đặt từng bước cho một ứng dụng hoàn chỉnh. Repo cũng không chỉ định một nhà cung cấp LLM, bộ dependency, API key hay quy trình triển khai. Người mới muốn có chatbot chạy ngay sẽ cần tìm một dự án thực hành hoặc framework có quick start cụ thể hơn.
Bạn nên chọn repo này để học cách thiết kế và đánh giá agent. Nếu mục tiêu là dựng nhanh một sản phẩm mẫu, hãy dùng công cụ có hướng dẫn cài đặt rõ ràng, rồi quay lại 12-factor-agents để kiểm tra kiến trúc, trạng thái, quyền hạn và khả năng vận hành của hệ thống.
Câu hỏi thường gặp
Repo này có phải một framework để cài và chạy agent ngay không?
Không hẳn. README chủ yếu là tài liệu về các nguyên tắc xây ứng dụng LLM đáng tin, kèm cấu trúc mã nguồn và workshop. README chưa ghi quy trình cài đặt một ứng dụng agent hoàn chỉnh.
Có cần biết TypeScript mới đọc được repo không?
README nói tác giả dùng chủ yếu TypeScript, nhưng các nguyên tắc có thể áp dụng bằng Python hoặc ngôn ngữ khác. Vì vậy, bạn có thể đọc phần tư duy thiết kế mà không cần dùng TypeScript ngay.
Repo có yêu cầu GPU không?
Tư liệu được cung cấp không nêu yêu cầu GPU. README cũng không ghi yêu cầu phần cứng cụ thể.
Có cần API key để dùng repo không?
README không chỉ định nhà cung cấp LLM, tên API key hay biến môi trường. Nếu bạn xây ứng dụng dựa trên các nguyên tắc này, yêu cầu API key sẽ phụ thuộc vào mô hình và hệ thống bạn chọn.
Chạy trên Windows được không?
README không nêu hệ điều hành được hỗ trợ. Các bước clone và mở thư mục là thao tác Git phổ thông, nhưng khả năng chạy từng package cần kiểm tra trong `Makefile`, `packages/` hoặc `workshops/`.
Repo có miễn phí không?
Tư liệu ghi nội dung được cấp phép CC BY-SA 4.0 và code được cấp phép Apache 2.0. README không ghi thêm chi phí dịch vụ LLM hoặc chi phí vận hành bên ngoài.
Điểm khác biệt chính so với việc dùng một agent framework là gì?
Repo khuyến khích lấy các khái niệm nhỏ như tool call, quản lý context, trạng thái và control flow rồi đưa vào sản phẩm hiện có. Mục tiêu là giữ quyền kiểm soát sâu hơn thay vì phụ thuộc hoàn toàn vào một framework.


