Вики
Блог 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 с его карточками ближе к телефонной сети: у каждого абонента есть номер и справочник возможностей, а что происходит на той стороне — не ваше дело.

Что решать самому

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

Как оценить навык до первой задачи. Подпись карточки удостоверяет, кто её выпустил, но ничего не говорит о том, умеет ли агент заявленное — эти два вопроса не связаны, и смешивать их опасно именно потому, что подпись создаёт ложное ощущение проверки. Репутация работает только там, где есть история взаимодействий, то есть не для нового агента. Остаётся тестовый прогон: небольшой набор задач с известным ответом, прогоняемый перед подключением и периодически после — по сути тот же eval-набор (Agent Evals), только направленный на чужой агент. Это единственный способ узнать про качество до того, как ошибка попадёт в рабочий поток.

SPIFFE/SPIRE вне Kubernetes

Сверка 2026-08: переносится полностью — SPIRE изначально не привязан к Kubernetes и штатно работает на виртуальных машинах, физических серверах и в гибридных средах. Меняется не архитектура, а способ подтверждения личности узла, и вот тут появляется работа, которой в Kubernetes не было.

В кластере агент запускается как DaemonSet, а личность узла подтверждается самим кластером. Вне его агент ставится системным демоном на каждую машину, и attestor узла надо выбрать: облачный (для EC2, Compute Engine — личность подтверждает провайдер), TPM (аппаратный корень доверия), существующий X.509-сертификат узла — рабочий вариант для датацентров, где машины разворачивают вручную, — или join token как самый простой и самый слабый.

Подтверждение самой рабочей нагрузки при этом устроено одинаково везде: агент опрашивает свои attestor'ы по идентификатору процесса, те собирают признаки через вызовы ядра и пространства пользователя и возвращают селекторы, по которым выдаётся идентичность.

Практический вывод для карточек агентов: связка применима и вне кластера, но цена входа смещается с настройки на выбор корня доверия. Join token переносится проще всего и даёт наименьшие гарантии — то есть ровно то, чего от подписи карточки и ждут; TPM или сертификат узла дают настоящее подтверждение, но требуют инфраструктурного решения заранее.

Связано с

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