Một buổi chiều thứ Ba. Mười hai lượt biến thành một phiên gỡ lỗi, và tác nhân tự tin nói với tôi rằng điểm cuối /users của chúng tôi đang phản hồi trong bốn mươi bảy giây. Con số thực tế là bốn mươi bảy mili giây.
Tôi đã tìm kiếm lỗi này trong hai ngày. Mỗi khi tôi thêm một câu lệnh in vào máy chủ MCP, câu trả lời của tác nhân lại thay đổi đủ để khiến tôi nghĩ rằng mình đang đi đúng hướng. Mỗi khi tôi viết lại lời nhắc hệ thống, phản hồi nghe có vẻ hợp lý hơn. Nhưng không cái nào đúng cả.
Điều mà tôi chưa làm, cho đến buổi chiều hôm đó, là mở vết thực thi thực tế và xem những gì đang được truyền giữa mô hình và công cụ. Đó là mục đích của AI Agent Debugger của Apidog. Tôi đã cài đặt nó ba tuần trước đó và quên mất. Mất mười hai phút để tìm ra lỗi.
Đây là điều làm tôi ngạc nhiên.
Lỗi mà tôi đã tìm kiếm
Thiết lập rất đơn giản. Một tác nhân được xây dựng trên GPT-5.5. Một máy chủ MCP tôi viết trong một cuối tuần, hiển thị công cụ get_response_time(endpoint) để truy vấn đường dẫn số liệu của chúng tôi. Một lời nhắc hệ thống khoảng bốn mươi từ. Lời nhắc người dùng: “Điểm cuối /users nhanh đến mức nào?”
Tác nhân trả lời nhanh. Nó trả lời tự tin. Nó trả lời sai, mỗi lần một kiểu khác nhau. Đôi khi là “điểm cuối đang phản hồi trong 47 giây.” Đôi khi là “khoảng 0.05 giây.” Một lần, đáng nhớ, “hiệu suất chấp nhận được.”
Tôi đã làm những việc cần làm. Thêm ghi log vào máy chủ MCP. Đọc phản hồi của mô hình từng token một. So sánh các lời nhắc hệ thống. Chửi thề. Tôi có ba cửa sổ terminal đang mở và một trang Notion chứa các giả thuyết thất bại vào sáng thứ Ba.
Điều khó khăn khi gỡ lỗi tác nhân là lỗi hiếm khi ở nơi bạn tìm kiếm đầu tiên. Nó có thể nằm trong lời nhắc hệ thống, trong lựa chọn mô hình, trong định nghĩa công cụ, trong các tham số mà mô hình truyền cho công cụ, trong dữ liệu mà công cụ trả về, hoặc trong cách mô hình giải thích dữ liệu đó. Sáu vị trí. Một console log chỉ cho bạn thấy một.
Bảng Traces thực sự hiển thị điều gì
Trình gỡ lỗi Apidog mở ra ba cột. Các phiên (Sessions) ở bên trái. Các lượt (Turns) ở giữa. Các vết (Traces) ở bên phải. Nhấp vào bất kỳ phiên nào và cột giữa sẽ hiển thị cho bạn hội thoại: tin nhắn người dùng, phản hồi mô hình, lệnh gọi công cụ, kết quả công cụ, phản hồi mô hình tiếp theo. Nhấp vào bất kỳ lượt nào và cột bên phải sẽ mở rộng thành cây thực thi đầy đủ bên dưới.
Cây thực thi là phần mà tôi đã bỏ lỡ. Mọi bước, theo thứ tự:
- Lời nhắc hệ thống như mô hình đã nhận
- Lời nhắc người dùng như mô hình đã nhận
- Tên và tham số lệnh gọi công cụ, dưới dạng JSON, chính xác như mô hình đã phát ra
- Dữ liệu trả về của công cụ, dưới dạng JSON, chính xác như công cụ đã trả về
- Phản hồi mô hình, với thời gian và token cho lượt đó
Tôi mở phiên bị lỗi. Lệnh gọi công cụ trông ổn: get_response_time(endpoint="/users"). Mô hình đã chọn đúng công cụ với đúng đối số.
Sau đó tôi mở rộng kết quả công cụ.
{"value": 47, "p95": 89, "samples": 1240}
Nó đây rồi. Đường dẫn số liệu trả về giá trị theo mili giây. Mô hình lại giả định là giây. 47 trở thành “47 giây” thông qua một 'ảo giác' tự tin mà không bận tâm đến việc nghi vấn đơn vị. Công cụ thì đúng. Mô hình thì sai. Lời nhắc hệ thống của tôi không có hướng dẫn về đơn vị, và phản hồi của công cụ cũng không có chú thích đơn vị.
Mười hai phút kể từ khi mở trình gỡ lỗi. Hai ngày tôi đã đổ lỗi cho lời nhắc hệ thống.
Sửa lỗi mất sáu dòng
Tôi đã thay đổi hai điều. Trong máy chủ MCP, tôi đã cập nhật cấu trúc phản hồi:
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Sau đó tôi thêm một câu vào lời nhắc hệ thống: “Kết quả công cụ trả về đơn vị một cách rõ ràng. Hãy đọc kỹ chúng.”
Tôi đã chạy lời nhắc /users tương tự thêm ba lần nữa. Ba phiên khác nhau trên bảng điều khiển bên trái. Cả ba đều trả về chính xác “điểm cuối đang phản hồi khoảng 47 ms” với phân tích từ mili giây đến phân vị trong lý luận của mô hình. Chi phí token thấp hơn mười tám phần trăm so với các lần chạy thất bại của tôi, có lẽ vì mô hình không tạo ra văn bản phục hồi xung quanh những giả định sai lầm của chính nó.
Tôi đã chạy cùng lời nhắc trên Claude Opus 4.7 trong một phiên thứ hai, song song. Kết quả tương tự, chi phí gấp đôi, dài dòng hơn một chút. Tôi biết mô hình nào sẽ được đưa vào sản xuất.
Đây là phần của công cụ khiến tôi phải nể phục. Không phải việc tìm lỗi, điều mà bất kỳ trình gỡ lỗi nào cũng nên làm. Mà là khả năng so sánh mô hình, chạy trên các cấu hình giống hệt nhau với các số liệu tóm tắt ở bảng bên trái: số lượt, số bước, thời gian, token, đô la. Tôi đã thực hiện việc so sánh đó trong một Google Sheet suốt sáu tháng. Giờ thì chỉ cần ba cú nhấp chuột.
Điều tôi đã làm sai
Cách nghĩ đơn giản là AI Agent Debugger là một công cụ ghi log. Không phải. Các công cụ ghi log cho bạn thấy điều gì đã xảy ra. Trình gỡ lỗi cho bạn thấy những gì mô hình và công cụ thực sự đã trao đổi, đó là một lớp khác biệt.
Nếu bạn viết tác nhân và bạn đã làm những gì tôi đã làm, đó là đọc đầu ra của mô hình và đoán nguyên nhân thất bại, thì đây là điều tôi sẽ phản đối. Bạn không gỡ lỗi tác nhân. Bạn đang gỡ lỗi giả thuyết của mình về tác nhân. Đó là những điều khác nhau, và chỉ một trong số đó giúp bạn đến được giải pháp.
Điều mà tôi đã từ chối tiếp thu trong sáu tháng là tác nhân là một hệ thống khép kín giữa mô hình, lời nhắc, các công cụ và các phản hồi công cụ. Lỗi luôn nằm trong một trong bốn yếu tố đó. Nếu bạn có thể nhìn thấy cả bốn cùng một lúc, bạn có thể tìm thấy lỗi trong mười hai phút. Nếu không, bạn có thể tìm kiếm nó trong một tuần.
Một điều khác mà trình gỡ lỗi đã phát hiện, điều mà tôi không ngờ tới, là tính không xác định trong chính tác nhân của tôi. Tôi đã chạy cùng một lời nhắc năm lần sau khi sửa lỗi, chỉ để xác nhận. Ba lần chạy gọi get_response_time một lần. Hai lần chạy gọi nó hai lần, lần thứ hai với đường dẫn điểm cuối có chữ hoa khác. Lược đồ công cụ của tôi phân biệt chữ hoa chữ thường. Tôi đã không nhận ra vì tất cả các trường hợp kiểm tra thất bại của tôi đều sử dụng chữ thường. Đó là một lỗi thứ hai mà tôi đã có thể đưa vào sản phẩm mà không hề hay biết.
Phân tích đa lần chạy là tính năng tôi sẽ sử dụng nhiều nhất trong tương lai. Nhấp chạy năm lần. Nhìn vào bảng điều khiển các phiên. Bất cứ điều gì thay đổi qua các lần chạy đều là điểm yếu của tác nhân của bạn.
Hãy tự mình thử: hướng dẫn thiết lập đầy đủ
Nếu bạn muốn thiết lập tương tự như tôi đã sử dụng trong quá trình tìm lỗi, đây là đường dẫn từ cài đặt mới đến một phiên gỡ lỗi đang chạy. Năm màn hình, theo thứ tự.
Bước 1: Tạo một phiên gỡ lỗi tác nhân mới
Mở Apidog và nhấp vào AI Agent Debugger trên thanh tab trên cùng. Phần trên của trang cấu hình mô hình và trạng thái chạy.
- Chọn nhà cung cấp mô hình ở bên trái (OpenAI, Anthropic và các nhà cung cấp khác)
- Chọn mô hình cụ thể ở giữa, ví dụ
gpt-5.5 - URL cơ sở sẽ tự động điền khi nhà cung cấp được chọn, không cần nhập thủ công
- Nhấp Run để bắt đầu một phiên
Bước 2: Cấu hình lời nhắc
Tab Prompts có hai khu vực nhập liệu.
- Lời nhắc hệ thống (System Prompt): xác định vai trò, mục tiêu, ràng buộc và quy tắc sử dụng công cụ của tác nhân
- Lời nhắc người dùng (User Prompt): đầu vào thử nghiệm cho phiên này, ví dụ “Apidog là gì?”
Nhấp Run ở phía trên bên phải khi cả hai đã được thiết lập. Nếu bạn muốn hộp nhập liệu tự động xóa sau mỗi lần chạy, hãy chọn Xóa sau khi gửi (Clear after Send).
Bước 3: Cấu hình công cụ
Tab Công cụ (Tools) liệt kê tất cả những gì tác nhân có thể gọi trong thời gian chạy. Con số trên tab là số lượng công cụ khả dụng hoặc đã cấu hình hiện tại.
Công cụ tích hợp sẵn được cung cấp kèm theo trình gỡ lỗi. Bật hoặc tắt chúng tùy theo nhu cầu.
| Công cụ | Chức năng |
|---|---|
bash |
Thực thi lệnh trong một phiên shell liên tục |
web_fetch |
Lấy nội dung web và chuyển đổi sang Markdown, văn bản hoặc HTML |
read |
Đọc các tệp văn bản, hình ảnh hoặc PDF |
edit |
Áp dụng thay thế chuỗi chính xác vào các tệp |
write |
Tạo hoặc ghi đè các tệp |
grep |
Tìm kiếm nội dung tệp bằng biểu thức chính quy |
glob |
Tìm kiếm tệp bằng các mẫu glob |
kill_shell |
Đặt lại phiên shell hiện tại |
Công cụ MCP thêm các hệ thống bên ngoài hoặc khả năng tùy chỉnh thông qua Máy chủ MCP. Ba phương pháp kết nối:
- STDIO: khởi chạy một tiến trình Máy chủ MCP cục bộ
- HTTP: kết nối với Máy chủ MCP hỗ trợ HTTP có thể truyền phát (Streamable HTTP)
- SSE: kết nối với Máy chủ MCP dựa trên Server-Sent Events
Các Máy chủ MCP yêu cầu xác thực chấp nhận các tiêu đề yêu cầu hoặc luồng OAuth 2.0. Khi kết nối thành công, hãy chọn công cụ nào mà máy chủ hiển thị cho tác nhân.
Bước 4: Cấu hình kỹ năng, xác thực và tham số mô hình
Ba tab nhỏ hơn hoàn thành việc thiết lập.
- Kỹ năng (Skills): các quy trình làm việc có thể tái sử dụng cho tác nhân. Hữu ích cho các quy trình làm việc dự án cố định, thông số kỹ thuật hoạt động nhiệm vụ chung và giảm văn bản dài lặp lại trong lời nhắc hệ thống. Kỹ năng được tải khi cần thiết trong thời gian chạy.
- Xác thực (Authentication): thông tin xác thực cần thiết bởi các dịch vụ mô hình hoặc dịch vụ MCP.
- Cài đặt (Settings): các tham số thời gian chạy của mô hình như Temperature, Max Tokens và Top P. Các tham số được hỗ trợ khác nhau tùy theo nhà cung cấp, vì vậy hãy kiểm tra xem mô hình của bạn thực sự chấp nhận những gì.
Bước 5: Đọc ba bảng điều khiển
Sau khi nhấp Run, phiên bạn vừa tạo sẽ xuất hiện ở bảng điều khiển bên trái. Mỗi phiên hiển thị một tóm tắt một dòng:
Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
- Bảng điều khiển Phiên (Sessions panel) (bên trái): lịch sử của mọi lần chạy với các số liệu tóm tắt
- Bảng điều khiển Lượt (Turns panel) (ở giữa): mỗi vòng đối thoại giữa người dùng/mô hình. Nhấp vào một vòng để tải chi tiết thực thi của nó ở bên phải.
- Bảng điều khiển Vết (Traces panel) (bên phải): chuỗi thực thi đầy đủ của tác nhân theo thứ tự, bao gồm lời nhắc hệ thống và người dùng, mọi lệnh gọi mô hình, quá trình suy nghĩ của mô hình nếu mô hình hiển thị, các lệnh gọi công cụ MCP và các thực thi Kỹ năng tùy chỉnh, các tham số đầu vào công cụ, kết quả, thời gian tiêu thụ, thông báo lỗi và đầu ra cuối cùng.
Khi một lệnh gọi công cụ thất bại hoặc mô hình trả về một ngoại lệ, bước bị lỗi sẽ hiển thị ngay trên bảng điều khiển Traces với đầu vào và đầu ra của nó. Không cần phải đào sâu log.
Bước 6: So sánh hiệu suất mô hình
Cùng lời nhắc, cùng cấu hình công cụ, mô hình khác nhau. Mỗi lần chạy tạo một phiên mới và bảng điều khiển bên trái cho phép bạn so sánh chúng song song.
Các số liệu hữu ích để so sánh:
- Số bước thực thi cho cùng một tác vụ
- Mô hình nào chọn công cụ chính xác hơn
- Mô hình nào có thời gian phản hồi thấp hơn
- Mô hình nào giữ mức tiêu thụ token và chi phí dễ dự đoán hơn
Bài học rút ra
Hai ngày gỡ lỗi gói gọn trong một buổi chiều, và tôi không học được bài học về lỗi. Tôi học được bài học về công cụ. Lý do tôi theo đuổi giải pháp sai là vì các công cụ tôi đang sử dụng không cho tôi thấy những gì tôi cần thấy. Tôi có đầu ra của mô hình và đầu ra của công cụ, nhưng không có một khung chung nào để xem chúng cùng nhau. Khung chung đó chính là điểm cốt yếu.
Nếu bạn đã viết nhiều hơn một tác nhân và bạn chưa mở AI Agent Debugger của Apidog, tác nhân tiếp theo bạn triển khai sẽ có một lỗi nằm giữa mô hình và công cụ. Bạn sẽ dành cả tuần cho nó. Bạn sẽ viết một trang Notion về các giả thuyết thất bại. Lỗi sẽ chính xác ở nơi trình gỡ lỗi đã có thể cho bạn thấy ngay từ ngày đầu tiên.
Tải Apidog và mở nó trên tác nhân tiếp theo cho bạn câu trả lời sai với giọng điệu tự tin. Mười hai phút. Bốn mươi bảy mili giây, không phải bốn mươi bảy giây.
Tham khảo đầy đủ tính năng, bao gồm thiết lập vận chuyển MCP và khả năng cung cấp gói dịch vụ, nằm trong Apidog AI Agent Debugger: khả năng khả dụng, phạm vi bao phủ và thiết lập.