Agent Card — A2A Docs

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

Где лежит#

Стандартное расположение — путь /.well-known/agent-card.json (well-known URI по RFC 8615). Другие механизмы обнаружения описаны в разделе 8.2 оригинала.

Из чего состоит#

Карточка разобрана на семь групп полей. Наведите на деталь или перемещайтесь стрелками: справа от каждой стоит её назначение, внизу прочитайте подробности.

ОбъектAgent Card

Источникспец. 4.4, 8

Версия1.0.0

Таблица полей#

В JSON имена полей записываются в стиле camelCase. Таблица составлена по краткой справке и странице «What's New» оригинальной документации; полный перечень полей смотрите в разделе 4.4.1 оригинала.

Поле	Что описывает
`name`, `description`, `version`	Имя, описание и версия агента.
`supportedInterfaces`	Список интерфейсов, через которые можно обратиться к агенту. У каждого есть `url`, `protocolBinding` (например, `JSONRPC`), `protocolVersion` (например, `1.0`) и необязательный `tenant`.
`capabilities`	Необязательные возможности: `streaming`, `pushNotifications`, `extendedAgentCard`, `extensions`.
`skills`	Список навыков агента. У каждого есть идентификатор, название, описание, теги и примеры.
`securitySchemes` и требования безопасности	Способы аутентификации: API-ключ, HTTP-аутентификация, OAuth 2.0, OpenID Connect, mTLS.
`defaultInputModes`, `defaultOutputModes`	Типы содержимого (MIME), которые агент принимает и отдаёт по умолчанию, например `text/plain`, `application/json`.
`provider`	Необязательно. Организация, отвечающая за агента: название и адрес сайта.
`documentationUrl`	Необязательно. Ссылка на дополнительную документацию об агенте.
`iconUrl`	Необязательно. Ссылка на значок агента.
`signatures`	Необязательные подписи Agent Card.

Обязательными в таблице спецификации (раздел 4.4.1) помечены supportedInterfaces и skills; provider, documentationUrl и iconUrl необязательны. Для остальных полей обязательность смотрите в оригинале.

Фрагмент из оригинала#

Так выглядит часть Agent Card в версии 1.0 (пример со страницы «What's New»; многоточие заменяет содержимое подписей):

json

{
  "supportedInterfaces": [
    {
      "url": "https://agent.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "extendedAgentCard": true
  },
  "signatures": [...]
}

Полный пример Agent Card приведён в разделе 8.5 оригинала.

Проверка возможностей#

Агент объявляет необязательные возможности в Agent Card. Если клиент пытается воспользоваться возможностью, которая не объявлена, агент ДОЛЖЕН вернуть соответствующую ошибку.

Возможность	Если не объявлена (`false` или поле отсутствует)	Ошибка
Push-уведомления, `capabilities.pushNotifications`	Операции настройки push-уведомлений: создание, получение, список, удаление	`PushNotificationNotSupportedError`
Потоковая передача, `capabilities.streaming`	`SendStreamingMessage`, `SubscribeToTask`	`UnsupportedOperationError`
Расширенная карточка, `capabilities.extendedAgentCard`	`GetExtendedAgentCard`	`UnsupportedOperationError`; если возможность объявлена, но карточка не настроена, то `ExtendedAgentCardNotConfiguredError`
Расширение с `required: true`	Клиент не заявил его поддержку в запросе	`ExtensionSupportRequiredError`

Клиентам СЛЕДУЕТ проверять поддержку по Agent Card, прежде чем использовать необязательные возможности.

Расширенная Agent Card#

Агент может отдавать более подробную версию Agent Card после аутентификации клиента. Для этого служит операция GetExtendedAgentCard; она доступна, только если в публичной карточке указано capabilities.extendedAgentCard: true.

Аутентификация. Клиент ДОЛЖЕН аутентифицировать запрос одной из схем, объявленных в публичной карточке.
Расширенные сведения. В зависимости от уровня аутентификации агент МОЖЕТ вернуть дополнительные навыки, возможности или настройки, которых нет в публичной карточке.
Замена карточки. Клиентам СЛЕДУЕТ заменить кэшированную публичную карточку полученной на время аутентифицированного сеанса или до смены версии карточки.

Рекомендации по безопасности смотрите в разделе 13.3 оригинала.

Подпись Agent Card#

Версия 1.0 позволяет подписывать Agent Card. Подпись делается по стандарту JWS (RFC 7515) над канонической формой JSON по RFC 8785 (JCS). Поле signatures при вычислении канонической формы исключается. Поддерживаются отделённые подписи с получением открытого ключа по jku или из доверенных хранилищ.

Если в карточке есть подписи, клиенту стоит проверить их до использования карточки.

Версия протокола#

В версии 1.0 версия протокола указывается не в карточке целиком, а в каждом интерфейсе (supportedInterfaces[].protocolVersion). Поэтому агент может открыть несколько интерфейсов с разными версиями, а клиент выбирает подходящий. Подробнее: «Протокол».