Giải mã 12-Factor Agents: 12 nguyên tắc xây dựng phần mềm LLM cấp Production (Hướng dẫn 2026)

Vì sao “Cứ dùng LangChain” không còn hiệu quả #

Mỗi kỹ sư đã từng đưa một tính năng dùng LLM cho người dùng thật đều đụng phải cùng một bức tường: prototype chạy đẹp trong notebook, sụp đổ ngay khi khách hàng trả tiền gọi đầu tiên từ góc độ khác. Agent ảo giác một tool call, context window nổ tung giữa session, lỗi âm thầm bị nuốt, retry quay vô tận, postmortem cho thấy — ngay cả kỹ sư xây nó cũng không thực sự hiểu agent đang làm gì khi nó hỏng.

Hệ sinh thái agentic AI 2025–2026 đẻ ra hàng tá framework hứa “biến agent thành production-ready” — LangChain, LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Pydantic AI, danh sách dài thêm. Mỗi cái đều giải quyết được vấn đề demo (kết hợp tool call, định tuyến giữa sub-agent). Hầu như không cái nào giải quyết được vấn đề production (hành vi dự đoán được khi input bất ngờ, failure mode quan sát được, session phục hồi được).

12-Factor Agents (GitHub: humanlayer/12-factor-agents, 22,000+ stars tính đến tháng 5/2026) là câu trả lời của Dex Horthy và HumanLayer cho khoảng trống đó. Mô phỏng theo phương pháp 12-Factor App của Heroku năm 2011, đây là một phương pháp luận — không phải framework, không phải runtime, không phải SaaS — để suy nghĩ về phần mềm LLM mà khách hàng thực sẽ dùng.

Code Apache 2.0, văn bản CC BY-SA 4.0. 273 commit và tăng, chủ yếu TypeScript với Python và Jupyter làm ví dụ dễ tiếp cận.

Insight cốt lõi #

Các framework trừu tượng hóa đi bốn thứ thực sự quan trọng nhất khi agent hỏng:

1. Prompt đã được gửi đi.
2. Context window đang hoạt động.
3. Control flow quyết định làm gì tiếp.
4. Execution state cần sống sót qua crash.

12-Factor Agents lập luận, từng dòng, rằng mọi thứ trong số này phải là code bạn sở hữu — không phải phép màu mà framework giấu. Kết quả là nhiều code hơn trong repo và ít cầu nguyện hơn khi sự cố ập đến lúc 3 giờ sáng.

Đây là toàn bộ 12 factor, kèm ý nghĩa thực tế của từng cái.

12 Factor #

1. Ngôn ngữ tự nhiên sang Tool Call #

Việc của LLM là dịch ý định người dùng thành tool call có cấu trúc — chỉ thế. Đừng yêu cầu LLM “làm việc đó”. Hãy yêu cầu nó emit JSON mô tả làm việc đó, rồi để code xác định thực thi. Ràng buộc duy nhất này loại bỏ cả một loại sự cố do ảo giác.

2. Sở hữu Prompt của bạn #

Prompt là code. Nó thuộc về repo, version control, code review của bạn. Template bị chôn trong prompt library của framework là technical debt chờ thay đổi hành vi âm thầm khi bạn nâng cấp. Nếu hành vi agent phụ thuộc vào một chuỗi, chuỗi đó thuộc về bạn.

3. Sở hữu Context Window của bạn #

Tập message hiện tại trong context model là yếu tố đơn lẻ lớn nhất quyết định hành vi. Framework auto-summarize, auto-prune, auto-inject memory rất tốt — đến khi không còn tốt nữa. Tự viết logic lắp ráp context. Bạn phải in được mảng message chính xác đi vào mỗi LLM call.

4. Tool chỉ là Output có cấu trúc #

“Tool” không phải Function object phép màu — nó là JSON Schema ràng buộc output của LLM. Một khi nội hóa điều này, bạn có thể tạo các “tool” mà LLM không thực sự gọi: state transition, nhánh quyết định, yêu cầu escalation. Bất cứ thứ gì cần LLM cam kết một shape đều có thể là tool.

5. Thống nhất Execution State và Business State #

