Trả lỗi có cấu trúc từ tool MCP

MCP (Model Context Protocol) là chuẩn để nối agent với các hệ thống bên ngoài: mỗi hệ thống dựng một MCP server, cung cấp các tool cho agent gọi. Khi tool chạy hỏng, cách nó báo lỗi quyết định agent có xử lý tiếp được hay không.

Bài này giúp bạn trả lời: tool nên trả lỗi thế nào để agent biết nên thử lại, nên đổi cách, hay nên dừng và báo người dùng?

Ví dụ xuyên suốt: MCP server đặt bàn nhà hàng

Một chuỗi nhà hàng lẩu dựng MCP server cho agent đặt bàn, có tool book_table(branch, date, time, party_size).

Bản đầu, gặp bất kỳ lỗi gì tool cũng trả về một câu: "Thao tác thất bại." Agent nhận câu này trong bốn tình huống rất khác nhau:

1. Hệ thống đặt bàn của chi nhánh quá tải, phản hồi chậm quá thời gian chờ.
2. Khách nói "tối thứ Tư tuần sau", agent truyền nhầm ngày dạng 31/11/2026, một ngày không tồn tại.
3. Khách muốn đặt cho 30 người, trong khi quy định chỉ nhận đặt online tối đa 20 người.
4. Tài khoản của agent không có quyền xem khu phòng riêng VIP.

Với câu "Thao tác thất bại", agent làm gì cũng sai: thử lại ca 3 thì vô ích, bỏ cuộc ca 1 thì đáng tiếc vì thử lại sau vài giây là được.

Cờ isError của MCP

Theo đặc tả MCP, có hai kiểu lỗi:

• Lỗi giao thức: gọi tool không tồn tại, tham số sai cấu trúc. Báo bằng lỗi JSON-RPC chuẩn.
• Lỗi khi chạy tool: API bên ngoài hỏng, dữ liệu đầu vào không hợp lệ, vi phạm quy tắc nghiệp vụ. Báo trong kết quả của tool, kèm isError: true.

Kiểu thứ hai là kiểu agent đọc được và xử lý được. Kết quả vẫn có phần content như thường, chỉ thêm cờ isError để agent biết đây là thất bại chứ không phải dữ liệu.

Bốn loại lỗi

Biết loại lỗi, agent mới chọn được cách xử lý đúng.

Trả lỗi kèm thông tin để agent quyết định

Thay vì một câu chung chung, tool trả lỗi có cấu trúc. Đề thi nhắc ba thứ: loại lỗi (errorCategory), có nên thử lại không (isRetryable), và lời giải thích con người đọc hiểu được.

Ca 3, vượt quá 20 người. Kết quả tool có cờ isError, và phần chữ bên trong là một đoạn JSON mô tả lỗi:

{
  "isError": true,
  "content": [{ "type": "text", "text": "(đoạn JSON bên dưới, dạng chuỗi)" }]
}

{
  "errorCategory": "business",
  "isRetryable": false,
  "message": "Đặt online nhận tối đa 20 khách. Nhóm từ 21 khách cần gọi hotline chi nhánh để xếp phòng riêng."
}

Với lỗi vi phạm quy định, isRetryable: false giúp agent khỏi thử đi thử lại vô ích. Phần message viết sao cho agent có thể nói lại với khách: không chỉ "không được", mà còn "phải làm thế nào".

Bài viết của Anthropic về thiết kế tool cũng khuyên viết thông báo lỗi chỉ rõ cần sửa gì, thay vì mã lỗi khó hiểu hay nguyên đoạn traceback.

Subagent tự thử lại lỗi tạm thời

Trong hệ thống nhiều agent, giả sử subagent đặt bàn gặp lỗi hết thời gian chờ. Nó có nên báo ngay lên agent điều phối không?

Không cần. Lỗi tạm thời thì subagent nên tự thử lại vài lần trước. Chỉ khi thử mà vẫn hỏng, nó mới báo lên, kèm:

• Những gì đã làm được (kết quả từng phần), ví dụ đã đặt xong bàn chi nhánh A, chưa đặt được chi nhánh B.
• Những gì đã thử, ví dụ đã thử lại 3 lần trong 30 giây.

Như vậy agent điều phối không bị làm phiền bởi những lỗi nhỏ tự hết, mà khi nhận được báo lỗi thì có đủ thông tin để quyết định. Cách truyền lỗi giữa các agent nằm ở bài 5.3.

Lỗi khác với không có kết quả

Khách hỏi "tối nay chi nhánh Quận 3 còn bàn 4 người không?". Có hai câu trả lời rất khác nhau:

Nếu tool trả danh sách rỗng cho cả hai trường hợp, agent sẽ báo khách "hết bàn" trong khi thật ra chỉ là mất kết nối. Ngược lại, nếu báo lỗi khi hết bàn, agent sẽ cố thử lại một truy vấn vốn đã đúng.