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

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