Agent của bạn có hai state machine: một cho “tôi đang ở đâu trong cuộc hội thoại” và một cho “đơn hàng/ticket/dự án của user đang làm gì”. 12-Factor lập luận hai cái này phải là cùng một state machine. Tách chúng ra là nguồn phổ biến nhất của bug “agent nghĩ đã xong nhưng đơn hàng vẫn pending”.

6. Launch / Pause / Resume với API đơn giản #

Agent của bạn phải có thể bị tạm dừng giữa chừng và resume sau — có thể trên máy khác, có thể sau khi người duyệt. Tức là toàn bộ session state phải serializable. Không closure-over-local-variable phép màu. Không “object LLM client giữ hội thoại sống trong memory”. Dữ liệu thuần, ghi vào nơi durable.

7. Liên hệ con người qua Tool Call #

Khi agent cần input của con người — duyệt, thiếu thông tin, escalation — nó nên emit một tool call, không dừng chết. Tool call đi vào cùng queue/UI/inbox mà con người monitor. Cùng pattern factor 4, áp dụng cho human-in-the-loop. Sản phẩm HumanLayer là phiên bản sản phẩm hóa nguyên tắc này.

8. Sở hữu Control Flow của bạn #

For loop “gọi LLM → chạy tool → gọi LLM lại → kiểm tra xong chưa → gọi LLM lại” là trái tim của mọi agent. Framework giấu nó (“cứ yield và để chúng tôi xử lý loop”) tước đoạt khả năng thêm logic tùy biến — rate limit, ngân sách trần, human checkpoint, retry — ngay tại nơi bạn cần. Viết loop. Hai mươi dòng thôi.

9. Nén Error vào Context Window #

Khi tool call thất bại, đúng cách là feed message lỗi ngắn, có cấu trúc trở lại lượt tiếp theo của LLM và để nó phản ứng. KHÔNG crash. KHÔNG retry âm thầm. KHÔNG log-and-pray. Một “TOOL_FAILED: HTTP 503 from /api/orders, payload too large” 200 ký tự đủ để LLM có động thái hợp lý kế tiếp — back off, thử payload nhỏ hơn, escalate cho người.

10. Agent nhỏ, tập trung #

Một mega-agent “làm mọi thứ” là ác mộng debug. Mười hai agent nhỏ, mỗi cái ba tool và một việc, đều testable và recoverable. Pattern khớp với microservice, cùng trade-off: nhiều chi phí điều phối hơn, cô lập lỗi tốt hơn rất nhiều.

11. Trigger ở mọi nơi, gặp user ở đâu họ có mặt #

Input của agent không nên gắn vào một kênh duy nhất. Message Slack, email, form web, GitHub issue, Telegram bot, cron job — cùng một agent. Cần factor 2 (sở hữu prompt) và factor 5 (state thống nhất) vững trước, nhưng phần thưởng là có thể thêm input source mới mà không phải viết lại agent.

12. Biến Agent của bạn thành Stateless Reducer #

Agent là hàm thuần: state, event → new state, output. Không mutation ẩn. Không “agent nhớ vì có thuộc tính self.history”. Mọi thứ ảnh hưởng output đều ở trong input. Đây là factor làm mọi thứ còn lại khả thi — không có cái này, factor 5, 6, 10 chỉ là kỳ vọng.

Áp dụng vào Stack Thực Tế #

Áp dụng vào workflow Claude Code #

Claude Code đã triển khai sẵn factor 1, 4, 7 theo thiết kế — tool call là structured output, MCP server thêm human-in-the-loop, và catalog tool do bạn sở hữu (cấu hình MCP của project). Cái cần bạn chú ý là factor 2 (system prompt thuộc về bạn để tùy biến qua CLAUDE.md), factor 3 (lắp ráp context window một phần do Claude, nhưng tích hợp pagefind/CodeGraph cho phép bạn định hình), và factor 9 (khi tool trả lỗi, đảm bảo nó gọn và có cấu trúc).

Áp dụng vào stack agent dựa trên MCP #

