AI Agent Roadmap: Giám sát Agent AI với LangFuse, Helicone, và OpenLLMetry

Một agent chạy 12 bước, gọi 4 tool, qua 2 model, và chỉ để lại một dòng log done. Khi khách hàng báo “hôm qua nó trả lời sai”, bạn không có gì để mở. Giám sát agent không phải bật dashboard cho đẹp; nó là điều kiện để bạn trả lời được ba câu: chuyện gì đã xảy ra, tốn bao nhiêu, và hỏng ở bước nào.

Bài này phân biệt ba thứ hay bị gộp làm một — tracing, eval, monitoring — rồi chỉ ra cách dùng Langfuse 5.2.0, Helicone và OpenLLMetry để có đủ dữ liệu mà không biến log thành bãi rác.

Cập nhật 2026: bốn thay đổi về công cụ và chuẩn

  • Langfuse 5.2.0. SDK hiện tại chạy trên nền OpenTelemetry: trace là cây span, generation là span có token và model. API của dòng 2.x — langfuse.trace(), InitialGeneration — không còn trong SDK 5.x; code copy từ bài 2024 sẽ lỗi import, không phải lỗi cấu hình.
  • Helicone vẫn hoạt động (cập nhật 2026-10), Apache-2.0. Vai trò của nó là gateway: chặn request ở tầng HTTP, log và tính chi phí mà không cần sửa logic agent. Số phiên bản cụ thể chưa xác minh được — đừng ghi số vào tài liệu nội bộ.
  • OpenLLMetry (Traceloop) vẫn hoạt động (2026-11), Apache-2.0. Đây là instrumentation, không phải backend: nó tạo span theo chuẩn OTel rồi đẩy đến collector bạn chọn. Version cũng chưa xác minh.
  • OTel GenAI vẫn ở trạng thái Development. Spec đã chuyển sang repo open-telemetry/semantic-conventions-genai, phủ client inference, embeddings, execute-tool, retrieval, agent span, token metric, cả MCP và A2A. Tên thuộc tính còn đổi — hãy pin phiên bản semconv và ghi vào tài liệu team.

Tracing, eval, monitoring: ba việc, ba dữ liệu

Việc Câu hỏi trả lời Công cụ điển hình
Tracing Chuyện gì đã xảy ra trong một lần chạy này? Langfuse, LangSmith, OTel backend
Eval Chất lượng trên một bộ case có tốt lên không? LangSmith, DeepEval, Ragas, promptfoo
Monitoring Xu hướng production hôm nay có bất thường không? Dashboard trên trace/metric, alert

Chúng chia sẻ telemetry nhưng không thay thế nhau. Một trace đẹp không nói agent đúng 80% hay 60%. Một con số eval không nói bước thứ 7 gọi tool sai tham số. Và một dashboard xanh không nói case hiếm vẫn hỏng. Nếu team bạn chỉ có một trong ba, bạn đang mù ở hai góc.

Mô hình dữ liệu tối thiểu

Một lần chạy agent là một trace. Mỗi bước là một span: gọi model, gọi tool, truy xuất, chờ người duyệt. Span gọi model là generation, và nó phải mang model, token vào/ra, token cache, token reasoning, thời gian, và trạng thái. Span gọi tool phải mang tên tool, tham số đã lọc, kết quả (hoặc hash của kết quả), lỗi nếu có.

Bốn trường luôn có trên mọi span: trace_id, tenant, task_type, step_index. Thiếu tenant thì bạn không tính được chi phí theo khách; thiếu task_type thì mọi chỉ số trung bình trộn ba loại việc khác nhau và không ai hành động được.

Langfuse 5.2.0: trace có cấu trúc, tự host được

Langfuse hợp khi bạn muốn dữ liệu nằm trong hạ tầng của mình (bản OSS) và muốn trace, prompt, eval sống gần nhau. Với SDK 5.x, điểm vào là decorator và span context manager:

# File: app/agent.py
# pip install "langfuse==5.2.0"
from langfuse import observe, get_client

langfuse = get_client()  # đọc LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST

@observe(name="refund-agent")
def handle_refund(order_id: str, tenant: str) -> str:
    with langfuse.start_as_current_span(name="tool:get_order_status") as span:
        span.update(input={"order_id": order_id})
        status = lookup_order(order_id)
        span.update(output={"status": status})

    answer = call_model(status)
    return answer

Nếu bạn pin bản khác 5.2.0, đối chiếu quickstart: tên hàm đã đổi giữa các major. Ngoài cú pháp, có hai điều quan trọng hơn. Thứ nhất, đặt tên span theo quy ước cố định (tool:<name>, llm:<step>, retrieval:<index>) — đây là thứ cho phép bạn group-by sau này; tên tự do làm dashboard vô dụng. Thứ hai, đừng đẩy toàn bộ payload tool vào span. Một tool trả 3MB HTML sẽ làm trace phình, chi phí lưu tăng, và mọi truy vấn chậm. Lưu hash, độ dài, và trường bạn thực sự cần.

