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

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

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

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

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

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

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

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

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

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

{
  "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-сервер. Если на сайте нет агента, карточка вводит других агентов в заблуждение: они попытаются отправить задачу и получат ошибку.
• Навыки без примеров и описание в одно слово.