Руфат Нуриев обновлено

Карточка агента в A2A: полный пример JSON и разбор полей

Парсинг JSON-документа Agent Card на экране ноутбука

Карточка агента - JSON-документ, по которому клиентский агент понимает, кого вызвать, куда слать задачу и какие навыки доступны. В протоколе A2A (Agent2Agent) карточка обычно публикуется по адресу /.well-known/agent-card.json: без неё агент плохо обнаруживается, с размытым описанием - плохо маршрутизируется.

  • Карточка агента - публичный контракт возможностей агента
  • Обнаружение - поиск карточки по well-known URL (стандартному адресу обнаружения) или реестру
  • Навыки - конкретные навыки, а не общее «умею всё»
  • capabilities - streaming, push, расширенная карточка
  • Безопасность - схемы аутентификации в стиле OpenAPI

Схема обнаружения и маршрутизации Agent Card на прозрачной доске

Зачем нужна Карточка агента

A2A связывает независимых агентов: один выступает клиентом, другой - исполнителем. Перед отправкой задачи клиент читает карточку и отвечает на вопросы:

  1. Подходит ли этот агент под намерение пользователя?
  2. Какой эндпоинт принимать задачи?
  3. Какие MIME-типы (форматы данных, например application/json) на входе и выходе?
  4. Нужна ли аутентификация и какая именно?
  5. Поддерживаются ли поток событий и вебхук-уведомления?

Карточка - не маркетинговый текст. Её парсят оркестраторы и LLM-роутеры. Чем точнее description, skills и examples, тем стабильнее выбор исполнителя.

Что это значит для владельца бизнеса

Карточка агента - техническая деталь, но с бизнес-последствиями. Если она отсутствует или размыта, партнёрские системы и AI-оркестраторы просто не найдут ваш сервис среди альтернатив - как сайт без корректной SEO-разметки. Если карточка слишком открыта (например, capabilities или security не соответствуют реальным ограничениям), это риск: сторонний агент может попытаться вызвать операцию, которая не должна быть доступна извне.

Владельцу не обязательно писать JSON самому - но стоит спросить у команды разработки: какие навыки и данные видны внешним агентам, какая аутентификация требуется, и пройден ли чеклист ниже перед публикацией.

Полный пример JSON

Дальше идёт технический разбор JSON-полей для разработчика или подрядчика, который будет готовить карточку. Если вы владелец бизнеса и хотите понять только риски и что спросить у команды - этого достаточно из раздела «Что это значит для владельца бизнеса» выше и «Что нельзя публиковать в Карточке агента» ниже.

Ниже - рабочий пример карточки для агента, который ищет товары на сайте, считает стоимость и создаёт заявку после подтверждения. Поля даны в camelCase, как в типичных JSON-карточках A2A.

{
  "name": "Site Commerce Agent",
  "description": "Ищет товары в каталоге сайта, рассчитывает стоимость и срок, создаёт заявку после подтверждения пользователя. Работает с каталогом, корзиной-черновиком и статусами заказов. Не выполняет оплату и не меняет цены.",
  "version": "1.2.0",
  "protocolVersion": "0.3.0",
  "url": "https://api.example.com/a2a",
  "documentationUrl": "https://docs.example.com/a2a/commerce-agent",
  "iconUrl": "https://example.com/icons/commerce-agent.svg",
  "provider": {
    "organization": "Example Shop",
    "url": "https://example.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "supportsAuthenticatedExtendedCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "search-products",
      "name": "Поиск товаров",
      "description": "Ищет товары по запросу, категории, цене и наличию. Возвращает список кандидатов с id, названием, ценой и кратким описанием.",
      "tags": ["catalog", "search", "products"],
      "examples": [
        "Найди ноутбуки до 800 евро с доставкой на этой неделе",
        "Покажи доступные тарифы для команды из 20 человек"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "calculate-quote",
      "name": "Расчёт стоимости",
      "description": "Считает цену, налоги, доставку и срок для выбранных позиций и количества. Не создаёт заказ.",
      "tags": ["pricing", "quote", "shipping"],
      "examples": [
        "Посчитай стоимость 3 единиц product_id=sku-1042 с доставкой в Берлин",
        "Сравни тариф Basic и Pro для 50 пользователей"
      ],
      "inputModes": ["application/json", "text/plain"],
      "outputModes": ["application/json"]
    },
    {
      "id": "create-lead",
      "name": "Создание заявки",
      "description": "Создаёт черновик заявки или лида после явного подтверждения пользователя. Требует контакт и согласие на обработку данных.",
      "tags": ["lead", "order-draft", "crm"],
      "examples": [
        "Создай заявку на тариф Pro для команды ACME, контакт: ops@acme.example",
        "Оформи черновик заказа по расчёту quote_id=q-7781"
      ],
      "inputModes": ["application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "get-order-status",
      "name": "Статус заказа",
      "description": "Возвращает статус оплаты и доставки по order_id для авторизованного пользователя или публичного трек-номера.",
      "tags": ["orders", "status", "tracking"],
      "examples": [
        "Какой статус у заказа ORD-20441?",
        "Где посылка с трек-номером TRK-998877?"
      ]
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    },
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "https://auth.example.com/oauth/token",
          "scopes": {
            "catalog:read": "Чтение каталога и расчётов",
            "leads:write": "Создание заявок",
            "orders:read": "Чтение статусов заказов"
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": ["catalog:read"]
    },
    {
      "bearer": []
    }
  ]
}

В A2A v1.0 эндпоинт часто описывают массивом supportedInterfaces вместо одного верхнеуровневого url. Смысл тот же: указать, куда клиент шлёт задачи и каким способом связывания пользоваться (JSONRPC, HTTP+JSON, GRPC и т.д.).

Пример фрагмента для v1.0:

{
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ]
}

