A2Aprotocol

Главная / Карточка агента

Карточка агента

Карточка агента — JSON-документ, с которого начинается любое взаимодействие по A2A. По ней клиент узнаёт, кто перед ним, что агент умеет и как к нему подключиться.

Спецификация A2A 1.0 · проверено 30.09.2026

Что это и зачем#

Карточка агента (Agent Card) решает задачу обнаружения: как незнакомому агенту понять, стоит ли поручать задачу этому агенту и как это сделать технически. Карточка описывает агента снаружи и ничего не раскрывает о его внутреннем устройстве — это следует из принципа непрозрачное выполнение.

Строение карточки агента: кто (name, description, provider, version), где подключаться (supportedInterfaces), что умеет (skills), как работать (capabilities, securitySchemes, режимы ввода и вывода), подпись (signatures).
Пять смысловых блоков карточки. Основной адрес подключения в версии 1.0 находится внутри supportedInterfaces, а не на верхнем уровне.

Где публикуется#

Стандартный способ — файл по адресу https://домен-агента/.well-known/agent-card.json. Путь зарезервирован по правилам RFC 8615, поэтому клиент может проверить его на любом домене без предварительной договорённости.

Кроме этого спецификация допускает два других способа: каталоги (реестры) агентов, которые собирают карточки централизованно, и прямую настройку, когда адрес карточки передан клиенту заранее. Для закрытых корпоративных агентов часто используют именно их.

Если агент предоставляет больше сведений только проверенным клиентам, он объявляет capabilities.extendedAgentCard: true, а полную версию отдаёт операцией GetExtendedAgentCard после аутентификации — это расширенная карточка агента.

Поля карточки#

Здесь достаточно четырёх групп полей, чтобы читать пример ниже. Таблица всех полей с типами и обязательностью — в документации на a2adocs.ru.

  • supportedInterfaces — адреса подключения. У каждого — url, protocolBinding (JSONRPC, GRPC или HTTP+JSON) и protocolVersion. Первый элемент считается основным.
  • capabilities — необязательные возможности: streaming, pushNotifications, extendedAgentCard, extensions.
  • skills — навыки агента: id, name, description, tags, examples.
  • securitySchemes — способы аутентификации, которые принимает агент.

Остальное — name, description, version, provider, defaultInputModes, defaultOutputModes, signatures, documentationUrl, iconUrl — описано в той же таблице.

Пример для версии 1.0#

Карточка публичного агента интернет-магазина без аутентификации. Названия и адреса вымышленные.

/.well-known/agent-card.json
{
  "name": "Ассистент каталога «Пример»",
  "description": "Подбирает товары из каталога магазина по описанию задачи и сообщает статус заказа.",
  "version": "1.2.0",
  "provider": {
    "organization": "ООО «Пример»",
    "url": "https://example.ru"
  },
  "supportedInterfaces": [
    {
      "url": "https://agent.example.ru/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "product-search",
      "name": "Подбор товаров",
      "description": "Находит товары по назначению, размерам и бюджету, возвращает список с ценами и наличием.",
      "tags": [
        "каталог",
        "подбор"
      ],
      "examples": [
        "Стеллаж для склада высотой 2 м, нагрузка на полку от 150 кг, до 30 000 ₽"
      ],
      "outputModes": [
        "application/json"
      ]
    },
    {
      "id": "order-status",
      "name": "Статус заказа",
      "description": "Сообщает состояние заказа по его номеру.",
      "tags": [
        "заказ"
      ],
      "examples": [
        "Где мой заказ 10452?"
      ]
    }
  ]
}

Файл примера: /agent-card/example.json. Схемы безопасности в примере опущены: их формат описан в разделе 4.5 спецификации и зависит от выбранного способа аутентификации.

Признаки хорошей карточки#

  • Навыки описаны конкретно. Не «помогаю с заказами», а «сообщаю статус заказа по номеру». Клиент выбирает агента по описанию навыка, расплывчатое описание снижает шанс, что задачу вообще поручат.
  • Есть примеры запросов. Поле examples показывает, в какой форме агент ждёт задачу, и заметно повышает точность выбора.
  • Указаны точные медиатипы. Если навык возвращает JSON, это должно быть видно в outputModes.
  • Адреса работают по HTTPS и отвечают. Карточка с недоступным адресом хуже, чем её отсутствие.
  • Версия агента меняется при изменении навыков: клиенты кэшируют карточки и по версии понимают, что пора обновить данные.
  • Карточка подписана, если агент публичный и через него проходят заказы или платежи.

Частые ошибки#

  • Старый путь. Файл лежит по адресу /.well-known/agent.json, как было до версии 0.3. Клиенты версии 1.0 его не найдут.
  • Поля версии 0.3 в карточке 1.0. url, preferredTransport, additionalInterfaces и protocolVersion на верхнем уровне в 1.0 удалены — всё это теперь внутри supportedInterfaces. Поле supportsAuthenticatedExtendedCard перенесено в capabilities.extendedAgentCard. Полное соответствие старых и новых полей — в разборе миграции.
  • Карточка без агента. Карточку публикуют, когда по указанному адресу реально отвечает A2A-сервер. Если на сайте нет агента, карточка вводит других агентов в заблуждение: они попытаются отправить задачу и получат ошибку.
  • Навыки без примеров и описание в одно слово.

Обычному сайту или интернет-магазину без собственного агента карточка A2A не нужна. Чтобы ИИ-агенты понимали такой сайт, достаточно машиночитаемой разметки товаров и организации, открытых цен и условий. Карточка появляется на следующем шаге, когда у компании есть агент, который сам принимает задачи.