Руководство · Стандарт или спецификация
A2A Agent Card: обнаружение возможностей агента
Как публиковать A2A Agent Card, описывать интерфейсы, навыки и требования к безопасности без секретов и почему карточка агента не должна давать анонимному клиенту полномочия на выполнение задач.
- Опубликовано
- Обновлено
Ограничение: материал объясняет проверяемый технический сигнал. Его наличие не гарантирует ранжирование, индексацию, цитирование или включение сайта в ответы ИИ.
Роль Agent Card
A2A использует Agent Card как публичное описание агента: идентификация, возможности, навыки, поддерживаемые интерфейсы и требования к безопасности. Стандартный well-known путь — `/.well-known/agent-card.json`.
Карточка помогает клиенту понять, с каким агентом он имеет дело и какой способ взаимодействия выбрать. Она не должна раскрывать внутреннее состояние агента, приватные учётные данные или детали внутренней реализации, которые не нужны для взаимодействия.
Что проверяет AI Web Check
Для сайта, определённого как интернет-магазин, сервис делает один ограниченный запрос к публичной Agent Card и проверяет поддерживаемую структуру с учётом совместимости версий. Отсутствие карты — необязательный сигнал.
AI Web Check не отправляет A2A-сообщения, не создаёт задачи и не вызывает навыки агента. Диагностика заканчивается проверкой публичной Agent Card и безопасности объявленных адресов API.
Что должно быть публичным, а что нет
В публичной карточке уместны имя агента, описание, провайдер, возможности, навыки, URL интерфейсов и схемы безопасности. Секретный токен, закрытый ключ, cookie, подписанная сессия или URL со встроенными учётными данными там публиковать нельзя.
Если системе нужен расширенный Agent Card с чувствительными сведениями, A2A предусматривает доступ после аутентификации. Публичное описание должно оставаться минимальным и безопасным.
Типичные ошибки
- Agent Card указывает HTTP или приватный либо локальный адрес API.
- В интерфейсах объявлен способ взаимодействия, который сервер не поддерживает.
- Схема безопасности описана, но API фактически принимает запросы без авторизации.
- В JSON опубликованы API-ключ, bearer-токен, закрытый JWK или другие учётные данные.
Порядок проверки
Сначала проверьте Agent Card как обычный публичный JSON-документ: HTTPS, корректный тип содержимого, поддерживаемую версию и валидные URL интерфейсов. Затем отдельно тестируйте аутентификацию и правила авторизации самих операций.
Не используйте успешное получение Agent Card как доказательство, что серверные навыки агента безопасны. Публичное описание и выполнение действий — разные границы доверия.