Разбор полей верхнего уровня

Поле Обязательность Назначение
name Да Человекочитаемое имя агента
description Да Кратко и конкретно: что делает, чего не делает
version Да Версия самого агента - лучше semver
url / supportedInterfaces Да* Endpoint(ы) для задач, не URL самой карточки
skills Да Минимум один навык
capabilities Да Честные флаги возможностей
defaultInputModes / defaultOutputModes Да MIME по умолчанию
provider Нет Организация-владелец
documentationUrl / iconUrl Нет Документация и иконка для UI
protocolVersion Зависит от версии схемы Версия протокола (в v0.3 часто наверху)
securitySchemes / security Нет Как клиенту аутентифицироваться

* В схемах v0.3 обычно обязателен url. В v1.0 роль эндпоинта берёт на себя supportedInterfaces.

name и description

name нужен людям и логам. description читают роутеры. Плохо: «Полезный агент для сайта». Хорошо: перечислить операции, ограничения и формат результата.

version

Это версия реализации агента, не обязательно версия протокола. Меняйте мажор при несовместимых изменениях в навыках или контракте ответа. Клиенты могут кэшировать карточку и обновлять её по смене версии.

url - частая ошибка

url - адрес, куда уходят message/send / задачи. Это не путь к /.well-known/agent-card.json.

Неправильно:

"url": "https://example.com/.well-known/agent-card.json"

Правильно:

"url": "https://api.example.com/a2a"

capabilities

Флаг Смысл
streaming Поддержка потоковых ответов
pushNotifications Webhook-уведомления о долгих задачах
stateTransitionHistory История переходов статусов задачи
supportsAuthenticatedExtendedCard После auth доступна расширенная/приватная карточка

Ставьте true только если реально реализовали поведение. Клиент, который откроет поток к агенту без streaming, получит ошибку.

defaultInputModes и defaultOutputModes

MIME-типы по умолчанию для всего агента. У навыка можно переопределить. Типичные значения: text/plain, application/json, application/pdf, image/png.

Разбор skills

Навык - единица маршрутизации. Один навык = одна понятная способность.

Поле Обязательность Комментарий
id Да Уникальный в рамках агента, удобен kebab-case
name Да Короткое имя для UI
description Да Что принимает, что возвращает, какие ограничения
tags Нет Ключевые слова для поиска и фильтрации
examples Нет, но очень желательно 2-3 реальных промпта для оркестратора
inputModes / outputModes Нет Override MIME для этого навыка

Примеры - не украшение. Без них модель-оркестратор угадывает входы только по описанию и чаще ошибается.

Плохой навык:

{
  "id": "website",
  "name": "Website",
  "description": "Работает с сайтом"
}

Хороший навык - как в полном примере выше: конкретный id, границы ответственности, tags и examples.

Аутентификация: securitySchemes и security

Схемы обычно повторяют подход OpenAPI:

  • apiKey
  • http (Basic / Bearer)
  • oauth2
  • openIdConnect
  • mutualTLS

securitySchemes описывает доступные методы. security задаёт требование по умолчанию:

  • несколько объектов в массиве security = альтернативы;
  • несколько ключей в одном объекте = нужно всё сразу.

В карточке публикуют как аутентифицироваться, а не секреты. Не кладите API-ключи, refresh-токены и внутренние hostname в JSON.

Обнаружение: как карточку находят

