Agent2Agent (A2A) Debugger Là Gì? Tại Sao Bạn Cần?

Bạn đã xây dựng một tác nhân A2A. Nó kết nối, chạy được, nhưng đôi khi trả về kết quả sai. Khi mở console, bạn chỉ thấy một luồng gói JSON-RPC với các trường quan trọng bị chôn sâu nhiều cấp. Bạn không biết lỗi nằm ở tầng truyền tải, định dạng payload, xác thực hay logic của tác nhân. Đây là lúc Trình gỡ lỗi Agent2Agent (A2A) trở nên cần thiết.

Dùng thử Apidog ngay hôm nay

Bài viết này giải thích trình gỡ lỗi A2A là gì, vì sao việc gỡ lỗi lưu lượng giữa các tác nhân khó nếu chỉ dùng log hoặc network tab, một trình gỡ lỗi tốt nên hỗ trợ gì, và cách áp dụng nó vào vòng lặp debug thực tế. Nếu bạn cần nắm giao thức trước, hãy bắt đầu với Agent2Agent (A2A) là gì.

Trình gỡ lỗi A2A là gì?

Trình gỡ lỗi A2A là công cụ cho phép bạn kết nối tới một tác nhân Agent2Agent, gửi thông báo thử nghiệm và kiểm tra toàn bộ request/response mà không cần tự viết client. Nó đóng vai trò tương tự một REST client đối với API: bạn điều khiển tác nhân thủ công, xem chính xác dữ liệu đi qua đường truyền và nhanh chóng xác định trường nào sai.

A2A là giao thức mở cho giao tiếp giữa các tác nhân AI. Nó định nghĩa Agent Card, vòng đời tác vụ, định dạng message, artifact và các payload mà tác nhân trao đổi. Trình gỡ lỗi A2A là nơi bạn kiểm tra các phần đó bằng tay trước khi đưa tác nhân vào workflow sản xuất.

Nói ngắn gọn, trình gỡ lỗi không xây dựng tác nhân thay bạn và cũng không chạy toàn bộ workflow. Nó trả lời một câu hỏi cụ thể:

Với Agent Card này, tác nhân thực sự làm gì khi tôi gửi message này?

Vì sao gỡ lỗi A2A khó nếu không có trình gỡ lỗi?

Lưu lượng giữa các tác nhân thường bị ẩn bên dưới SDK, JSON-RPC và các lớp transport. Các công cụ debug thông thường chỉ cho bạn một phần bức tranh.

Console log thường thiếu dữ liệu quan trọng

SDK chỉ ghi log những gì tác giả SDK hoặc tác giả tác nhân quyết định ghi. Các trường như task ID có cấu trúc, artifact parts, metadata tùy chỉnh hoặc payload gốc thường không xuất hiện trong stdout.

Bạn có thể thấy:

Task completed

Nhưng không thấy:

{
  "taskId": "task_123",
  "artifact": {
    "parts": [
      {
        "kind": "text",
        "text": "..."
      }
    ]
  },
  "metadata": {
    "tenantId": "demo"
  }
}

Kết quả là log báo “hoàn thành”, nhưng bạn vẫn không biết dữ liệu trả về có đúng định dạng hay không.

Network tab hiển thị thô, nhưng không hiểu A2A

Network tab của trình duyệt có thể hiển thị HTTP request/response, nhưng payload A2A thường là JSON-RPC lồng nhau. Muốn biết tác nhân trả về text, file hay artifact có cấu trúc, bạn phải tự đọc một khối JSON lớn.

Ví dụ, thay vì chỉ cần thấy “response content”, bạn phải lần theo nhiều lớp:

{
  "jsonrpc": "2.0",
  "result": {
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "parts": [
          {
            "kind": "text",
            "text": "Kết quả..."
          }
        ]
      }
    ]
  }
}

Nếu payload bị thiếu một trường, network tab không nói cho bạn biết đó là lỗi ở Agent Card, message format hay logic của tác nhân.

Script thử nghiệm tùy chỉnh dễ lỗi thời

Cách phổ biến là viết nhanh một lệnh curl hoặc một script Python nhỏ:

curl -X POST http://localhost:3000/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"message/send","params":{...},"id":"1"}'

Cách này chạy được trong giai đoạn đầu. Nhưng khi Agent Card thay đổi, schema xác thực đổi, endpoint di chuyển hoặc metadata mới được thêm vào, script có thể hỏng âm thầm. Không ai cập nhật nó, và bạn lại debug trên một payload không còn đại diện cho production.

