Валидатор A2A Agent Card

Валидатор Agent Card проверяет вставленный JSON, загруженные файлы Agent Card и публичные URL агентов на соответствие требованиям обнаружения A2A v1.0.

Используйте валидатор Agent Card агента

Вставьте JSON, URL-адрес публичного агента, или перетащите файл JSON в редактор.

Охват валидатора Agent Card

Что проверяет валидатор Agent Card до того, как клиенты обнаружат вашего агента.

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

Вставьте локальный JSON-документ во время разработки, загрузите Agent Card из вашего репозитория, или используйте живую проверку URL на развёрнутом домене, чтобы проверить публичные пути обнаружения.

Соответствие схеме (A2A v1.0)

Проверяет обязательные поля по спецификации v1.0: name, description, version, supportedInterfaces с protocolBinding и protocolVersion для каждого интерфейса, capabilities, режимы содержимого, и как минимум один навык с обязательными тегами.

Семантические проблемы и проблемы миграции

Обнаруживает структуры до v1.0 — url верхнего уровня, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — и точно указывает, куда переместилось каждое поле в v1.0.

Сканирование безопасности и секретов

Проверяет, что securitySchemes и требования безопасности объявлены для непубличных конечных точек, помечает не-HTTPS URL, и сканирует значения, похожие на встроенные API-ключи, JWT или bearer-токены.

Готовность к обнаружению

Получает /.well-known/agent-card.json и устаревший /.well-known/agent.json с реального домена и подтверждает, что оба возвращают разбираемый JSON Agent Card.

Где применяется проверка

Проверяйте на каждом этапе: редактор, CI-конвейер, боевой домен.

Agent Card, прошедшая проверку в прошлом месяце, всё ещё может сломать обнаружение сегодня — конечная точка меняется, навык изменяется, повторное развёртывание теряет well-known маршрут. Платформенные команды и рецензенты маркетплейсов относятся к проверке как к повторяемому шлюзу, а не разовой проверке.

Самая простая CI-защита требует только curl: подтвердите, что well-known путь отвечает разбираемым JSON, прежде чем трафик переключится на новое развёртывание.

# 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"])'

Руководство по исправлению

Частые исправления Agent Card

Сначала используйте отчёт валидатора Agent Card для устранения обязательных полей, затем улучшите детали обнаружения, доверия и миграции.

Замените URL-заглушки конечных точек на развёрнутый HTTPS URL сервиса A2A.

Переместите url и preferredTransport верхнего уровня в упорядоченный массив supportedInterfaces — первая запись является предпочтительным интерфейсом.

Добавьте обязательное поле version верхнего уровня, описывающее самого агента, и добавьте теги к каждому навыку.

Переименуйте provider.name в provider.organization и расширьте короткие описания, чтобы клиенты знали, когда вызывать агента.

Объявляйте метаданные безопасности всякий раз, когда конечная точка агента не полностью публична — и никогда не встраивайте сами учётные данные.

Опубликуйте ту же действительную Agent Card по адресу /.well-known/agent-card.json (и по устаревшему пути agent.json, пока клиенты всё ещё проверяют оба).

Частые вопросы

Вопросы о валидаторе Agent Card

Приведите в порядок основы до того, как ваш агент достигнет клиента A2A.

Сравнить корректные примеры

На какую версию A2A нацелен валидатор?

Проверки следуют структуре Agent Card A2A v1.0 — supportedInterfaces, версии протокола для каждого интерфейса, обязательные теги навыков, provider.organization. Agent Card до v1.0 не отклоняются сразу: устаревшие поля выводятся как предупреждения с точной заменой для v1.0.

Почему проверяются оба well-known URL?

Спецификация v1.0 регистрирует /.well-known/agent-card.json, но более ранние реализации A2A использовали /.well-known/agent.json. Проверка обоих выявляет пробелы в обнаружении до того, как клиенты потерпят неудачу.

Можно ли игнорировать предупреждения?

Предупреждения не блокируют как ошибки JSON, но обычно указывают на метаданные, которые упрощают обнаружение, доверие и вызов агента — или на поля до v1.0, которые более новые клиенты перестанут читать.

Когда следует запускать проверку?

Три момента: при редактировании Agent Card во время разработки, в качестве шлюза CI перед развёртыванием, и после публикации — вставьте URL реального сервиса, чтобы подтвердить, что клиенты фактически получают с обоих путей обнаружения.

Готовы к проверке

Проверьте свою Agent Card до того, как клиенты её обнаружат.

Вставьте JSON, перетащите файл Agent Card, или проверьте публичный URL в едином рабочем пространстве валидатора.

Открыть валидатор Agent Card Сгенерировать Agent Card