MCP đóng đinh factor 4 (tool là structured output qua protocol chuẩn hóa) và giúp factor 11 (bất kỳ client MCP nào cũng có thể drive bất kỳ MCP server nào). MCP tự thân im lặng với factor 5, 6, 8, 12 — những cái đó bạn phải xây trên MCP.

Áp dụng vào Hermes Agent / OpenCode / Stack tùy biến #

Những công cụ này cho bạn khởi đầu sẵn về factor 1, 4, 8 (agent loop tích hợp, structured tool call). Bạn vẫn phải mang theo factor 2 (prompt), factor 3 (định hình context), factor 5–6 (state durable), và factor 12 (statelessness) cho riêng mình.

Nơi 12-Factor Agents Bất Đồng với Marketing Framework Chủ Lưu #

Vài nguyên tắc trong manifesto đẩy lùi mạnh khẩu hiệu “dùng framework chúng tôi và quên đi chi tiết”:

• Factor 2 vs prompt library: Hầu hết framework agent ship một prompt library. 12-Factor nói: copy prompt vào repo, rồi chúng thuộc về bạn.
• Factor 3 vs auto-memory: Framework thích cung cấp memory tự động (“RAG out of the box”). 12-Factor nói: đó là nguồn duy nhất lớn nhất của bí ẩn “tại sao agent đang làm thế này?”. Tự xây lắp ráp.
• Factor 8 vs runtime giấu loop: Runtime hosted giấu loop tiện cho đến khi bạn cần inject logic tùy biến. 12-Factor nói: tự viết loop, nó nhỏ.

Đây không phải cuộc chiến chống framework — đây là cuộc chiến chống framework giấu quá nhiều. Dùng framework như library, không phải hộp đen.

12-Factor Agents KHÔNG là gì #

Đặt kỳ vọng đúng:

• Không phải runtime. Không có pip install twelve-factor-agents. Là chữ, ví dụ, pattern.
• Không gắn ngôn ngữ đơn. Ví dụ là TypeScript và Python, nhưng nguyên tắc độc lập ngôn ngữ.
• Không phải tôn giáo. Một số factor (đặc biệt 10 — agent nhỏ tập trung) đi kèm trade-off thật. Manifesto thừa nhận thẳng.
• Chưa hoàn thành. 273 commit và tăng. Issue và discussion liên tục lặp về cách diễn đạt.

Ai Nên Đọc #

Có, đọc từ đầu đến cuối, nếu bạn:

• Đang ship (hoặc sắp ship) tính năng LLM cho khách hàng trả tiền.
• Đã debug sự cố agent “demo thì chạy mà” trong 60 ngày qua.
• Đang phân vân giữa tự viết agent loop và adopt LangGraph/CrewAI/Agents SDK.
• Đang so sánh vendor như Cursor vs Claude Code và muốn checklist “production-ready” thực sự nghĩa là gì.

Có thể đọc lướt nếu bạn:

• Vẫn ở giai đoạn demo “agent đầu tiên” (đọc factor 1, 2, quay lại sau).
• Chỉ dùng nền tảng no-code hosted (n8n, Zapier) không tự viết agent loop.

Kết luận #

12-Factor Agents là manifesto LLM software được trích dẫn nhiều nhất 2026 vì lý do chính đáng: nó đặt từ ngữ cho các pattern mà các kỹ sư ship production agent độc lập đã đến trong hai năm qua. Sự song hành với 12-factor của Heroku không phải tự kiêu — cả hai văn bản đều mã hóa cái gì hết là tùy chọn khi user thực sự phụ thuộc.

Sự thay đổi tư duy đơn lẻ lớn nhất mà manifesto đẩy: agent là phần mềm, và phần mềm cần được hiểu bởi team vận hành nó. Framework làm mờ hợp đồng đó là technical debt, không phải productivity.

Kết hợp 12 factor với lớp symbol hiệu quả token như CodeGraph, proxy LLM nhận thức chi phí như rtk, và control plane CLI hợp nhất như CC Switch, bạn có xương sống kiến trúc của AI stack production 2026.

GitHub: humanlayer/12-factor-agents · License: Apache 2.0 (code) / CC BY-SA 4.0 (content) · Stars: 22K+ · Tác giả: Dex Horthy / HumanLayer