Trace tool call bị lỗi của agent mà không bỏ sót hay đếm trùng lỗi

Đặt span của tool là ERROR kèm error.type khi tool lỗi hẳn, ghi exception đúng một lần, và giữ các lần retry dưới dạng span con hoặc event. Sau đó báo lỗi cuối cùng cho công cụ theo dõi lỗi từ chính đoạn code đưa lỗi đó cho model. Không có chỗ nào khác làm việc này: trong 60 lần chạy agent của mình, không lỗi nào tự đến được công cụ theo dõi lỗi.

Quy tắc của OpenTelemetry nói gì#

Các quy ước về lỗi khá ngắn (recording errors):

• Span kết thúc không lỗi thì để status ở trạng thái unset.
• Thao tác thất bại thì đặt status Error và error.type.
• Lỗi đã được “retried or handled”, tức đã retry hoặc đã xử lý, thì không nên đánh dấu thao tác là thất bại.
• Cùng một exception không nên được ghi quá một lần.

Đặc tả trace nói thêm khi nào gắn event exception: chỉ khi exception vẫn chưa được xử lý lúc span kết thúc (exceptions).

Với một agent, điều đó có nghĩa span của tool thất bại, còn span của agent thì không, vì agent đã xử lý lỗi bằng cách đưa nó cho model.

Một lần hoàn tiền lỗi, từng span một#

Ngày 26/10/2026, mình chạy một agent hỗ trợ khách hàng có tool refund_payment gọi tới nhà cung cấp thanh toán và retry một lần khi timeout. Khi nhà cung cấp sập, lần chạy nào cũng ra đúng cây span này:

Mỗi lần gọi thanh toán là một span CLIENT riêng và tự thất bại. Span của tool ghi hai event app.retry, rồi thất bại với một event exception. Span của agent vẫn unset và mang một event thường, ghi rằng nó đã chuyển lỗi cho model. Request trả về 200.

Cây span đó đúng, và cũng chính vì vậy mà lỗi bị bỏ qua. Bất cứ thứ gì chỉ theo dõi request thất bại, hay root span bị lỗi, đều thấy một lần chạy sạch sẽ.

Ba cách báo lỗi, đếm thử#

• Chỉ báo exception chưa xử lý, cách mà đa số cấu hình mặc định đang làm: 0 lỗi được báo, ở mọi tình huống.
• Báo một lần, trong handler xử lý lỗi của tool: 15 lỗi cho sự cố thanh toán và 25 cho bug trong code, mỗi loại gom thành một issue.
• Báo mọi exception đã bắt, tính cả từng lần thử: 45 cho sự cố thanh toán, cộng thêm 15 cho những lần timeout đã được retry khắc phục. Như vậy là gọi người dậy vì những vấn đề tự hết; bài đừng báo động cho mọi exception giải thích vì sao.

Bug trong code cho 25 lỗi từ 15 lần chạy vì hai trong ba model gọi hàm tra cứu bị hỏng hai lần trong mỗi lần chạy. Đếm theo error.type sẽ thấy ngay kiểu lặp này.

Handler, viết bằng code#

Trong vòng lặp agent của riêng bạn, hãy báo lỗi ở đúng chỗ bắt lỗi:

import sentry_sdktry:    result = execute_tool(call)except Exception as error:    sentry_sdk.capture_exception(error)  # một lần, cho lỗi cuối cùng    result = {"error": type(error).__name__}

Với OpenAI Agents SDK, handler mặc định trả cho model câu “An error occurred while running the tool. Please try again.” và mặc định chỉ ghi lỗi ở mức debug (mã nguồn Agents SDK). Truyền vào failure_error_function của riêng bạn để báo lỗi:

def report_tool_error(ctx, error: Exception) -> str:    sentry_sdk.capture_exception(error)    return "An error occurred while running the tool."@function_tool(failure_error_function=report_tool_error)def refund_payment(order_id: str, amount: float) -> dict: ...

Giữ vòng retry bên trong tool, và đừng báo gì cho những lần thử mà lần sau đã thành công.

Belvador giúp ở đâu#

Cấu hình Python của Belvador dùng sentry-sdk chính thức với DSN Belvador của bạn, nên capture_exception trong handler gửi một event, và node gom các lần lặp lại thành một issue (hướng dẫn Python). Belvador không tạo span và không biến exception bên trong span thành issue; trace đến qua OTLP và nằm cạnh lỗi trên node của bạn, như tổng quan OpenTelemetry mô tả. Cảnh báo bắn khi có issue mới, lỗi quay lại hoặc số lỗi tăng đột ngột, không phải cho từng event.

Để nhìn bức tranh lớn hơn, xem observability cho AI agent. Bài OpenTelemetry GenAI conventions thực tế nói về các attribute trên những span ở trên.

Đọc tiếp#

• Observability cho AI agent: những lỗi vẫn trả về 200
• OpenTelemetry GenAI conventions thực tế: thứ gì thật sự được ghi
• Đừng báo động cho mọi exception: một ngày nhiều lỗi, bốn cách cảnh báo