Một người dùng báo cáo rằng tác nhân (agent) “đã làm điều gì đó lạ” vào chiều hôm qua. Bạn mở nhật ký (log) và thấy điều này:
INFO agent run started
INFO calling tool: updateOrder
INFO tool returned 200
INFO agent run completed
Tác nhân đã gọi updateOrder. Bạn không biết với những đối số nào, chống lại lệnh nào, tại sao nó chọn công cụ đó, hoặc điều gì đã trả về. Lần chạy đã thành công theo mọi thước đo bạn ghi lại, và bạn không thể tái tạo bất kỳ quyết định nào mà nó đã đưa ra.
Các hệ thống tác nhân thường thất bại theo những cách mà chỉ có ý nghĩa khi nhìn lại, điều đó có nghĩa là nhật ký là sản phẩm. Hướng dẫn này bao gồm những gì cần ghi lại trong mỗi lần gọi công cụ, cách tương quan quyết định của mô hình với yêu cầu HTTP mà nó tạo ra, những gì cần biên tập (redact), và cách biến dấu vết (traces) thành các bài kiểm tra. Bài viết của chúng tôi về khả năng quan sát API đề cập đến phía dịch vụ; bài viết này đề cập đến lớp tác nhân nằm trên đó.
Apidog rất hữu ích khi bạn có một dấu vết, bởi vì cách nhanh nhất để hiểu một cuộc gọi sai là phát lại nó với cùng một điểm cuối và xem điều gì xảy ra.
Ba lớp, một dấu vết
Một tác nhân tạo ra các sự kiện ở ba cấp độ, và hầu hết các nhóm chỉ ghi lại cấp độ ở giữa.
Lớp suy luận (reasoning layer) là nơi mô hình đưa ra quyết định. Những gì có trong ngữ cảnh, những công cụ nào được cung cấp, công cụ nào nó đã chọn và với những đối số nào.
Lớp công cụ (tool layer) là trình thực thi của bạn. Nó xác thực các đối số, áp dụng chính sách, ánh xạ cuộc gọi đến một yêu cầu HTTP và xử lý kết quả.
Lớp HTTP (HTTP layer) là đường truyền. Phương thức, URL, tiêu đề, nội dung, trạng thái, độ trễ.
Gỡ lỗi gần như luôn liên quan đến nhiều lớp. “Tác nhân đã gửi sai ID khách hàng” là một vấn đề về suy luận chỉ hiển thị ở lớp HTTP. “API trả về mã 200 với nội dung trống” là một vấn đề HTTP xuất hiện dưới dạng suy luận kỳ lạ ba bước sau đó. Nếu ba lớp không được liên kết với nhau bằng một định danh chung, bạn sẽ phải tương quan theo dấu thời gian, điều này sẽ ngừng hoạt động ngay khi hai lần chạy chồng chéo.
Vì vậy, quy tắc đầu tiên: một ID dấu vết cho mỗi lần chạy tác nhân, một ID span cho mỗi lần gọi công cụ, và cả hai đều được đóng dấu trên mọi bản ghi ở mọi lớp. Dấu vết OpenTelemetry đã mô hình hóa chính xác hình dạng này, và có một bộ quy ước ngữ nghĩa GenAI ngày càng tăng để đặt tên các thuộc tính để dữ liệu của bạn có thể di chuyển được.
Ghi lại những gì trong mỗi lần gọi công cụ
Một bản ghi trả lời các câu hỏi thực tế có hình dạng đại khái như sau:
{
"trace_id": "run_01J8ZK3M2Q",
"span_id": "call_004",
"parent_span_id": "call_003",
"timestamp": "2026-08-26T14:03:11.482Z",
"agent": "billing",
"step": 4,
"tool_name": "refundOrder",
"tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
"tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],
"http": {
"method": "POST",
"url": "/v1/orders/ord_92/refund",
"request_body_hash": "sha256:1f4c...",
"status": 200,
"duration_ms": 412,
"retry_count": 1,
"idempotency_key": "9f2b7c14-6d3a-4b18"
},
"outcome": "success",
"tokens": { "prompt": 8420, "completion": 96 },
"policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}
Năm trường đóng vai trò quan trọng.
tool_args là trường thường bị thiếu nhất, và đó là trường bạn luôn muốn có. Hãy ghi lại các đối số mà mô hình đã tạo ra, trước khi trình thực thi của bạn chuẩn hóa chúng. Khi một tác nhân gửi sai ID, đây là nơi nó được nhìn thấy.
tools_available giải thích việc lựa chọn. Nếu mô hình chọn một công cụ kỳ lạ, câu hỏi đầu tiên là nó còn những lựa chọn nào khác. Trường này tốn vài byte và trả lời ngay lập tức.
retry_count phân biệt giữa “API chậm” và “API đã thất bại hai lần rồi hoạt động.” Nếu không có nó, ba lần thử trông giống như một cuộc gọi.
outcome nên là một enum rõ ràng, không phải là thứ được suy ra từ mã trạng thái. success, failed, timed_out, blocked_by_policy, rejected_by_human. Hai loại cuối cùng quan trọng vì một cuộc gọi bị chặn là một hàng rào bảo vệ đang hoạt động, không phải là lỗi, và việc trộn lẫn chúng sẽ làm sai lệch tỷ lệ thất bại của bạn.
policy là dấu vết kiểm toán của bạn. Khi ai đó hỏi liệu một hành động gây phá hủy có được chấp thuận hay không, đây là câu trả lời. Nó kết hợp với việc thực thi được mô tả trong bài viết của chúng tôi về các hàng rào bảo vệ tác nhân AI.
Ghi lại quyết định, không chỉ hành động
Các lỗi tác nhân khó nhất là các lựa chọn, vì vậy hãy ghi lại đủ để tái tạo chúng.
Giữ lại định nghĩa công cụ được sử dụng cho lần chạy, hoặc một mã băm của chúng. Khi độ chính xác lựa chọn thay đổi, nghi phạm đầu tiên là một mô tả mà ai đó đã chỉnh sửa, và một mã băm cho bạn biết ngay lập tức liệu bộ công cụ có thay đổi giữa một lần chạy tốt và một lần chạy lỗi hay không. Bài viết của chúng tôi về thiết kế lược đồ công cụ đề cập lý do tại sao văn bản đó lại thay đổi hành vi nhiều đến vậy.
Ghi lại mô hình và cài đặt của nó. ID mô hình, nhiệt độ (temperature), và phiên bản lời nhắc (prompt version) thuộc về bản ghi lần chạy. Hành vi thay đổi giữa các phiên bản mô hình, và nếu không có trường này, bạn sẽ mất một ngày để điều tra mã của chính mình.
Ghi lại những gì mô hình đã thấy, hoặc ít nhất là kích thước của nó. Một bản ghi đầy đủ của lời nhắc (prompt dump) tốn kém để lưu trữ và thường nhạy cảm. Một số lượng token cộng với một mã băm mang lại cho bạn hầu hết giá trị chẩn đoán: một lần chạy có lời nhắc lớn gấp đôi kích thước thông thường là một lần chạy mà có điều gì đó đã được thêm vào mà không nên có.
Ghi lại kết quả công cụ thô trước khi cắt bớt. Nếu trình thực thi của bạn chiếu các phản hồi xuống trước khi chuyển chúng cho mô hình, như trong bài viết của chúng tôi về giữ phản hồi công cụ khỏi cửa sổ ngữ cảnh, hãy lưu trữ toàn bộ payload trong dấu vết. Nếu không, bạn không thể biết liệu dữ liệu bị thiếu hay bạn đã bỏ nó.
Biên tập trước khi lưu trữ
Dấu vết tác nhân đặc biệt nguy hiểm vì chúng chứa cả yêu cầu và lý do xung quanh nó, và các lời nhắc có thói quen thu thập dữ liệu cá nhân.
Bốn quy tắc giúp quản lý điều này.
Không bao giờ lưu trữ thông tin xác thực. Loại bỏ Authorization, khóa API, cookie và bất kỳ URL đã ký nào. Ghi lại định danh của thông tin xác thực, chẳng hạn như ID khóa, chứ không phải giá trị. Bài viết của chúng tôi về khóa API đặc quyền tối thiểu cho tác nhân đề cập lý do bạn muốn định danh đó: nó cho bạn biết tác nhân nào đã hành động.
Biên tập ở ranh giới, không phải trong truy vấn. Lọc tại thời điểm đọc có nghĩa là bí mật đã được ghi vào đĩa, sao chép và sao lưu. Hãy biên tập trong middleware ghi nhật ký trước khi bản ghi rời khỏi tiến trình.
Mã băm các nội dung mà bạn không thể lưu trữ. Mã băm nội dung yêu cầu vẫn cho phép bạn chứng minh hai cuộc gọi là giống hệt nhau, điều này là phần lớn những gì bạn cần cho các cuộc điều tra trùng lặp, mà không cần giữ lại payload.
Đặt thời gian lưu trữ theo độ nhạy cảm. Dấu vết đầy đủ trong một tuần, tóm tắt đã biên tập trong một năm. Hầu hết việc gỡ lỗi diễn ra trong vài ngày; hầu hết các câu hỏi kiểm toán đến trong vòng vài tháng.
Biến dấu vết thành các bài kiểm tra
Lợi ích của việc theo dõi tốt không chỉ là gỡ lỗi nhanh hơn. Đó còn là nguồn cung cấp các trường hợp kiểm thử thực tế.
Mỗi lần chạy thất bại là một kịch bản. Lấy các lệnh gọi công cụ từ một dấu vết lỗi, phát lại chúng đối với API của bạn, và bạn có một bản tái tạo lỗi. Khi bản sửa lỗi được triển khai, hãy giữ bản phát lại làm bài kiểm thử hồi quy. Trong Apidog, bạn có thể xây dựng lại yêu cầu lỗi dưới dạng một trường hợp đã lưu, xác nhận hành vi đã sửa và chạy nó trong CI, đây là cách một sự cố đơn lẻ biến thành phạm vi bảo hiểm vĩnh viễn.
Dấu vết cũng cho bạn biết những gì cần giả lập (mock). Các điểm cuối mà tác nhân của bạn gọi nhiều nhất, và các trạng thái lỗi mà nó thực sự gặp phải, đến trực tiếp từ dữ liệu thay vì phỏng đoán. Xây dựng các giả lập xung quanh những điều đó, theo bài viết của chúng tôi về chạy tác nhân với giả lập thay vì môi trường sản xuất.
Và chúng làm lộ ra những thay đổi chậm mà bạn có thể bỏ lỡ. Theo dõi một vài con số mỗi tuần: phân phối lựa chọn công cụ, tỷ lệ thử lại trên mỗi điểm cuối, số lần gọi trên mỗi tác vụ hoàn thành, và phần trăm các lần chạy bị chặn bởi chính sách. Một sự thay đổi trong bất kỳ chỉ số nào trong số đó là một tín hiệu trước khi nó trở thành một sự cố. Các kiểm tra ở cấp hợp đồng, như trong hướng dẫn kiểm thử hợp đồng API của chúng tôi, phát hiện ra sự thay đổi ở thượng nguồn thường gây ra nó.
Ba cuộc điều tra mà dấu vết phải tồn tại
“Tác nhân đã tính phí sai khách hàng.” Bạn cần các đối số mà mô hình đã tạo ra, URL đã được giải quyết và bước trước đó. Chín trong mười lần, ID đến từ một kết quả công cụ trước đó đã trả về nhiều hơn một kết quả khớp và mô hình đã chọn cái đầu tiên. Dấu vết cho thấy kết quả trước đó, sự mơ hồ và lựa chọn. Nếu không có tool_args, bạn sẽ có một mã 200 và một khách hàng rất không hài lòng.
“Nó ngừng hoạt động vào thứ Ba.” So sánh một lần chạy tốt và một lần chạy lỗi từng trường một. ID mô hình, mã băm bộ công cụ, phiên bản lời nhắc, kích thước phản hồi trung bình. Có điều gì đó đã thay đổi, và một trong bốn yếu tố đó thường cho biết đó là gì. Đây là lý do tại sao bản ghi lần chạy mang theo cấu hình chứ không chỉ các sự kiện: sự khác biệt chỉ có thể xảy ra khi cả hai bên ghi lại cùng các trường.
“Có ai đã phê duyệt việc này không?” Khối chính sách là toàn bộ câu trả lời, và nó phải được ghi lại tại thời điểm đưa ra quyết định, chứ không phải tái tạo sau này. approval_required, approved_by, và một dấu thời gian biến một cuộc đối thoại căng thẳng thành một tìm kiếm.
Hãy chú ý đến điểm chung của những điều này. Không có câu hỏi nào trong số đó được trả lời bằng “công cụ trả về 200.” Cả ba đều được trả lời bằng các trường tốn gần như không gì để ghi và không thể phục hồi sau khi sự việc đã xảy ra.
Lấy mẫu, và những gì không bao giờ nên lấy mẫu
Theo dõi đầy đủ độ trung thực trên mỗi lần chạy sẽ trở nên tốn kém khi khối lượng lớn, vì vậy các nhóm thực hiện lấy mẫu. Hãy lấy mẫu cẩn thận, vì lưu lượng tác nhân không đồng nhất.
Luôn giữ lại mọi lần chạy thất bại, mọi lần chạy gặp chặn chính sách và mọi lần chạy chứa thao tác ghi. Đó là những lần chạy mà bất kỳ ai cũng sẽ hỏi. Hãy lấy mẫu các lần chạy chỉ đọc thành công, vì chúng chiếm phần lớn khối lượng và ít thú vị nhất xét riêng lẻ, mặc dù bạn vẫn muốn có đủ chúng để tính toán các đường cơ sở của mình.
Chương về giám sát hệ thống phân tán trong sách SRE của Google vẫn là tuyên bố rõ ràng nhất về lý do bạn lấy mẫu theo tín hiệu hơn là theo khối lượng, và lý do này áp dụng trực tiếp.
Giữ lại bản ghi lần chạy ngay cả khi bạn loại bỏ các payload. Một dấu vết sườn với tên công cụ, kết quả và thời lượng là nhỏ và vẫn hỗ trợ bốn số liệu trên. Các phần tốn kém là nội dung và lời nhắc, và đó là những phần bạn có thể loại bỏ trước tiên.
Một cảnh báo về lấy mẫu đuôi (tail sampling): nếu bạn quyết định giữ lại gì sau khi một lần chạy kết thúc, hãy đảm bảo rằng quyết định đó xảy ra sau khi kết quả đã được biết. Một lần chạy trông ổn ở bước ba và thất bại ở bước chín phải được giữ lại hoàn toàn, điều này có nghĩa là đệm thay vì loại bỏ khi bạn tiến hành.
Nơi dấu vết nên được lưu trữ
Tất cả những điều trên đều giả định bạn sở hữu bộ lưu trữ. Đó là giả định đúng khi tác nhân là dịch vụ của riêng bạn đang gọi các API của riêng bạn. Nó không phù hợp khi các tác nhân là môi trường chạy mã trên máy của nhà phát triển, bởi vì dấu vết sau đó nằm ở bất kỳ thiết bị đầu cuối nào đã chạy nó.
Sharkly áp dụng một cách tiếp cận khác: dấu vết thực thi được gắn vào Nhiệm vụ mà tác nhân được giao. Lịch sử chạy, nhật ký thực thi và kết quả nằm cạnh mục tiêu, trạng thái và chuỗi bình luận nơi con người đã xem xét công việc. Sự khác biệt thực tế là ở việc truy xuất. “Tại sao tác nhân lại làm điều đó” trở thành một câu hỏi bạn trả lời bằng cách mở nhiệm vụ, thay vì tìm máy, phiên và lịch sử cuộn lại.
Nó không thay thế việc theo dõi được mô tả ở đây, và nó cũng không thay thế môi trường thời gian chạy; Claude Code và Codex vẫn thực hiện công việc. Điều nó thay đổi là nơi bản ghi kết thúc khi tác nhân không phải là một dịch vụ mà bạn đã triển khai.
Theo dõi bốn con số
Dấu vết chỉ hữu ích nếu có ai đó xem xét. Bốn con số này xứng đáng có mặt trên bảng điều khiển.
Số lần gọi trên mỗi tác vụ hoàn thành. Thước đo hiệu quả rõ ràng nhất. Nếu nó tăng lên, tác nhân đang khám phá nhiều hơn, thường là do mô tả kém hơn hoặc một điểm cuối bắt đầu gặp lỗi.
Tỷ lệ thử lại theo điểm cuối. Xếp hạng các phụ thuộc ít đáng tin cậy nhất của bạn và cho thấy khi nào một điểm cuối bị suy giảm. Bài viết của chúng tôi về phục hồi lỗi tác nhân đề cập đến những gì cần làm với các mục hàng đầu của danh sách đó.
Tỷ lệ bị chặn bởi chính sách. Nên thấp và ổn định. Một sự tăng vọt có nghĩa là tác nhân đang thử những điều không nên, hoặc một chính sách quá chặt chẽ và hiện đang là nút cổ chai.
Thời gian đến lần gọi công cụ đầu tiên. Một khởi đầu chậm thường có nghĩa là một lời nhắc bị phình to, và kích thước lời nhắc là thứ phát triển mà không ai quyết định làm cho nó phát triển.
Danh sách kiểm tra
- Một ID dấu vết cho mỗi lần chạy, một ID span cho mỗi lần gọi công cụ, được đóng dấu ở cả ba lớp.
- Các đối số mô hình được ghi nhật ký trước khi chuẩn hóa.
- Danh sách công cụ có sẵn được ghi lại trong mỗi cuộc gọi.
- Kết quả được ghi lại dưới dạng một enum rõ ràng, bao gồm cả các khối chính sách.
- Số lần thử lại riêng biệt với số lần gọi.
- Mô hình, nhiệt độ, phiên bản lời nhắc và mã băm bộ công cụ trên bản ghi lần chạy.
- Lưu trữ kết quả công cụ thô, không chỉ phiên bản đã cắt bớt được chuyển cho mô hình.
- Thông tin xác thực được loại bỏ trong middleware, các phần thân được băm khi không thể lưu trữ.
- Thời gian lưu trữ được phân cấp theo độ nhạy cảm.
- Các dấu vết lỗi có thể chuyển đổi thành các trường hợp kiểm thử có thể phát lại.
Mục tiêu rất đơn giản: khi ai đó hỏi tại sao tác nhân lại làm điều đó, bạn có thể trả lời từ bản ghi thay vì phỏng đoán. Tải Apidog để phát lại các cuộc gọi trong một dấu vết và giữ lại các bản tái tạo làm bài kiểm tra.
Các câu hỏi thường gặp
Tôi nên sử dụng OpenTelemetry hay một công cụ quan sát tác nhân chuyên dụng? Sử dụng OpenTelemetry cho việc vận chuyển và mô hình dấu vết, vì nó đã xử lý việc tương quan và cơ sở hạ tầng của bạn có thể hiểu nó. Các công cụ chuyên biệt cho tác nhân bổ sung các chế độ xem hữu ích; dữ liệu bên dưới vẫn nên có thể di chuyển được.
Chi phí lưu trữ đầy đủ dấu vết là bao nhiêu? Ít hơn mọi người mong đợi, nếu bạn phân cấp. Các payload đầy đủ trong vài ngày và các bản ghi có cấu trúc không kèm nội dung trong thời gian dài hơn sẽ giữ cho hầu hết khối lượng ở mức thấp. Các bản ghi lời nhắc là phần tốn kém, vì vậy hãy băm và đo kích thước chúng thay vì lưu trữ chúng theo mặc định.
Tôi có cần ghi lại văn bản suy luận của mô hình không? Thông thường là không. Công cụ nó đã chọn, các đối số nó đã tạo ra và các lựa chọn nó có sẽ giải thích hầu hết các quyết định. Nơi nhà cung cấp tiết lộ nội dung suy luận, hãy lưu trữ nó chỉ cho các lần chạy thất bại và coi đó là dữ liệu nhạy cảm.
Làm cách nào để theo dõi qua nhiều tác nhân? Giữ một ID dấu vết cho toàn bộ tác vụ và cấp cho mỗi tác nhân một span riêng, với việc chuyển giao được ghi lại dưới dạng một sự kiện. Bài viết của chúng tôi về chuyển giao đa tác nhân bao gồm những gì thuộc về bản ghi chuyển giao đó.
Điều gì sẽ xảy ra nếu tác nhân chạy trên máy của khách hàng? Ghi nhật ký cục bộ, biên tập tích cực và chỉ gửi các số liệu tổng hợp trừ khi người dùng đồng ý. Tên công cụ, kết quả và thời lượng thường đủ cho việc giám sát cấp độ đội ngũ mà không cần bất kỳ payload nào rời khỏi thiết bị.
Mã băm nội dung yêu cầu có thực sự hữu ích không? Có, đối với hầu hết các câu hỏi phổ biến. Nó chứng minh hai cuộc gọi là giống hệt nhau, giúp giải quyết hầu hết các cuộc điều tra ghi trùng lặp, mà không cần giữ lại chính payload. Kết hợp nó với các khóa bất biến (idempotency keys) lẽ ra đã ngăn chặn sự trùng lặp đó.