# Agent Card

Как агент рассказывает о себе

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/concepts/agent-card/). Тип: Перевод и пересказ. Основа: Спецификация, разделы 3.1.11 и 3.3.4; What's New; краткая справка (https://a2a-protocol.org/latest/specification/#3111-get-extended-agent-card). Версия спецификации 1.0.0, сверено 05.10.2026.

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

## Где лежит

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

> **Заметка переводчика.** В версии 0.3 карточка тоже публиковалась по пути `/.well-known/agent-card.json`. Изменилась структура содержимого, а не адрес: см. [«Миграцию»](https://a2adocs.ru/migration/#agent-card).

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

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



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

В 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` необязательны. Для остальных полей обязательность смотрите в оригинале.

> **Заметка переводчика.** Требования безопасности названы в источниках по-разному: в тексте спецификации встречается `AgentCard.security`, в краткой справке — `security_requirements`, а в справочнике Google Cloud JSON-представление карточки использует `securityRequirements`. Точное имя берите из a2a.proto.

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

Так выглядит часть 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`). Поэтому агент может открыть несколько интерфейсов с разными версиями, а клиент выбирает подходящий. Подробнее: [«Протокол»](https://a2adocs.ru/protocol/#versionirovanie).