Lỗi transport và lỗi logic nhìn giống nhau

Khi tác nhân trả lời sai, nguyên nhân có thể là:

• Request bị format sai
• Header xác thực thiếu hoặc sai
• Kết nối transport bị lỗi
• Metadata không được truyền đúng chỗ
• Prompt hoặc model reasoning sai

Nếu không nhìn được request và response gốc, tất cả đều bị gom thành một kết luận mơ hồ: “tác nhân bị lỗi”.

Trình gỡ lỗi A2A loại bỏ sự mơ hồ đó. Bạn thấy chính xác request đã gửi, response đã nhận và trường nào không đúng.

Một trình gỡ lỗi A2A nên làm gì?

Một trình gỡ lỗi A2A hữu ích cần bao phủ ít nhất bốn nhóm chức năng: kết nối, gửi message, kiểm tra response và xử lý xác thực.

1. Kết nối và khám phá Agent Card

Bạn dán URL Agent Card, trình gỡ lỗi sẽ fetch, xác thực và hiển thị metadata mà tác nhân công bố, ví dụ:

• Tên tác nhân
• Mô tả
• Khả năng
• Kỹ năng đã khai báo
• Loại input được hỗ trợ
• Phiên bản giao thức
• Endpoint liên quan

Với môi trường local, URL thường có dạng:

http://localhost:3000/.well-known/agent.json

Nếu Agent Card sai định dạng, công cụ tốt nên chỉ ra trường bị thiếu hoặc không hợp lệ. Điều này giúp bạn sửa manifest thay vì đoán lỗi ở tầng runtime.

2. Gửi message thử nghiệm

Bạn cần có thể gửi message giống như khi dùng một hộp chat hoặc API client:

• Văn bản thuần túy
• Tệp đính kèm
• Metadata tùy chỉnh
• Header bổ sung nếu cần
• Payload có cấu trúc

Trình gỡ lỗi sẽ tự gói input của bạn vào cấu trúc A2A và JSON-RPC phù hợp. Bạn không cần tự dựng payload thủ công.

Ví dụ, thay vì tự viết toàn bộ JSON-RPC, bạn chỉ nhập prompt:

Tóm tắt nội dung file này thành 5 gạch đầu dòng.

Sau đó công cụ sẽ xử lý phần đóng gói message theo giao thức.

3. Kiểm tra response ở nhiều chế độ xem

Response A2A có thể là:

• Chuỗi văn bản
• Artifact có cấu trúc
• Tham chiếu file
• Nhiều phần message kết hợp
• Payload JSON-RPC đầy đủ

Một trình gỡ lỗi tốt nên hiển thị cùng một response qua nhiều góc nhìn. Ví dụ, Trình gỡ lỗi A2A của Apidog cung cấp ba chế độ:

• Preview: hiển thị dữ liệu có cấu trúc dưới dạng cây dễ đọc.
• Content: hiển thị nội dung người dùng cuối sẽ thấy.
• Raw Data: hiển thị toàn bộ payload JSON-RPC để kiểm tra cấp trường.

Cách đọc thực tế:

1. Mở Raw Data để xác nhận tác nhân thực sự trả về gì.
2. Mở Preview để xem cấu trúc đã được parse đúng chưa.
3. Mở Content để kiểm tra nội dung hiển thị cuối cùng.

Nếu Preview có artifact nhưng Content trống, có thể tác nhân trả về kiểu artifact mà trình hiển thị không flatten được. Nếu Raw Data thiếu trường mong đợi, lỗi nằm trong mã tác nhân hoặc handler.

4. Xử lý xác thực và header

Tác nhân production thường nằm sau gateway, proxy hoặc lớp xác thực. Trình gỡ lỗi nên hỗ trợ trực tiếp:

• Bearer Token
• Basic Auth
• API key qua custom header
• Header tùy chỉnh
• Tenant ID hoặc request ID
• Header dành cho gateway/proxy

Ví dụ:

Authorization: Bearer <token>
X-Tenant-ID: demo
X-Request-ID: debug-001

Điểm quan trọng là phân biệt HTTP header và A2A metadata:

• Header đi tới gateway, proxy hoặc middleware.
• Metadata đi tới task handler của tác nhân.

Nếu bạn đặt chỉ dẫn dành cho tác nhân vào header, tác nhân có thể không bao giờ đọc được nó. Ngược lại, nếu thông tin xác thực lại đặt trong metadata, gateway có thể từ chối request trước khi tác nhân nhận được.

