Bài 7 — Observability & độ tin cậy: quan sát và phục hồi agent

Agent là hộp đen nhiều bước: một lượt có thể gọi LLM 8 lần, dùng 3 tool, rẽ nhánh theo quyết định của model. Khi lỗi hoặc chậm, nếu không quan sát được, bạn mù hoàn toàn. Bài này chỉ cách làm agent quan sát được và tự phục hồi.

Ba trụ cột observability cho agent

• Traces: theo dõi trọn một lượt agent — từng lời gọi LLM, từng tool call, thời gian, token, kết quả. Đây là thứ quan trọng NHẤT với agent vì luồng phi tuyến.
• Metrics: tỉ lệ thành công, độ trễ p50/p95, token/lượt, chi phí/lượt, độ sâu queue, tỉ lệ 429.
• Logs: sự kiện có cấu trúc (JSON), luôn kèm trace_id/job_id để nối các mảnh lại.

Correlation ID xuyên suốt

Mỗi lượt agent phải có một trace_id duy nhất, đi kèm mọi log/metric/webhook. Khi người dùng báo "job của tôi hỏng", bạn tìm theo trace_id là thấy toàn bộ hành trình.

import logging, json
def log_event(trace_id, step, **kw):
    logging.info(json.dumps({"trace_id": trace_id, "step": step, **kw}))

log_event(tid, "llm_call", model="gpt-4o", tokens=1240, ms=2100)
log_event(tid, "tool_call", tool="search", ok=True, ms=340)

Ghi lại từng bước của agent

Với agent, hãy log ở mức step: prompt đưa vào, tool nào được chọn, tham số tool, kết quả tool, số token. Khi model "ảo giác" gọi sai tool, bạn cần thấy chính xác bước đó — không thể suy ra từ một log tổng.

Độ tin cậy: thiết kế để lỗi vẫn sống

• Timeout mọi lời gọi ngoài: LLM, tool, DB. Không timeout = treo vô hạn.
• Circuit breaker: khi một tool lỗi liên tục, "ngắt mạch" tạm để không dồn request vào chỗ chết, cho nó thời gian hồi.
• Fallback: LLM chính 429 → thử model dự phòng, hoặc trả kết quả một phần rõ ràng thay vì lỗi trắng.
• Checkpoint tác vụ dài: lưu tiến độ sau mỗi bước lớn. Worker chết thì chạy tiếp từ checkpoint, không làm lại từ đầu (đỡ token).
• Graceful degradation: mất vector DB thì agent vẫn trả lời được ở mức cơ bản, báo rõ hạn chế.

Cảnh báo (alerting) nên có

• DLQ có message → điều tra ngay.
• Tỉ lệ lỗi lượt agent vượt ngưỡng.
• p95 độ trễ tăng bất thường.
• Chi phí token/ngày vượt ngân sách.
• Độ sâu queue tăng liên tục (worker không theo kịp).

Khung tư duy: "Thấy — Chịu lỗi — Hồi phục"

Thấy:     trace_id + step logs + metrics token/độ trễ/chi phí
Chịu lỗi: timeout + circuit breaker + fallback
Hồi phục: checkpoint + retry backoff + DLQ + alert

Các bước triển khai

• Gắn trace_id ngay khi job vào, truyền qua mọi lớp.
• Log có cấu trúc từng step (llm_call, tool_call) kèm token và ms.
• Xuất metrics: success rate, p95, token/lượt, chi phí, độ sâu queue.
• Đặt timeout cho mọi lời gọi ngoài.
• Thêm circuit breaker cho tool hay lỗi và fallback model.
• Checkpoint tiến độ cho tác vụ nhiều bước.
• Cấu hình alert cho DLQ, lỗi, chi phí, độ trễ.

Sai lầm thường gặp

• Chỉ log kết quả cuối: không thấy bước nào hỏng trong chuỗi agent.
• Không có correlation id: log rời rạc, không ghép được một lượt.
• Không đo token/chi phí: hóa đơn nổ mà không biết bước nào ngốn.
• Không timeout lời gọi ngoài: một tool treo kéo cả agent treo.
• Retry mù không circuit breaker: dồn request vào dịch vụ đang chết.
• Không checkpoint: worker chết ở bước 7/8 phải chạy lại toàn bộ, đốt token.
• Không alert DLQ: job lỗi nằm im, người dùng phát hiện trước bạn.