Trình kiểm định Agent Card kiểm tra JSON đã dán, tệp Agent Card đã tải lên, và URL agent công khai theo yêu cầu khám phá A2A v1.0.
Dán JSON, URL tác nhân công hoặc kéo tệp JSON vào trình chỉnh sửa.
Phạm vi Trình kiểm định Agent Card
Trình kiểm định Agent Card được thiết kế cho các nhà phát triển xuất bản agent A2A, đội nền tảng nội bộ xem xét metadata agent, và nhà điều hành marketplace kiểm tra xem Agent Card được gửi có đủ thông tin cho việc gọi đáng tin cậy hay không.
Dán một tài liệu JSON cục bộ trong quá trình phát triển, tải lên một Agent Card từ kho lưu trữ của bạn, hoặc sử dụng xác thực URL trực tiếp với một tên miền đã triển khai để xác minh các đường dẫn khám phá công khai.
Kiểm tra các trường bắt buộc theo đặc tả v1.0: name, description, version, supportedInterfaces với protocolBinding và protocolVersion cho từng interface, capabilities, chế độ nội dung, và ít nhất một skill với các tag bắt buộc.
Phát hiện các cấu trúc trước v1.0 — url cấp cao nhất, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — và cho bạn biết chính xác từng trường đã chuyển đến đâu trong v1.0.
Xác minh securitySchemes và các yêu cầu bảo mật được khai báo cho các endpoint không công khai, đánh dấu các URL không phải HTTPS, và quét các giá trị trông giống khóa API, JWT, hoặc token bearer được nhúng.
Lấy /.well-known/agent-card.json và /.well-known/agent.json cũ từ một tên miền thực và xác nhận cả hai đều trả về JSON Agent Card có thể phân tích được.
Xác thực phù hợp ở đâu
Một Agent Card đã vượt qua đánh giá tháng trước vẫn có thể phá vỡ khả năng khám phá hôm nay — một endpoint thay đổi, một skill thay đổi, một lần triển khai lại làm mất tuyến well-known. Đội nền tảng và người đánh giá marketplace coi xác thực là một cổng có thể lặp lại, không phải kiểm tra một lần.
Biện pháp bảo vệ CI đơn giản nhất chỉ cần curl: xác nhận rằng đường dẫn well-known phản hồi bằng JSON có thể phân tích được trước khi lưu lượng chuyển sang triển khai mới.
# deploy pipeline: fail if the published card breaks
curl -fsS https://your-domain/.well-known/agent-card.json \
| python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'Hướng dẫn khắc phục
Sử dụng báo cáo của Trình kiểm định Agent Card để giải quyết các trường bắt buộc trước, sau đó cải thiện chi tiết về khả năng khám phá, độ tin cậy, và di trú.
Thay thế URL endpoint giữ chỗ bằng URL dịch vụ A2A HTTPS đã triển khai.
Di chuyển url và preferredTransport cấp cao nhất vào một mảng supportedInterfaces có thứ tự — mục đầu tiên là interface ưu tiên.
Thêm trường version cấp cao nhất bắt buộc mô tả chính agent, và thêm tag cho mọi skill.
Đổi tên provider.name thành provider.organization và mở rộng các mô tả ngắn để client biết khi nào gọi agent.
Khai báo metadata bảo mật bất cứ khi nào endpoint của agent không hoàn toàn công khai — và không bao giờ nhúng chính thông tin xác thực.
Xuất bản cùng một Agent Card hợp lệ tại /.well-known/agent-card.json (và tại đường dẫn agent.json cũ trong khi client vẫn kiểm tra cả hai).
Câu hỏi thường gặp
Đảm bảo những điều cơ bản đúng trước khi agent của bạn tiếp cận một client A2A.
So sánh các ví dụ hợp lệCác kiểm tra tuân theo cấu trúc Agent Card A2A v1.0 — supportedInterfaces, phiên bản giao thức theo từng interface, tag skill bắt buộc, provider.organization. Agent Card trước v1.0 không bị từ chối hoàn toàn: các trường cũ hiển thị dưới dạng cảnh báo kèm theo thay thế chính xác của v1.0.
Đặc tả v1.0 đăng ký /.well-known/agent-card.json, nhưng các triển khai A2A trước đó sử dụng /.well-known/agent.json. Kiểm tra cả hai giúp phát hiện lỗ hổng khám phá trước khi client thất bại.
Cảnh báo không chặn như lỗi JSON, nhưng chúng thường chỉ ra metadata giúp agent dễ khám phá, đáng tin cậy, và dễ gọi hơn — hoặc các trường trước v1.0 mà client mới hơn sẽ ngừng đọc.
Ba thời điểm: khi chỉnh sửa Agent Card trong quá trình phát triển, như một cổng CI trước khi triển khai, và sau khi xuất bản — dán URL dịch vụ thực để xác nhận những gì client thực sự nhận được từ cả hai đường dẫn khám phá.
Sẵn sàng xác thực
Dán JSON, thả một tệp Agent Card, hoặc kiểm tra một URL công khai từ không gian làm việc trình kiểm định thống nhất.