Типичный путь:

  1. Клиент знает базовый домен агента.
  2. Запрашивает https://agent.example.com/.well-known/agent-card.json.
  3. Валидирует обязательные поля.
  4. Выбирает навык по описанию, tags и examples.
  5. Аутентифицируется по security.
  6. Отправляет задачу на url / supportedInterfaces.

Карточку также публикуют в реестре или каталогах агентов. Тогда обнаружение идёт через поиск, а well-known остаётся источником истины у владельца.

Проверка локально:

curl -s https://api.example.com/.well-known/agent-card.json

Что нельзя публиковать в Карточке агента

  • API-ключи, пароли, private keys;
  • внутренние URL админок и предбоевого контура без защиты;
  • операции, недоступные внешним клиентам;
  • завышенные capabilities («streaming: true» без реализации);
  • размытые навыки вроде «делает всё по сайту».

Публичная карточка - поверхность атаки и поверхность маршрутизации одновременно. Держите её точной и минимально достаточной.

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

  1. Перепутан url и URL карточки.
  2. Пустой массив skills. Агент становится практически ненаходимым для роутинга.
  3. Описание без границ. Не сказано, чего агент не делает (оплата, удаление, смена цен).
  4. Нет examples. Оркестратор хуже понимает валидный ввод.
  5. localhost в прод-карточке. Эндпоинт должен быть достижим для клиентов.
  6. Один навык на весь продукт. Лучше несколько узких навыков с разными правами и MIME.

Мини-чеклист перед публикацией

  1. Карточка отдаётся по HTTPS с корректным Content-Type: application/json.
  2. Есть name, description, version, эндпоинт и хотя бы один навык.
  3. description и описания навыков конкретны.
  4. У ключевых навыков есть examples и tags.
  5. capabilities соответствуют реальному серверу.
  6. В JSON нет секретов.
  7. Эндпоинт из карточки отвечает на тестовую задачу.
  8. Версия увеличивается при несовместимых изменениях.

Когда Карточка агента не нужна

Если бизнес пока не планирует интеграции с внешними AI-агентами, маркетплейсами агентов или партнёрскими оркестраторами, полноценная карточка может подождать. Она не критична для:

  • внутреннего чат-бота на сайте, который отвечает только людям через веб-виджет;
  • MVP без публичного API, где интеграции с другими агентами появятся позже;
  • сценариев, где агент вызывается напрямую вашим же кодом, а не сторонними системами.

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

Итог

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

Если нужно спроектировать карточку агента и API для A2A-интеграции - свяжитесь со мной.

Часто задаваемые вопросы

Где должна лежать Карточка агента?

Стандартный публичный путь - /.well-known/agent-card.json на домене агента. Дополнительно карточку можно зарегистрировать в каталоге или реестре, но well-known URL остаётся удобной точкой обнаружения без отдельного индекса.

Чем url отличается от адреса карточки?

Адрес карточки нужен для обнаружения, url (или supportedInterfaces) - для выполнения задач. Клиент сначала читает JSON-карточку, затем отправляет сообщения/задачи на рабочий эндпоинт агента.

Сколько навыков должно быть в карточке?

Столько, сколько реально разных способностей с разными входами или правами. Обычно лучше 3-7 узких навыков, чем один общий «сделай всё». Для роутинга важны точные границы, tags и examples.

Обязательна ли аутентификация в Карточке агента?

Не всегда. Публичный агент, доступный только для чтения, может работать без security. Для записи, персональных данных и платных операций укажите securitySchemes и security, а секреты храните вне карточки.

Нужно ли обновлять карточку при каждом деплое?

Обновляйте, когда меняются навыки, эндпоинт, capabilities, auth или смысл агента. Технический патч без изменения контракта можно отражать в version; несовместимые изменения лучше сопровождать мажорной версией и явной документацией.

Термины в статье

A2A — Agent-to-Agent — протокол взаимодействия ИИ-агентов друг с другом

эндпоинт — endpoint — точка API / конкретный URL API (endpoint)

LLM — Large Language Model — большая языковая модель

semver — versioning as MAJOR.MINOR.PATCH for compatibility signals — версии мажор.минор.патч (MAJOR.MINOR.PATCH) как сигнал совместимости

endpoint — specific API URL that accepts requests — конкретный URL API, который принимает запросы

webhook — HTTP callback when an event happens — HTTP-уведомление при наступлении события

API-ключи — API keys — секретные токены для доступа к API

оркестратор — orchestrator — компонент, координирующий шаги (orchestrator)

MVP — Minimum Viable Product — минимально жизнеспособный продукт

Контакты