Langfuse cũng có prompt management và eval — nhưng đừng dùng nó như nguồn sự thật duy nhất cho eval; bài trước trong series đã nói vì sao dataset và gate nên sống gần code.

Helicone: gateway, không phải thư viện

Helicone nằm giữa ứng dụng và provider. Bạn đổi base URL, thêm header, và mọi request đi qua đó đều được log, tính chi phí, có thể cache và rate-limit. Ưu điểm: không phải sửa logic agent, không phải chọn SDK theo framework. Nhược điểm: nó thấy toàn bộ prompt — một quyết định về dữ liệu, không chỉ về kỹ thuật.

# File: app/llm_client.py
from openai import OpenAI

client = OpenAI(
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {HELICONE_API_KEY}",
        "Helicone-Property-Tenant": tenant,
        "Helicone-Property-TaskType": "refund",
    },
)

So với code cũ dùng openai.api_base: thuộc tính module đó đã bị bỏ từ openai 1.x, nay SDK là 3.46.0 và cấu hình nằm trên client. Đây là loại lỗi làm integration “không chạy” mà không có thông báo rõ ràng.

Dùng Helicone khi bạn cần nhìn chi phí và lưu lượng nhanh, đặc biệt khi nhiều team gọi nhiều provider qua một cửa. Đừng dùng nó như lớp tracing duy nhất nếu agent có nhiều tool nội bộ: gateway không thấy được bước nào trong code bạn, chỉ thấy request HTTP.

OpenLLMetry: chuẩn hoá để không khoá vào nhà cung cấp

Nếu tổ chức đã có Datadog, Grafana, Honeycomb hay Jaeger, đừng dựng thêm một silo. OpenLLMetry tạo span OTel từ các thư viện LLM và framework, rồi đẩy qua OTLP đến collector hiện có:

# File: app/telemetry.py
# pip install traceloop-sdk
from traceloop.sdk import Traceloop

Traceloop.init(app_name="agent-api", disable_batch=False)
# Endpoint OTLP lấy từ biến môi trường của SDK OTel / collector,
# không hard-code trong repo.

Giá trị thật của con đường này là bạn dùng lại được alerting, retention, quyền truy cập, và chi phí hạ tầng đã có. Cái giá là bạn phải sống với spec còn Development: tên thuộc tính có thể đổi giữa các phiên bản semconv, dashboard có thể vỡ sau một lần nâng cấp. Pin semconv, viết test cho vài truy vấn quan trọng, và đừng giả định gen_ai.* là vĩnh viễn.

Đo gì trên mỗi bước

  • Token và chi phí: input, cached input, output, reasoning — bốn số riêng, vì reasoning bị tính như output và cache ghi cũng tốn tiền. Cộng dồn theo trace_id để có cost per task.
  • Độ trễ: p50 và p95 cho từng loại span. Trung bình che mất tail; tail mới là thứ khách hàng cảm nhận.
  • Lỗi tool: tỷ lệ lỗi theo tên tool, theo mã lỗi (429, 5xx, timeout, schema). Một tool lỗi 8% là vấn đề hợp đồng, không phải vấn đề model.
  • Số bước: phân phối step count. Đuôi dài bất thường là dấu hiệu loop; thêm phát hiện lặp bằng hash của (tên tool + tham số) xuất hiện quá 2 lần.
  • Chờ duyệt: thời gian từ lúc interrupt đến lúc resume. Đây là chỉ số vận hành, không phải chỉ số AI, nhưng ảnh hưởng trực tiếp đến SLA.

PII: che trước khi rời process

Đây là phần dễ sai nhất. Trace chứa prompt, prompt chứa dữ liệu khách, và mọi công cụ ở trên đều lưu nguyên văn nếu bạn không chặn. Nguyên tắc: che ở tầng instrumentation, trước khi dữ liệu ra khỏi process — không che trong UI, vì UI chỉ là một trong nhiều nơi đọc dữ liệu.

  • Allowlist trường được ghi thay vì denylist trường bị cấm. Danh sách cấm luôn thiếu.
  • Hash hoặc tokenize user id; giữ khoá map ở database của bạn, không ở công cụ trace.
  • Tắt ghi prompt/response cho tenant không có thoả thuận, hoặc chỉ ghi metadata và token count.
  • Đặt TTL theo loại dữ liệu: trace lỗi giữ lâu hơn trace thành công, nhưng cả hai đều phải có hạn.
  • Không đưa secret, API key, hoặc toàn bộ tool output vào span. Nếu cần debug, lưu tham chiếu tới object storage có kiểm soát truy cập.

