Вики
Блог nikolskiy.dev

Agent Card

Публичный паспорт агента: JSON-документ, из которого чужая система узнаёт, что этот агент умеет, как с ним аутентифицироваться и куда слать задачи. Механизм обнаружения в протоколе A2A — то, что позволяет поручить работу агенту, чей код вы никогда не увидите.

Суть

Чтобы делегировать задачу чужому агенту, нужно сначала его найти и понять, подходит ли он. Agent Card — ответ на оба вопроса. Каждый агент, говорящий по A2A, обязан опубликовать такую карточку, причём по предсказуемому адресу: /.well-known/agent-card.json. Логика та же, что у robots.txt — клиент знает, куда смотреть, без предварительной договорённости.

Спецификация (§8.2) описывает три способа обнаружения, а не один: well-known URI, реестры и каталоги агентов, прямая конфигурация URL карточки. Путь /.well-known/agent.json встречается в материалах до v0.3 — это легаси.

Ключевое свойство: карточка описывает агента снаружи, ничего не раскрывая о внутренностях. Это осознанный выбор протокола — он рассчитан на «непрозрачных» агентов от разных поставщиков, где заглядывать внутрь нельзя ни по техническим, ни по коммерческим причинам.

Что внутри

  • Идентификация — имя, описание, версия.
  • Skills — перечень навыков: что агент берётся делать, с какими входами и выходами. По ним клиент выбирает исполнителя под конкретную задачу.
  • Capabilities — поддерживает ли стриминг, push-уведомления, какие типы контента понимает.
  • Схема аутентификации — как к нему стучаться легально.
  • supportedInterfaces — массив интерфейсов в порядке предпочтения; каждая запись несёт url, protocolBinding (JSONRPC / GRPC / HTTP+JSON) и protocolVersion. В версиях до 1.0 на этом месте были плоские поля url + preferredTransport — их больше нет.

Клиентская сторона забирает карточку (в SDK за это отвечают резолверы вроде A2ACardResolver), сравнивает объявленные навыки с задачей и решает, кому делегировать.

Границы ответственности

Протокол разводит роли явно, и карточка — центр этой договорённости:

  • Remote agent обязан опубликовать честную карточку, принять или отклонить задачу, работать в рамках объявленных skills, не просить лишних прав и вернуть артефакт со статусом.
  • Client agent формулирует задачу, выбирает исполнителя по карточке, хранит свой контекст, принимает артефакт и решает, доверять ли результату.

Отсюда же вырастает безопасность: карточку подписывают, соединение защищают TLS, права выдают по принципу наименьших привилегий.

Чем подпирается честность карточки

Формулировка «честность карточки — вопрос доверия, а не техники» верна только наполовину: часть проблемы закрывается технически, часть действительно нет.

Что закрывается. Спецификация (§8.4) разрешает подписывать карточку по JWS (RFC 7515), причём перед подписью карточку обязательно приводят к канонической форме по JCS (RFC 8785) — иначе подпись развалится на переупорядочивании ключей. Это делает карточку tamper-evident: подменить её содержимое незаметно нельзя.

Что не закрывается подписью. Red Hat формулирует разрыв точно: карточка несёт метаданные и подпись, но «nothing inherently ties that metadata back to the workload actually serving it at runtime». Подписанная карточка доказывает, что документ не подменили, — но не то, что отдаёт её тот, за кого себя выдаёт. Их аналогия: визитку с надписью «врач» может напечатать кто угодно. Отсюда предложение привязывать карточку к workload-identity через SPIFFE/SPIRE и контролировать вызовы на уровне mesh-identity.

Что не закрывается вообще. Заявленный навык может быть заявлен добросовестно и выполняться плохо. Это вопрос репутации и проверки результата, а не криптографии.

Смежный сдвиг, который стоит держать в голове: discovery в мире агентов идёт не по имени сервиса, а по навыку («найди агента, умеющего разбирать финансовые таблицы»). Старая модель авторизации «может ли сервис A звать сервис B» на это не ложится.

Аналогия

Если MCP — это USB-C для инструментов (один разъём, через который агент дотягивается до базы или API), то A2A с его карточками ближе к телефонной сети: у каждого абонента есть номер и справочник возможностей, а что происходит на той стороне — не ваше дело.

Связано с

  • Agent2Agent Protocol — протокол, частью которого является карточка
  • A2A Task Lifecycle — что происходит после того, как исполнитель выбран
  • MCP — вертикальный протокол; A2A и карточки решают горизонтальную задачу
  • Multi Agent Systems — разница между агентами внутри одной системы и чужими агентами

Открытые вопросы

  • нужен ли реестр карточек в корпоративном контуре или хватает статических адресов
  • как оценивать качество объявленного навыка до первой задачи — тестовым прогоном или репутацией; подпись эту часть не закрывает
  • переносится ли связка SPIFFE/SPIRE за пределы Kubernetes, где workload-identity не выдаётся автоматически