Инструмент обнаружения · 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. 1

    Публикация по стандартному пути

    Отдавайте проверенную Agent Card по адресу /.well-known/agent-card.json через HTTPS на том же домене, что и сервис A2A, с типом содержимого application/a2a+json.

  2. 2

    Зеркалирование устаревшего пути

    Возвращайте идентичный документ по адресу /.well-known/agent.json, пока в обороте остаются старые клиенты — расхождения Agent Card на двух путях сбивают маршрутизацию.

  3. 3

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

    При любом изменении конечных точек, навыков, возможностей или аутентификации обновляйте Agent Card, повышайте поле version и повторно развёртывайте оба пути одновременно.

  4. 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