Công cụ khám phá · A2A v1.0

Kiểm tra URL khám phá A2A Agent Card

Các client A2A khám phá một agent bằng cách lấy Agent Card JSON từ một URL well-known. Kiểm tra cả hai quy ước đặt tên trên một tên miền thực và xem chính xác những gì client nhận được.

Xây dựng cả hai URL khám phá tiềm năng từ cùng một tên miền gốc.

Lấy JSON trả về và báo cáo mã trạng thái cùng loại nội dung.

Phân tích phản hồi thành JSON Agent Card khi có thể.

Chạy kiểm tra sẵn sàng cho interface, skill, provider, mode, capability và metadata bảo mật.

Kiểm tra một tên miền agent công khai

Nhập một tên miền gốc. Công cụ kiểm tra sẽ lấy cả hai đường dẫn khám phá, phân tích JSON trả về, và chạy kiểm tra sẵn sàng của Agent Card.

Cách khám phá hoạt động

Một URL well-known khởi động mọi tích hợp A2A.

Trước khi một agent khác có thể gọi dịch vụ của bạn, nó sẽ lấy Agent Card từ một URI well-known (RFC 8615) trên tên miền của bạn, đánh giá các skill và yêu cầu bảo mật, sau đó gọi interface ưu tiên. Nếu Agent Card bị thiếu, lỗi thời, hoặc bị ẩn sau redirect, tích hợp thất bại trước khi bắt đầu.

Trang này thực hành đúng những gì nó kiểm tra: AgentCard.net công bố Agent Card của chính mình trên cả hai đường dẫn, và ví dụ bên phải là tài liệu thực tế.

Xem Agent Card trực tiếp của chúng tôi
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

Đường dẫn khám phá

Hai quy ước, một Agent Card.

Mở trình kiểm định đầy đủ
Chuẩn A2A v1.0

/.well-known/agent-card.json

URI well-known được đăng ký bởi đặc tả A2A v1.0. Client mới sẽ lấy đường dẫn này trước tiên; hãy phục vụ nó với loại nội dung application/a2a+json.

Cũ (trước v1.0)

/.well-known/agent.json

Được sử dụng bởi các triển khai A2A đời đầu và ví dụ codelab. Nhiều client đã triển khai vẫn chỉ kiểm tra đường dẫn này, vì vậy phục vụ cùng một Agent Card ở đây là chiến lược chuyển đổi an toàn.

Mô hình xuất bản

Làm cho việc khám phá Agent Card trở nên bền vững.

Lỗi khám phá hiếm khi phức tạp: một redirect, một trang lỗi được cache, hoặc một đường dẫn đã triển khai còn đường kia bị quên. Quy trình xuất bản này giữ cho cả hai quy ước luôn phục vụ cùng một Agent Card mới nhất.

  1. 1

    Xuất bản tại đường dẫn chuẩn

    Phục vụ Agent Card đã xem xét tại /.well-known/agent-card.json qua HTTPS trên cùng tên miền với dịch vụ A2A, với loại nội dung application/a2a+json.

  2. 2

    Phản chiếu đường dẫn cũ

    Trả về tài liệu giống hệt tại /.well-known/agent.json trong khi các client cũ vẫn còn lưu hành — Agent Card khác biệt trên hai đường dẫn sẽ gây rối định tuyến.

  3. 3

    Giữ Agent Card đồng bộ

    Bất cứ khi nào endpoint, skill, capability, hoặc xác thực thay đổi, hãy cập nhật Agent Card, tăng trường version, và triển khai lại cả hai đường dẫn cùng nhau.

  4. 4

    Kiểm tra lại sau mỗi thay đổi

    Chạy công cụ kiểm tra này sau khi triển khai, thay đổi DNS, di chuyển gateway, hoặc chỉnh sửa marketplace. Lỗi thường bắt nguồn từ redirect, trang lỗi HTML, hoặc một đường dẫn bị quên.

Câu hỏi thường gặp

Câu hỏi thường gặp về Well-known Agent JSON

Nên xuất bản gì, xuất bản ở đâu, và cách giữ cho client của cả hai quy ước hoạt động.

Tôi nên dùng đường dẫn Agent Card well-known nào?

A2A v1.0 đăng ký /.well-known/agent-card.json là đường dẫn khám phá chuẩn. Đường dẫn cũ /.well-known/agent.json có trước v1.0 nhưng vẫn được nhiều client đã triển khai kiểm tra, vì vậy xuất bản cùng một Agent Card trên cả hai đường dẫn là lựa chọn thực tế trong giai đoạn chuyển đổi.

Cả hai đường dẫn có nên trả về JSON giống hệt nhau không?

Có. Trả về cùng một Agent Card công khai từ cả hai đường dẫn giúp các client chỉ hỗ trợ một quy ước luôn nhất quán. Tài liệu khác biệt khiến agent trông khác nhau tùy vào đường dẫn mà client lấy.

Agent Card nên được phục vụ với loại nội dung nào?

Đặc tả đăng ký application/a2a+json cho Agent Card. application/json thông thường được chấp nhận rộng rãi trong thực tế, nhưng loại nội dung HTML là dấu hiệu đáng tin cậy cho thấy đường dẫn đang trả về trang lỗi thay vì Agent Card.

Agent Card công khai có thể ẩn các capability riêng tư không?

Có. Chỉ xuất bản metadata an toàn cho khám phá trong Agent Card công khai, đặt capabilities.extendedAgentCard thành true, và công khai các skill nhạy cảm thông qua thao tác GetExtendedAgentCard đã xác thực.

Tại sao kiểm tra khám phá thất bại sau khi triển khai?

Nguyên nhân thường gặp là redirect đến trang đăng nhập hoặc marketing, trang HTML 404 trả về với trạng thái 200, JSON cũ được cache trên CDN, hoặc chỉ một trong hai đường dẫn well-known được triển khai. Công cụ kiểm tra báo cáo mã trạng thái và loại nội dung cho từng đường dẫn, nên lỗi hiển thị ngay lập tức.

Trước khi xuất bản

Xác thực Agent Card, sau đó kiểm tra URL.

Trước tiên hãy đưa JSON qua trình kiểm định đầy đủ, xuất bản nó trên cả hai đường dẫn well-known, và xác nhận khám phá bằng công cụ kiểm tra này.

Mở trình kiểm địnhTạo Agent Card