Đưa Agent lên Production — Kiến trúc, Quan sát, Chi phí & Độ bền
Kiến trúc chạy agent bất đồng bộ và bền, tracing theo chuẩn OpenTelemetry, kiểm soát chi phí và độ trễ, xử lý lỗi, và quy trình phát hành an toàn.
Khoảng cách giữa demo và production của agent lớn hơn hầu hết các loại phần mềm khác. Demo chạy 30 giây trên máy bạn; production chạy 40 phút, giữa chừng server được deploy lại, API bên thứ ba trả 429, người dùng đóng tab, và cuối tháng hoá đơn gấp năm dự tính. Module này áp dụng những gì bạn biết từ các khoá Backend API, DevOps và System Architecture vào đặc thù của agent: phiên dài, không tất định, chi phí biến thiên theo từng yêu cầu.
🎯 Mục tiêu học tập
- Thiết kế kiến trúc chạy agent: bất đồng bộ, streaming tiến độ, lưu trạng thái, tiếp tục sau lỗi
- Hiểu durable execution và khi nào cần nó thay vì checkpoint tự viết
- Thiết lập tracing cho agent theo chuẩn OpenTelemetry và xác định các chỉ số cần theo dõi
- Áp dụng các đòn bẩy chi phí và độ trễ theo đúng thứ tự ưu tiên
- Xây quy trình phát hành: quản lý phiên bản prompt/tool, chạy bóng, canary, phản hồi từ production về eval
Kiến trúc tham chiếu
Client ──POST /runs──▶ API ──enqueue──▶ Hàng đợi ──▶ Worker (vòng lặp agent)
▲ │ │ │
│ ▼ │ ├──▶ Model API
└──SSE/WebSocket── Luồng sự kiện ◀──── phát sự kiện ───┘ ├──▶ Tools / MCP / Sandbox
│ └──▶ Kho trạng thái (checkpoint)
▼
Trace / Metrics / Audit log
| Quyết định thiết kế | Lý do |
|---|---|
Bất đồng bộ từ đầu: API trả run_id ngay, việc chạy ở worker | Phiên agent dài hơn timeout HTTP; client có thể ngắt kết nối và quay lại |
| Luồng sự kiện tách khỏi request: lưu sự kiện có số thứ tự, client đọc lại từ vị trí cuối | Hiển thị tiến độ (đang gọi tool gì); nối lại không mất sự kiện |
| Checkpoint sau mỗi bước vào kho bền | Worker chết, deploy lại, chờ người duyệt — đều tiếp tục được |
| Worker không giữ trạng thái | Bất kỳ worker nào cũng nhặt lại được một run; scale ngang |
| Tool có idempotency | Một bước có thể bị chạy lại sau khi phục hồi |
| Huỷ được: cờ huỷ kiểm tra giữa các bước | Người dùng đổi ý; dừng khẩn cấp |
| Giới hạn đồng thời theo người dùng và toàn cục | Rate limit của model API là tài nguyên dùng chung |
Đây là kiến trúc hàng đợi + worker bạn đã gặp ở khoá Backend API (RabbitMQ/Kafka, idempotency, retry) — agent chỉ là một loại job chạy lâu và tốn kém.
Durable execution
Checkpoint tự viết đủ dùng cho vòng lặp đơn giản. Khi luồng phức tạp hơn — chờ người duyệt nhiều ngày, hẹn giờ, nhiều subagent, bù trừ khi thất bại giữa chừng — các nền tảng durable execution (Temporal, Restate, DBOS, Inngest...) giải quyết ở tầng hạ tầng: code viết như chạy liền mạch, nền tảng ghi lại kết quả từng bước và phát lại để khôi phục đúng trạng thái sau sự cố.
| Khái niệm | Trong ngữ cảnh agent |
|---|---|
| Workflow (tất định, phát lại được) | Vòng lặp agent: thứ tự các bước |
| Activity (có tác dụng phụ, tự retry) | Mỗi lời gọi model, mỗi lời gọi tool |
| Signal | Quyết định của người duyệt, tin nhắn mới của người dùng |
| Timer bền | "Chờ tối đa 48 giờ, sau đó chuyển cấp" |
Điểm cần nhớ: lời gọi model không tất định nên phải nằm trong activity — kết quả được ghi lại một lần và phát lại nguyên vẹn, không gọi lại model khi khôi phục. Chọn: checkpoint tự viết hoặc checkpointer của framework cho agent đơn; durable execution khi đã có hoặc sẵn sàng vận hành nền tảng đó; nền tảng agent được quản lý khi muốn giao hẳn phần này.
Quan sát: trace là công cụ debug chính
Với agent, log dạng dòng không đủ. Bạn cần trace: một cây span thể hiện toàn bộ một run — mỗi lời gọi model, mỗi tool, mỗi subagent — kèm thời gian, token, đầu vào/đầu ra.
from opentelemetry import trace
tracer = trace.get_tracer("support-agent")
def run_agent(run_id, user_input):
with tracer.start_as_current_span("invoke_agent support-agent") as run_span:
run_span.set_attribute("gen_ai.operation.name", "invoke_agent")
run_span.set_attribute("gen_ai.agent.name", "support-agent")
run_span.set_attribute("app.run_id", run_id)
run_span.set_attribute("app.prompt_version", PROMPT_VERSION)
for step in range(MAX_STEPS):
with tracer.start_as_current_span("chat claude-opus-5-5") as s:
response = call_model(messages)
s.set_attribute("gen_ai.request.model", "claude-opus-5-5")
s.set_attribute("gen_ai.usage.input_tokens", response.usage.input_tokens)
s.set_attribute("gen_ai.usage.output_tokens", response.usage.output_tokens)
s.set_attribute("gen_ai.response.finish_reasons", [response.stop_reason])
for call in tool_calls(response):
with tracer.start_as_current_span(f"execute_tool {call.name}") as t:
t.set_attribute("gen_ai.tool.name", call.name)
result = run_tool(call)
t.set_attribute("app.tool.is_error", result.is_error)
Dùng quy ước ngữ nghĩa OpenTelemetry GenAI để không khoá vào một nhà cung cấp; hầu hết công cụ (Langfuse, LangSmith, Arize Phoenix, Braintrust, các APM phổ thông) đều nhận được, và nhiều framework tự phát span theo chuẩn này.
| Nhóm chỉ số | Theo dõi |
|---|---|
| Kết quả | Tỉ lệ run hoàn thành / thất bại / bị huỷ / chạm giới hạn; phân bố lý do dừng |
| Chất lượng | Điểm từ grader chạy trên mẫu production; phản hồi người dùng; tỉ lệ chuyển cho người |
| Hiệu quả | Số bước, token, chi phí mỗi run (p50, p95, p99); tỉ lệ trúng cache |
| Độ trễ | Thời gian tới sự kiện đầu tiên; thời gian mỗi bước; tổng thời gian |
| Tool | Tỉ lệ lỗi và độ trễ theo từng tool; tool nào được gọi nhiều nhất; lời gọi lặp |
| An toàn | Số lần bị chính sách từ chối; tỉ lệ duyệt/từ chối; cảnh báo injection |
Cẩn trọng với dữ liệu: trace chứa nội dung hội thoại và kết quả tool — che dữ liệu nhạy cảm, giới hạn quyền xem và thời gian lưu.
Chi phí và độ trễ: thứ tự các đòn bẩy
Đo trước khi tối ưu: lập hồ sơ token (bao nhiêu là system/tool, lịch sử, kết quả tool, output; tỉ lệ trúng cache). Rồi đi theo thứ tự — phần miễn phí trước, phần đánh đổi chất lượng sau:
| # | Đòn bẩy | Tác động | Đánh đổi |
|---|---|---|---|
| 1 | Prompt caching đúng cách (Module 4) | Rất lớn với vòng lặp dài | Không |
| 2 | Vệ sinh context: giới hạn kết quả tool, xoá kết quả cũ, bớt tool thừa | Lớn | Không, nếu làm cẩn thận |
| 3 | Vệ sinh vòng lặp: tool gộp, gọi song song, gọi tool qua code | Giảm số bước và độ trễ | Công thiết kế tool |
| 4 | Batch cho việc không cần ngay (eval, xử lý nền) | Giảm khoảng một nửa giá | Độ trễ hàng giờ |
| 5 | Giảm effort cho các tuyến không cần suy luận sâu | Lớn | Chất lượng — phải đo bằng eval |
| 6 | Model nhỏ hơn cho subagent/việc phụ | Lớn với hệ multi-agent | Chất lượng phần việc đó |
| 7 | Routing: việc đơn giản không qua agent | Rất lớn nếu phần lớn lưu lượng là đơn giản | Thêm độ phức tạp, rủi ro phân loại sai |
- Chỉ số đúng là chi phí cho mỗi tác vụ hoàn thành, không phải mỗi request. Cấu hình rẻ hơn nhưng cần gấp đôi số bước hoặc hay thất bại thì không rẻ.
- Ngân sách cứng ở nhiều cấp: mỗi run, mỗi người dùng mỗi ngày, toàn hệ thống — kèm cảnh báo khi bất thường.
- Độ trễ cảm nhận: streaming văn bản và sự kiện tiến độ ("đang tra cứu đơn hàng...") làm 40 giây chờ dễ chịu hơn nhiều so với một thanh quay im lặng.
Độ bền: lỗi là trạng thái bình thường
| Sự cố | Xử lý |
|---|---|
| Model API trả 429 / 5xx / quá tải | Retry có backoff và jitter (SDK thường tự làm); giới hạn đồng thời phía client; hàng đợi hấp thụ đỉnh tải |
| Tool lỗi tạm thời | Harness retry vài lần; sau đó báo cho agent rằng tool tạm thời không dùng được |
| Tool treo | Timeout từng tool; trả lỗi cho agent thay vì chờ mãi |
| Worker chết giữa run | Checkpoint + tiếp tục; tool idempotent |
| Agent lặp vô ích | Phát hiện lặp, giới hạn bước, ngân sách; khi chạm thì kết thúc có tóm tắt tiến độ |
Output bị cắt (max_tokens) | Không chạy tool call dở; tăng giới hạn/streaming; yêu cầu tiếp tục |
| Model từ chối | Kết thúc rõ ràng với người dùng; không retry y nguyên |
| Context đầy | Compaction/xoá kết quả cũ chủ động trước khi chạm trần |
| Nhà cung cấp gặp sự cố kéo dài | Phương án dự phòng (nền tảng/khu vực khác) đã được kiểm thử trước; suy giảm có kiểm soát |
Thất bại có ích: khi không hoàn thành được, agent nên trả về những gì đã làm, đã phát hiện, và còn thiếu gì — để người hoặc lần chạy sau tiếp tục, thay vì một thông báo lỗi trống.
Quy trình phát hành và vòng phản hồi
- Mọi thứ đều có phiên bản: system prompt, định nghĩa tool, model, effort, cấu hình harness — trong git, và gắn vào mọi trace để biết run nào chạy cấu hình nào.
- Ghim phiên bản model; nâng cấp model là một thay đổi cần chạy lại eval và thường cần chỉnh lại prompt (model mới hay làm đúng những gì prompt cũ dặn quá kỹ).
- Cổng eval trong CI: regression suite phải đạt trước khi merge (Module 13).
- Chạy bóng (shadow): phiên bản mới chạy song song trên lưu lượng thật, ở chế độ không có tác dụng phụ, để so sánh trước khi mở.
- Canary: mở cho vài phần trăm, theo dõi tỉ lệ hoàn thành, chi phí, tỉ lệ chuyển cho người; có đường lùi nhanh.
- Mở rộng tự chủ theo giai đoạn: chỉ gợi ý → hành động có duyệt → tự động trong phạm vi hẹp → mở rộng phạm vi, mỗi bước dựa trên số liệu.
- Vòng phản hồi: lỗi production → phân loại qua transcript → thành task eval mới → sửa → kiểm chứng. Đây là bánh đà làm agent tốt dần theo thời gian.
- Sổ tay sự cố: cách tắt một tool, hạ mức tự chủ, chuyển toàn bộ sang người, và ai được quyền làm.
🏋️ Bài tập thực hành
Đóng gói một agent bạn đã xây thành dịch vụ: (1) API FastAPI với POST /runs trả
run_id, GET /runs/{id}/events phát sự kiện tiến độ qua SSE và cho phép nối lại từ số thứ tự
cuối, POST /runs/{id}/cancel; (2) worker lấy việc từ hàng đợi (Redis là đủ), checkpoint sau mỗi
bước vào Postgres; (3) trace OpenTelemetry theo quy ước GenAI xuất tới một backend mã nguồn mở (Langfuse
hoặc Phoenix chạy bằng Docker Compose); (4) ngân sách cứng theo run và theo người dùng mỗi ngày. Kiểm thử
hỗn loạn: giết worker giữa một run và xác nhận run tiếp tục mà không chạy lại tool ghi; giả lập model API
trả 429 liên tục trong 30 giây; cho một tool treo. Cuối cùng lập hồ sơ token của 20 run, áp dụng ba đòn bẩy
chi phí đầu tiên, và báo cáo chi phí cho mỗi tác vụ hoàn thành trước và sau.
📚 Tài nguyên học tập
-
OpenTelemetry — Semantic conventions for GenAIQuy ước span/thuộc tính chuẩn cho lời gọi model, tool và agentChuẩn
-
Anthropic — Effective harnesses for long-running agentsThiết kế harness cho agent làm việc qua nhiều phiên, nhiều giờBài viết
-
Temporal — DocumentationNền tảng durable execution: workflow, activity, signalDocs
-
Langfuse — DocumentationNền tảng quan sát LLM/agent mã nguồn mở, tự host đượcDocs
-
Claude Docs — Rate limitsCơ chế giới hạn và cách thiết kế quanh nóDocs
-
Claude Docs — Batch processingXử lý không cần ngay với chi phí thấp hơnDocs
✅ Tự đánh giá hoàn thành
- Agent của mình chạy bất đồng bộ, phát sự kiện tiến độ, huỷ được, và tiếp tục được sau khi worker chết
- Mỗi run có trace đầy đủ theo chuẩn mở, gắn phiên bản prompt/tool/model
- Có dashboard các chỉ số kết quả, hiệu quả, tool và an toàn
- Đã lập hồ sơ token và áp dụng các đòn bẩy chi phí theo thứ tự; đo theo chi phí mỗi tác vụ hoàn thành
- Có quy trình phát hành với cổng eval, canary, đường lùi, và sổ tay sự cố