Полный учебник JSON Schema A2A Agent Card: имя, возможности, skills, интерфейсы и endpoint

Для кого эта карточка

Agent Card — публичная визитка, которую A2A-сервер вешает на /.well-known/agent-card.json. Читатель — не ваша модель, а другой оркестратор, шлюз или каталог в организации. Карточка отвечает на три фразы: кто вы, как к вам подключиться, что вы берётесь делать. Первое: name / description / version. Второе: supportedInterfaces. Третье: skills[]. Залить runbook в description — первым ударитесь о 10 КБ; поверхность открытия худеет.

Версия 1.0 фиксирует обязательное. В таблице спеки name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes и skills помечены Yes. Нет одного — клиент 1.0 не должен читать файл как легальную карточку. 0.3 жила верхними url и protocolVersion. Клиент 1.0 их игнорирует и читает массив интерфейсов. Смешать оба набора — извлечение каталога молча худеет, в тикете снова «не нашли».

Карточка — не Plugin Manifest и не MCP tools/list. Как coding-агент растит навыки — статья про Plugin. Как hop вызова проверяет аргументы — MCP и JSON Schema. Сегодня только о том, как боковой коллега описывает себя. Подписи, расширенные карточки и GetExtendedAgentCard — после auth. Публичная карточка сначала называет навыки.

Идентичность: name, description, version, provider

name — для людей, которые сканируют каталог, не внутреннее имя сервиса. description задаёт рамку и границу: что делаете и чего не делаете. Специалист по возвратам может написать «классифицирует заявки на возврат; не проводит возврат денег». Оркестраторы решают, слать ли Task, по этому абзацу, не по README.

version — релиз этого агента, например 1.0.3. Версия протокола едет с интерфейсом, в supportedInterfaces[].protocolVersion. Написать 1.0 в обоих местах — потом не понять, какая сторона сдвинулась. provider необязателен, но если есть — пара: organization плюс url. documentationUrl и iconUrl тоже необязательны; длинный текст — на URL документации, не в визитку.

После блока идентичности остановитесь. Без интерфейсов карточку нельзя вызвать. Без skills каталог вас не найдёт. Первую из трёх фраз держите короткой и честной, потом заполняйте эндпоинты.

Интерфейсы: endpoint — это supportedInterfaces

В 1.0 основной эндпоинт не наверху. supportedInterfaces — упорядоченный массив; первый элемент предпочтителен. У каждого обязательны url, protocolBinding и protocolVersion. Боевой url — абсолютный HTTPS. Официальные ядра: JSONRPC, GRPC, HTTP+JSON; спека оставляет строку открытой для расширений. tenant необязателен — только для мультиаренды.

Один агент может перечислить три привязки на трёх URL. Клиенты берут первый, на котором умеют говорить, в порядке массива. Не указывайте все три на один и тот же 404 ради полноты. Верхние url и protocolVersion из 0.3 — старый контракт; страница изменений v1.0 говорит, что они больше не главные. Регистрация как 1.0 с URL наверху: валидация 1.0 должна упасть, либо основной эндпоинт проигнорируют.

Массив интерфейсов решает, как вы говорите, не чем занимаетесь. JSONRPC без skills: достучаться можно, найти нельзя. Skills без интерфейсов: найти можно, Task не послать. Нужны оба блока.

capabilities и MIME по умолчанию

capabilities в 1.0 — обязательный объект; булевы внутри необязательны: streaming, pushNotifications, extendedAgentCard плюс массив extensions. Нет или false — соответствующая операция должна ошибиться, не молча ретраиться. Не возвращайте stateTransitionHistory из 0.3 как ядерную возможность. В таблице 4.4.3 её больше нет.

defaultInputModes и defaultOutputModes — массивы медиатипов на все skills. Один skill может перекрыть через inputModes / outputModes. Только текст: text/plain. JSON наружу: добавьте application/json. Пустой массив — незаявленная карточка; валидация 1.0 должна упасть. Ни расширений файлов, ни частных enum.

extendedAgentCard true значит: после auth можно забрать вторую, более полную карточку. Публичная всё равно должна стоять сама: навыки, интерфейсы, MIME по умолчанию. Спрятать критический skill только в расширенной — неаутентифицированные каталоги промахнутся на поверхности поиска.