Sampling: giữ cái đắt, bỏ cái nhàm

Ghi 100% trace ở quy mô lớn là tốn kém và vô ích: 95% lần chạy giống nhau. Dùng tail-based sampling — quyết định giữ sau khi trace kết thúc, dựa trên kết quả. Giữ 100% trace có lỗi, có cảnh báo, chậm hơn p95, hoặc vượt ngân sách token; giữ 5–10% trace thành công để làm baseline. Cách này giữ được tín hiệu và cắt được phần lớn chi phí lưu trữ.

Với công cụ chỉ hỗ trợ head sampling (lấy mẫu trước khi chạy), bạn phải chấp nhận mất một phần lỗi hiếm — và nên bù bằng alert trên metric thay vì alert trên trace.

Dashboard và alert: phần giám sát bạn thực sự dùng

Sáu chỉ số là đủ cho bản đầu: cost per task (p50/p95), token per task, tỷ lệ lỗi tool theo tên, p95 latency theo loại span, số task vượt ngân sách bước, và thời gian chờ duyệt. Alert nên đặt trên tốc độ thay đổi và ngưỡng nghiệp vụ, không trên từng sự kiện: “lỗi tool > 5% trong 15 phút”, “cost trung bình tăng 30% so với cùng giờ hôm qua”, “p95 vượt SLA 2 lần liên tiếp”.

Một dashboard có 40 biểu đồ là một dashboard không ai đọc. Bắt đầu bằng sáu, thêm khi có sự cố thật sự cần con số đó.

Cạm bẫy

Instrument mọi thứ. Mỗi span là một network call và một khoản lưu trữ. Bắt đầu từ span ở ranh giới quan trọng: mỗi lần gọi model, mỗi lần gọi tool, mỗi lần chờ người. Không cần span cho từng hàm Python.

Nhãn cardinality cao. Đừng đưa user_id hay order_id vào tag của metric; nó làm bùng nổ số series và chi phí backend. Chúng thuộc về span attribute, không thuộc metric label.

Lưu prompt chứa PII rồi xử lý sau. Xử lý sau là đã lộ. Che trước.

Nhầm tracing với monitoring. Có trace không có nghĩa có chỉ số; có chỉ số không có nghĩa tra được một lần chạy cụ thể. Cần cả hai, và cần một khoá chung (trace_id) để đi từ dashboard xuống trace.

Khoá vào SDK riêng. Nếu công cụ chỉ xuất dữ liệu qua SDK proprietary, bạn sẽ khó đổi. Ưu tiên công cụ xuất được OTLP; đó là lý do OpenLLMetry và Langfuse 5.x cùng nói chuyện được với hạ tầng OTel.

Chọn công cụ nào

  • Muốn tự host, cần trace + prompt + eval trong một UI: Langfuse 5.2.0.
  • Muốn nhìn chi phí ngay, nhiều provider, không sửa code agent: Helicone, chấp nhận prompt đi qua bên thứ ba.
  • Đã có stack OTel (Datadog/Grafana/Jaeger): OpenLLMetry + collector hiện có.
  • Cần cả ba: OpenLLMetry làm lớp instrumentation, OTLP vào collector nội bộ, và một backend chuyên cho LLM nếu bạn cần UI theo prompt. Không chạy hai lớp instrumentation cùng lúc — span sẽ trùng và chi phí tăng gấp đôi.

Nhìn trước 2027

OTel GenAI sẽ còn churn trong vài phiên bản nữa, nhưng hướng là rõ: agent span, MCP span và A2A span thành chuẩn, nghĩa là trace của bạn sẽ bắc qua cả ranh giới agent–tool–agent khác. Chuẩn bị trước bằng cách giữ trace_id xuyên suốt và không nhúng phụ thuộc vào một UI cụ thể. Về phía chi phí, dự báo giá token theo bậc (long-context, reasoning) sẽ buộc dashboard phải hiển thị chi phí theo bước, không chỉ theo tháng.

Checklist

  • Mỗi lần chạy có trace_id, tenant, task_type; mỗi span có step_index.
  • Span generation ghi đủ bốn loại token, không chỉ tổng.
  • Tên span theo quy ước cố định, có test cho hai truy vấn dashboard quan trọng.
  • PII được che trước khi export; có TTL cho từng loại trace.
  • Sampling kiểu tail-based: 100% lỗi, 5–10% thành công.
  • Sáu alert, mỗi alert có ngưỡng và người chịu trách nhiệm.

Để nối tiếp: bài đánh giá agent bằng LangSmith, Ragas và DeepEval dùng chính dữ liệu trace để xây dataset; bài kiểm thử agent AI cho bạn tầng khẳng định trước khi đo; và bài bảo mật agent AI giải thích vì sao trace chứa prompt là một bề mặt tấn công, không chỉ một kho dữ liệu.