Trình gỡ lỗi A2A của Apidog

Apidog cung cấp Trình gỡ lỗi A2A trong ứng dụng khách tiêu chuẩn, giúp bạn kiểm tra tác nhân mà không cần viết client riêng.

Quy trình cơ bản:

1. Mở trang A2A Debugger.
2. Dán URL Agent Card, ví dụ:

   http://localhost:3000/.well-known/agent.json

1. Nhấp Connect.
2. Kiểm tra metadata của tác nhân trong bảng điều khiển.
3. Mở tab Messages.
4. Nhập prompt thử nghiệm.
5. Tùy chọn thêm file hoặc metadata.
6. Nhấp Send.
7. Đọc response trong Preview, Content và Raw Data.

Apidog xử lý phần đóng gói JSON-RPC, server-sent event streaming khi tác nhân hỗ trợ, và phân tích cú pháp response. Lịch sử phiên giữ lại các message đã gửi để bạn có thể quay lại từng lần thử.

Theo nội dung gốc, trình gỡ lỗi chạy như một client cục bộ: lưu lượng đi thẳng giữa máy của bạn và tác nhân, không thông qua máy chủ của Apidog.

Một lợi ích thực tế là bạn nhìn được header HTTP và metadata A2A cạnh nhau. Điều này giúp phát hiện nhanh lỗi kiểu:

• Đặt tenantId trong header trong khi handler chỉ đọc metadata
• Đặt token trong metadata trong khi gateway yêu cầu Authorization
• Gửi prompt đúng nhưng thiếu metadata mà skill cần để chạy

Để xem hướng dẫn từng bước, đọc hướng dẫn Trình gỡ lỗi A2A của Apidog. Apidog cũng có trình gỡ lỗi tác nhân AI cho quy trình kiểm thử tác nhân rộng hơn.

Checklist khi chọn trình gỡ lỗi A2A

Khi so sánh công cụ, hãy kiểm tra các điểm sau.

Xác thực Agent Card rõ ràng

Công cụ không nên chỉ báo “Agent Card invalid”. Nó cần chỉ ra lý do cụ thể, ví dụ:

• Thiếu trường bắt buộc
• Sai kiểu dữ liệu
• Endpoint không hợp lệ
• Không khớp phiên bản giao thức

Có nhiều chế độ xem response

JSON thô là cần thiết nhưng chưa đủ. Bạn nên có:

• Chế độ dễ đọc cho nội dung cuối cùng
• Chế độ cấu trúc để xem artifact/message parts
• Chế độ raw để kiểm tra payload gốc

Hỗ trợ xác thực đầy đủ

Tối thiểu nên có:

• Bearer Token
• Basic Auth
• API key
• Custom headers

Không nên buộc bạn tự encode hoặc tự viết script chỉ để thêm header.

Hỗ trợ file và metadata

A2A thực tế không chỉ có text. Nhiều tác nhân cần file đính kèm hoặc metadata theo từng message. Nếu trình gỡ lỗi chỉ gửi được text, bạn sẽ bỏ lỡ một phần lớn bề mặt lỗi.

Hỗ trợ streaming

Nếu tác nhân dùng server-sent events, trình gỡ lỗi nên hiển thị các phần response khi chúng đến và hiển thị payload đã ghép lại sau khi stream kết thúc.

Có lịch sử phiên

Trong debug, bạn thường gửi lại cùng một prompt nhiều lần sau mỗi lần sửa. Lịch sử phiên giúp bạn:

• So sánh response trước/sau
• Re-run message cũ
• Kiểm tra thay đổi ở raw payload
• Giảm thao tác nhập lại

Ưu tiên lưu lượng cục bộ

Trình gỡ lỗi nên giao tiếp trực tiếp với tác nhân của bạn thay vì định tuyến payload qua bên thứ ba, đặc biệt khi payload chứa dữ liệu nhạy cảm hoặc đang chạy trên môi trường local.

Một trình gỡ lỗi bao phủ các điểm này sẽ biến debug A2A từ phỏng đoán thành quy trình xác minh từng lớp. Đây cũng là cùng nguyên tắc được áp dụng trong bài cách kiểm thử các tác nhân AI gọi API của bạn. Nếu bạn cũng chạy MCP server, hướng dẫn về MCP server so với A2A giải thích vì sao thường cần trình gỡ lỗi riêng cho từng giao thức.