skills[]: id, tags, examples

У каждого skill обязательны id, name, description и tags. id — стабильный короткий программный ключ без пробелов. name — для людей. description задаёт границы ввода-вывода, это всё ещё не схема аргументов. tags в 1.0 — обязательный массив строк для каталога и оркестратора. Google Registry тоже индексирует tags. Пусто или нет: файл может распарситься, вас не найдут.

examples — необязательные подсказки или сцены для людей, не JSON Schema. 1.0 не считает inputSchema контрактом навыка. Старые реализации ещё вешают схему; намёк можно, контракт tools/call нельзя. Напротив непрозрачный агент; вы шлёте Task. Фрагмент 0.3 на сайте с inputSchema на skill — старый контракт. В новую карточку не копируйте.

Не режьте skills по внутренним именам функций. Один skill — один род работы, который оркестратор делегировал бы. Специалист по возвратам может открыть classify-return и check-window, а не «читать таблицу», «писать лог», «слать почту» как три поисковых слова. Ниже карточка 1.0 в репозиторий. Сначала parse, потом официальная схема.

{
  "name": "Returns Specialist",
  "description": "Classifies return requests and checks the return window. Does not post refunds.",
  "version": "1.0.3",
  "provider": {
    "organization": "Example Commerce",
    "url": "https://commerce.example.com"
  },
  "documentationUrl": "https://docs.example.com/returns-agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    },
    {
      "url": "https://agents.example.com/returns/a2a/json",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide whether a request is a return, exchange, or warranty claim.",
      "tags": ["returns", "classify", "commerce"],
      "examples": ["This jacket arrived damaged. Is it a return or a warranty claim?"]
    },
    {
      "id": "check-window",
      "name": "Check return window",
      "description": "Say whether the purchase is still inside the return window.",
      "tags": ["returns", "policy", "deadline"],
      "examples": ["Order 8841 was delivered on 2026-08-02. Can they still return it?"]
    }
  ]
}

Чего не должно быть в карточке 1.0

Оставьте хотя бы один негатив: верхний url ещё есть, у skill нет tags, плюс inputSchema в форме MCP. Валидация 1.0 должна упасть. Если CI сваливает 0.3 и 1.0 в «общую проверку агента», вы грязнее клиента. Registry выбирает правила по заявленной версии и не ходит за схемой при загрузке.

{
  "name": "Returns Specialist",
  "description": "Classifies return requests.",
  "version": "1.0.3",
  "url": "https://agents.example.com/returns/a2a",
  "protocolVersion": "1.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide the request type.",
      "inputSchema": {
        "type": "object",
        "required": ["orderId"],
        "properties": {
          "orderId": { "type": "string" }
        }
      }
    }
  ]
}

securitySchemes и требования безопасности — необязательный слой. Публичная карточка может выйти без подписей. signatures — JWS; прогулка проверки — в практической статье. Запомните: подпись не заменяет tags. Честная карточка с одним настоящим skill лучше красивой с пустым массивом. skills по-прежнему обязательный массив — ноль элементов только если навыков правда нет.

Не копируйте закрытые поля Plugin, пути SKILL.md и MCP tools[].name в Card. Три JSON говорят «возможность»; обработка отказа разная. Сломанная Card — отказ обнаружения.

В браузере:Форматтер JSON — парсится ли карточка;Валидатор JSON Schema — проверить 1.0 supportedInterfaces и skills[].tags;JSON Diff — поймать верхний url / дырки в tags между закоммиченной карточкой и негативом. Данные не уходят с машины. Дальше:обзор Agent Registry и A2A vs MCP. Прогулка по обнаружению — следующая статья.

Рядом: Google Agent Registry, A2A vs MCP, MCP и JSON Schema.

FAQ

Итог и следующие шаги

В 2026 A2A Agent Card складывается в одну обязательную таблицу: три поля идентичности, массив интерфейсов, объект capabilities, MIME по умолчанию и skills с tags. Оркестраторы читают эти поля, не слайд архитектуры.

Порядок: легальная карточка 1.0; первый интерфейс — настоящий эндпоинт; у каждого skill непустые tags; parse и схема в JSONVue. Как каталог ест карточку — прошлая статья. Хопы — следующая. Подписи и чеклист — позже.