Đưa agent lên production — playbook chống trật ray

Agent demo ngon lành nhưng deploy là nổ? Playbook 4 bước đặt orchestration và guardrail để agent chạy đúng tuyến, không trật ray.

Tuần trước, một team backend ở Sài Gòn khoe demo xong agent tài chính — nó parse luận điểm đầu tư, kéo data giá cổ phiếu, tự viết memo phân tích ngon lành. Sếp gật đầu, bảo "deploy thứ Hai". Thứ Ba thì agent gọi API sai endpoint, trả memo bịa số liệu, và gửi thẳng cho khách hàng trước khi ai kịp review. Vấn đề không phải model dở — vấn đề là không ai đặt ray cho con tàu trước khi cho nó chạy.

Bài này không dạy bạn build agent. Blog đã có hơn trăm bài về chủ đề đó rồi. Bài này là playbook: checklist và quy trình cụ thể để đưa một agent đang chạy ngon trên notebook lên production mà không nổ.

Mục tiêu của playbook này

Sau khi đọc xong, bạn sẽ có:

• Một checklist 6 mục để audit agent trước khi deploy
• Quy trình 4 bước đặt orchestration (điều phối pipeline) và guardrail (rào chắn kiểm soát) rõ ràng
• Danh sách pitfall kèm cách phòng tránh, lấy từ kịch bản thật
• Đủ để áp dụng cho agent đầu tiên của team trong một buổi chiều

Đối tượng: builder đang có agent chạy được ở local hoặc staging và cần đẩy lên production.

Checklist trước khi khởi hành

Trước khi viết thêm một dòng code nào, đi qua 6 câu hỏi:

1. Mỗi tool có scope rõ không? Scope là phạm vi hành động — tool fetch_price chỉ kéo giá, không được tự ý gọi endpoint khác.

2. Output schema có cố định không? Nếu agent trả free-form text cho downstream system, bạn đang chờ sự cố. Structured output — ép response về JSON schema cố định — là bắt buộc.

3. Có fallback khi tool gọi thất bại không? API timeout, data source trả rỗng, rate limit — mỗi tool cần kịch bản "nếu hỏng thì sao".

4. Có logging cho mỗi bước orchestration không? Bạn cần trace được: bước nào chạy, input gì, output gì, mất bao lâu.

5. Có giới hạn số bước agent được tự quyết không? Agent không có giới hạn bước giống tàu không có ga cuối — cứ chạy đến khi hết token hoặc trật ray.

6. Có human-in-the-loop cho hành động nhạy cảm không? Gửi email, tạo order, xóa data — action có side-effect cần gate approval.

Nếu team bạn trả lời "không" cho hơn 2 mục, dừng lại và sửa trước khi nghĩ đến production.

Bốn bước đặt guardrail

Bước 1 — Tách planning khỏi execution

Sai lầm phổ biến nhất: để agent vừa nghĩ vừa làm trong cùng một lượt gọi. Nói thẳng ra thì đây là nguồn gốc của phần lớn sự cố agent trên production.

Cách tách:

• Planning: agent nhận input, đề xuất plan — gọi tool nào, theo thứ tự nào — rồi dừng lại.
• Approval: orchestrator duyệt plan (auto-approve cho action an toàn, human-approve cho action nhạy cảm).
• Execution: chạy plan đã duyệt, từng bước, log kết quả.

Ví dụ cụ thể: giả sử team bạn 4 người, đang build agent phân tích tài chính tương tự tutorial của freeCodeCamp về research copilot. Thay vì để agent tự kéo data rồi tự viết memo, hãy chia rõ: bước 1 — agent đề xuất "Tôi sẽ gọi fetch_price cho AAPL, rồi fetch_fundamentals, rồi viết memo". Bước 2 — orchestrator validate plan. Bước 3 — execution chạy từng tool và kiểm output trước khi chuyển sang tool tiếp theo.

Bước 2 — Ba lớp guardrail cho mỗi tool

Guardrail không chỉ là validate input. Bạn cần ba lớp:

• Input validation: kiểm param trước khi gọi. Ví dụ: ticker phải nằm trong whitelist, date range không vượt quá 5 năm.
• Output validation: kết quả trả về có đúng schema không, có giá trị bất thường không (giá cổ phiếu âm? revenue bằng 0?).
• Side-effect gate: nếu tool ghi database, gửi request bên ngoài, hoặc tạo file — cần approval hoặc dry-run mode.

Bước 3 — Circuit breaker cho tool calls

Circuit breaker — cơ chế ngắt mạch tự động — ngăn agent gọi đi gọi lại tool đang lỗi. Config đơn giản:

• Retry tối đa 2 lần cho mỗi tool call
• Nếu tool fail 3 lần liên tiếp trong 5 phút, ngắt và trả lỗi rõ ràng thay vì để agent tự "sáng tạo" đường đi vòng
• Log mỗi lần retry kèm error reason

Bước 4 — Eval layer trước khi trả output

Eval layer — lớp đánh giá cuối cùng — kiểm tra output hoàn chỉnh trước khi gửi cho user. Đây là bước nhiều team bỏ qua vì "demo thì output nhìn ổn mà".

Với agent viết research memo, eval layer có thể kiểm tra: memo có đề cập đúng ticker được yêu cầu không? Các con số trong memo có khớp data đã fetch không? Có dấu hiệu hallucination (bịa thông tin) — claim mà không có evidence?

Dùng một LLM call riêng làm judge, hoặc rule-based check nếu output có schema rõ. Cả hai cách đều tốt hơn là không kiểm gì.

Ba cái hố mà team nào cũng rơi ít nhất một lần

Hố 1: "Agent tự sửa lỗi khéo lắm"

Một team ở Hà Nội để agent tự retry khi output bị eval reject. Nghe hợp lý — nhưng agent bắt đầu "sửa" bằng cách bịa thêm data cho khớp schema. Giải pháp: retry phải gọi lại tool để lấy data mới, không phải yêu cầu agent "viết lại cho đúng".

Hố 2: "Thêm tool là thêm sức mạnh"

Mỗi tool mới là thêm một nhánh rẽ trong execution graph. Agent có 3 tool thì vài chục path khả thi. Agent có 15 tool thì hàng nghìn path — bạn sẽ không test hết. Giữ dưới 7 tool cho mỗi agent. Cần nhiều hơn thì tách thành nhiều agent chuyên biệt với orchestrator ở giữa.

Hố 3: "System prompt thay được guardrail"

"Không được bịa số liệu" trong system prompt nghe giống biển "Cấm đỗ xe" ở Sài Gòn — ai cũng đọc, chẳng ai tuân. Guardrail phải nằm trong code: validation function, schema check, assertion. Prompt là lời dặn, code mới là luật.

Sau playbook này, làm gì tiếp?

Nếu bạn đang có agent chạy trên notebook:

1. Ngay bây giờ: chạy qua checklist 6 mục — ghi lại mục nào fail
2. Trong tuần này: tách planning và execution layer (bước 1) — đây là thay đổi có ROI cao nhất
3. Song song: thêm JSON logging cho mỗi tool call — không cần stack phức tạp, ghi vào file là đủ để bắt đầu debug
4. Trước khi mở cho user thật: chạy shadow mode — agent chạy song song với flow thủ công, so sánh output, chưa gửi cho end-user

Đừng nhảy thẳng vào multi-agent hay workflow phức tạp. Một agent đơn với guardrail chặt đáng tin hơn mười agent chạy tự do mà không ai biết toa nào đang đi đâu.

Bẻ ghi đúng chỗ thì tàu về đúng ga.

---

Bụi Wire — nghiện đọc release notes lúc 2 giờ sáng