Vòng lặp gỡ lỗi A2A thực tế

Khi một tác nhân A2A hoạt động sai, hãy chạy vòng lặp này trong trình gỡ lỗi.

Bước 1: Kết nối và xác nhận Agent Card

Kiểm tra rằng Agent Card hiển thị đúng skill bạn mong đợi. Nếu skill không xuất hiện, đừng debug message vội. Hãy sửa manifest hoặc endpoint discovery trước.

Bước 2: Gửi message nhỏ nhất có thể

Bắt đầu bằng prompt tối giản:

Ping

Hoặc prompt kích hoạt đúng skill:

Tóm tắt đoạn văn sau: ...

Chưa thêm file, metadata hoặc header phức tạp nếu chưa cần.

Bước 3: Đọc Raw Data trước

Đọc payload gốc để biết tác nhân thực sự phát ra gì. Đừng chỉ dựa vào preview vì preview có thể đã qua xử lý hiển thị.

Bước 4: Kiểm tra trường mong đợi

Nếu bạn kỳ vọng response có artifacts, parts hoặc metadata, hãy xác nhận trực tiếp trong raw payload.

Ví dụ:

{
  "artifacts": [
    {
      "parts": [
        {
          "kind": "text",
          "text": "..."
        }
      ]
    }
  ]
}

Nếu trường bị thiếu, lỗi có khả năng nằm trong handler của tác nhân.

Bước 5: Phân loại lỗi

Dựa trên response, phân loại lỗi:

• Payload không hợp lệ → lỗi đóng gói request hoặc client
• Unauthorized/forbidden → lỗi auth/header
• Agent Card sai → lỗi discovery/manifest
• Response đúng schema nhưng nội dung sai → lỗi prompt, model hoặc logic tác nhân
• Stream bị ngắt → kiểm tra transport hoặc SSE handling

Bước 6: Chỉ thêm độ phức tạp sau khi case đơn giản chạy đúng

Thứ tự khuyến nghị:

1. Text thuần
2. Text + metadata
3. Text + header xác thực
4. Text + file
5. Streaming
6. Full workflow

Cách này giúp bạn cô lập lỗi theo từng lớp thay vì debug tất cả cùng lúc.

FAQ

Trình gỡ lỗi A2A là gì trong một câu?

Đó là công cụ kết nối với một tác nhân Agent2Agent, gửi message thử nghiệm và hiển thị toàn bộ request/response để bạn debug tích hợp tác nhân mà không cần tự viết client.

Trình gỡ lỗi A2A khác gì máy khách API thông thường?

Máy khách API kiểm tra endpoint HTTP thuần túy. Trình gỡ lỗi A2A hiểu thêm lớp A2A phía trên: Agent Card, vòng đời tác vụ, message parts và artifact. Nó parse và hiển thị các cấu trúc đó thay vì chỉ trả lại body thô.

Tôi có cần trình gỡ lỗi A2A nếu đã có log không?

Có, nếu bạn cần xác minh payload thực tế. Log chỉ hiển thị những gì tác nhân chọn ghi lại, thường bỏ qua nhiều trường có cấu trúc. Trình gỡ lỗi hiển thị lưu lượng transport chính xác, giúp phân biệt lỗi truyền tải với lỗi logic. Xem thêm Agent2Agent (A2A) là gì để hiểu ngữ cảnh giao thức.

Trình gỡ lỗi A2A của Apidog có miễn phí không?

Có. Theo nội dung gốc, nó được đóng gói cùng ứng dụng khách Apidog tiêu chuẩn. Bạn có thể tải Apidog và mở Trình gỡ lỗi A2A trong bảng điều khiển bên ở phiên bản mới nhất.

Trình gỡ lỗi A2A có kiểm thử được tác nhân trên bất kỳ framework nào không?

Có, miễn là tác nhân hiển thị Agent Card A2A hợp lệ. Giao thức không phụ thuộc framework, nên các tác nhân xây bằng LangGraph, CrewAI, AutoGen hoặc framework tùy chỉnh đều có thể được kiểm thử nếu tuân theo A2A.

Trình gỡ lỗi A2A có xử lý response streaming không?

Một trình gỡ lỗi tốt nên làm được. Khi tác nhân hỗ trợ server-sent events, trình gỡ lỗi cần đọc từng phần khi chúng đến, cập nhật view theo thời gian thực và hiển thị payload đã ghép lại khi stream đóng.