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

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

Використовуйте засіб перевірки Agent Cards

Вставте 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