Інструмент виявлення · A2A v1.0

Перевірте URL-адреси виявлення A2A Agent Card

Клієнти A2A виявляють агента, отримуючи його JSON Agent Card за well-known URL. Перевірте обидва варіанти іменування на реальному домені й побачте, що саме отримують клієнти.

Формує обидва можливі URL виявлення з одного базового домену.

Отримує повернений JSON і повідомляє код статусу та тип вмісту.

За можливості розбирає відповідь як JSON Agent Card.

Виконує перевірки готовності для інтерфейсів, навичок, провайдера, режимів, можливостей і метаданих безпеки.

Перевірити публічний домен агента

Введіть базовий домен. Перевірка отримує обидва шляхи виявлення, розбирає повернений JSON і виконує перевірки готовності Agent Card.

Як працює виявлення

Один well-known URL запускає кожну інтеграцію A2A.

Перш ніж інший агент зможе викликати ваш, він отримує Agent Card за well-known URI (RFC 8615) на вашому домені, оцінює навички та вимоги безпеки, а потім викликає бажаний інтерфейс. Якщо Agent Card відсутня, застаріла або схована за перенаправленням, інтеграція завершується невдачею ще до початку.

Цей сайт застосовує те, що перевіряє: AgentCard.net публікує власну Agent Card за обома шляхами, а приклад праворуч — реальний документ.

Переглянути нашу актуальну Agent Card

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", ... }
  ]
}

Шляхи виявлення

Дві конвенції, одна Agent Card.

Відкрити повний валідатор

Стандарт A2A v1.0

/.well-known/agent-card.json

Well-known URI, зареєстрований специфікацією A2A v1.0. Нові клієнти спершу отримують цей шлях; надавайте його з типом вмісту application/a2a+json.

Застарілий (до v1.0)

/.well-known/agent.json

Використовується ранніми реалізаціями A2A та прикладами codelab. Багато розгорнутих клієнтів досі перевіряють лише цей шлях, тож надання тут тієї самої Agent Card — безпечна стратегія переходу.

Схема публікації

Зробіть виявлення Agent Card стійким.

Збої виявлення рідко бувають екзотичними: перенаправлення, закешована сторінка помилки, або один шлях розгорнуто, а інший забуто. Ця процедура публікації підтримує обидві конвенції з однією й тією ж актуальною Agent Card.

1
Публікація за стандартним шляхом
Надавайте перевірену Agent Card за адресою /.well-known/agent-card.json через HTTPS на тому самому домені, що й сервіс A2A, з типом вмісту application/a2a+json.
2
Дзеркалення застарілого шляху
Повертайте ідентичний документ з /.well-known/agent.json, доки старі клієнти ще в обігу — розбіжні Agent Card на двох шляхах заплутують маршрутизацію.
3
Синхронізація Agent Card
Щоразу, коли змінюються кінцеві точки, навички, можливості або автентифікація, оновлюйте Agent Card, підвищуйте поле version і повторно розгортайте обидва шляхи разом.
4
Повторна перевірка після кожної зміни
Запускайте цю перевірку після розгортань, змін DNS, міграцій шлюзу або редагувань маркетплейсу. Збої зазвичай пов'язані з перенаправленнями, сторінками помилок HTML або забутим шляхом.

Часті запитання

Часті запитання про Well-known Agent JSON

Що публікувати, де публікувати та як підтримувати роботу клієнтів обох конвенцій.

Який well-known шлях Agent Card слід використовувати?

A2A v1.0 реєструє /.well-known/agent-card.json як стандартний шлях виявлення. Застарілий /.well-known/agent.json передує v1.0, але досі перевіряється багатьма розгорнутими клієнтами, тож публікація однієї й тієї ж Agent Card на обох шляхах є прагматичним вибором під час переходу.

Чи повинні обидва шляхи повертати однаковий JSON?

Так. Повернення однієї й тієї ж публічної Agent Card з обох шляхів забезпечує узгодженість для клієнтів, які підтримують лише одну конвенцію. Розбіжні документи змушують агента виглядати по-різному залежно від того, який шлях отримає клієнт.

З яким типом вмісту слід надавати Agent Card?

Специфікація реєструє application/a2a+json для Agent Card. Звичайний application/json широко приймається на практиці, але тип вмісту HTML — надійна ознака того, що шлях повертає сторінку помилки замість Agent Card.

Чи може публічна Agent Card приховувати приватні можливості?

Так. Публікуйте в публічній Agent Card лише метадані, безпечні для виявлення, встановіть capabilities.extendedAgentCard у true та розкривайте чутливі навички через автентифіковану операцію GetExtendedAgentCard.

Чому перевірки виявлення не проходять після розгортання?

Поширені причини — перенаправлення на сторінку входу чи маркетингу, сторінки HTML 404, повернені зі статусом 200, застарілий JSON, закешований у CDN, або розгорнуто лише один із двох well-known шляхів. Перевірка повідомляє код статусу й тип вмісту для кожного шляху, тож збій стає видимим одразу.

Перед публікацією

Перевірте Agent Card, потім URL-адреси.

Спершу пропустіть JSON через повний валідатор, опублікуйте його на обох well-known шляхах і підтвердіть виявлення цією перевіркою.

Відкрити валідатор Згенерувати Agent Card

З блогу

Практичні посібники з виявлення A2A, написані за специфікацією v1.0.

Усі статті

Comparison

Статті публікуються англійською мовою.

Перевірте URL-адреси виявлення A2A Agent Card

Перевірити публічний домен агента

Один well-known URL запускає кожну інтеграцію A2A.

Дві конвенції, одна Agent Card.

/.well-known/agent-card.json

/.well-known/agent.json

Зробіть виявлення Agent Card стійким.

Публікація за стандартним шляхом

Дзеркалення застарілого шляху

Синхронізація Agent Card

Повторна перевірка після кожної зміни