Агенты A2A

Используйте A2A, когда один агент поручает работу другому. MCP предоставляет инструменты и ресурсы, а A2A описывает сообщения агентов, задачи, обновления состояния и артефакты. Оба протокола можно хранить в одной локальной спецификации, не смешивая их назначение.

Создание и отладка

В разделе отладки выберите Новый запрос → A2A. По умолчанию используется A2A 1.0, JSON-RPC поверх HTTP.
Укажите JSON-RPC-эндпоинт агента в строке URL. Для старых агентов явно выберите версию 0.3: Powerduck не преобразует версии незаметно.
На вкладке протокола выберите метод и нажмите Создать тело запроса. Проверьте предпросмотр и выберите Заменить тело запроса, чтобы применить шаблон. Отмена или смена метода сохраняет текущий черновик.
Отредактируйте params на вкладке тела. Учётные данные задавайте в разделах аутентификации и заголовков; при отправке добавляется выбранный заголовок A2A-Version.
Отправьте запрос. Проверьте весь конверт JSON-RPC: ответ HTTP 200 всё ещё может содержать error. Успешные ответы 1.0 помещают task или message внутрь result; версия 0.3 использует собственные структуры ответов.
Чтобы добавить быстрый запрос, используйте Сохранить в спецификацию. Для существующей операции Сохранить сохраняет локальные настройки отладки, а Обновить спецификацию явно меняет определение. Версия, эндпоинт, метод и документированные схемы хранятся в x-a2a; локальные черновики запросов в OAS не экспортируются. Контракт протокола редактируется через Изменить документацию.

ID сообщений и ID запросов JSON-RPC различаются. Новый пример создаёт новые идентификаторы. Чтобы продолжить разговор, передайте в следующем сообщении возвращённые идентификаторы контекста и задачи согласно выбранной версии протокола.

Agent Card

Используйте Получить публичную Agent Card с явно указанным URL, обычно /.well-known/agent-card.json. Перед настройкой эндпоинта проверьте заявленные интерфейсы, версию, навыки, аутентификацию и возможности. Получение карточки не меняет URL запроса автоматически и не пересылает учётные данные на другой источник.

Публичное обнаружение не отправляет учётные данные запроса и запрещает перенаправления. Настольная версия использует нативный исполнитель HTTP, а браузеру требуется CORS. Ответ ограничен 1 MiB. Для A2A 1.0 раскройте Проверить подпись JWS и вставьте доверенный публичный JWKS. Проверка выполняется локально, поддерживает асимметричные подписи и никогда не переходит по URL ключей из карточки. Обязательные пустые значения сохраняются согласно закреплённому в проекте A2A proto. Дополнительные поля вне стандартной схемы карточки не аутентифицируются. Неподписанные и непроверенные карточки явно помечены; сохранение снимка не сохраняет решение о доверии. Для защищённых метаданных используйте RPC расширенной карточки с аутентификацией запроса. Сохранить карточку в спецификацию сохраняет только снимок; удалите частные метаданные перед публикацией или размещением спецификации.

Задачи и потоковая передача

Для 1.0 используйте SendStreamingMessage или SubscribeToTask, для 0.3 — message/stream или tasks/resubscribe. Ответы отображаются в существующем просмотрщике SSE с ограничениями размера и управлением отменой. Исходные обновления состояния и артефактов доступны для изучения.

Остановить разрывает локальный запрос, но не отменяет удалённую работу. Для запроса удалённой отмены отправьте CancelTask в 1.0 или tasks/cancel в 0.3 с возвращённым ID задачи. Задачу в конечном состоянии нельзя просто запустить заново.

Доступны получение задач, их список в 1.0, расширенные карточки и методы настройки push-уведомлений. A2A 1.0 предоставляет их через все три привязки; 0.3 использует JSON-RPC. Необязательные операции зависят от заявленных возможностей агента. Powerduck не размещает приёмник push-уведомлений.

Расширение OpenAPI

x-a2a — расширение OpenAPI от Powerduck, а не стандартная Agent Card A2A и не стандартное ключевое слово OpenAPI. Операции JSON-RPC используют post. Путь OpenAPI обозначает документируемую операцию; endpoint содержит настоящий удалённый URL JSON-RPC.

openapi: 3.2.0
info:
  title: Research agent
  version: 1.0.0
paths:
  /agents/research/send:
    post:
      summary: Ask the research agent
      x-protocol: a2a
      x-a2a:
        version: '1.0'
        binding: JSONRPC
        endpoint: https://agent.example.com/rpc
        agentCardUrl: https://agent.example.com/.well-known/agent-card.json
        method: SendMessage
        requestSchema:
          type: object
          description: Application-specific message parameters
        responseSchema:
          type: object
          description: JSON-RPC response envelope
        example:
          jsonrpc: '2.0'
          id: request-1
          method: SendMessage
          params:
            message:
              messageId: message-1
              role: ROLE_USER
              parts:
                - text: Summarize the release notes
      responses:
        '200':
          description: A2A response; inspect result or error
          content:
            application/json:
              schema:
                type: object

Для потоковых ответов используйте text/event-stream с itemSchema из OAS 3.2, описывающей одно событие JSON-RPC. Редактор поддерживает независимые схемы запроса и ответа. Опубликованная документация и копирование для LLM сохраняют конфигурацию A2A и документированные контракты.

Поле	Значение
`version`	Поддерживаемая версия формата передачи: `1.0` или `0.3`
`binding`	`JSONRPC`; A2A 1.0 также поддерживает `HTTP+JSON` и `GRPC`
`endpoint`	Эндпоинт JSON-RPC, базовый URL REST или адрес узла gRPC с HTTP(S)
`method`	Метод выбранной версии: REST/gRPC используют это значение, JSON-RPC — метод из тела
`agentCardUrl`	URL публичного обнаружения
`agentCard`	Необязательный сохранённый снимок метаданных
`requestSchema`, `responseSchema`	Явно документированные контракты, а не схемы, выведенные из одного полученного ответа
`example`	Конверт JSON-RPC либо непосредственный объект запроса REST/gRPC

REST и gRPC

Выбирайте Транспортную привязку независимо от версии и метода. A2A 1.0 поддерживает JSON-RPC, REST и нативный gRPC. A2A 0.3 сохраняет поддержку JSON-RPC; неподдерживаемые сочетания отклоняются, а не преобразуются автоматически.

Для REST строка URL содержит базовый адрес, например https://agent.example/rest. Метод определяет HTTP-глагол и суффикс пути. В теле редактируется непосредственно объект запроса, без полей конверта jsonrpc, id и params. Идентификаторы задач кодируются как сегменты пути; фильтры и пагинация становятся параметрами запроса. Отладка и генерация кода документации используют одинаковое сопоставление.

Нативный gRPC требует настольного приложения. Используйте https://host:port для TLS с системным хранилищем доверенных сертификатов или http://localhost:port для локальных незашифрованных тестов. Компонент пути отсутствует. Заголовки становятся метаданными gRPC. Вызовы используют официальный дескриптор lf.a2a.v1.A2AService с преобразованием ProtoJSON для вложенных данных, перечислений и двоичных полей. Остановка отменяет локальный вызов, но не удалённую задачу. Скрипты HTTP, прокси и пользовательские настройки TLS для этой привязки отклоняются, а не игнорируются.

Смена версии или привязки сохраняет черновик. Нажмите Создать тело запроса, проверьте шаблон и подтвердите Заменить тело запроса, чтобы применить правильную структуру. Несовместимый конверт отклоняется до отправки. Обнаруженные интерфейсы можно применить явно; A2A больше не наследует автоматически посторонний сервер документа.

Генерация сервера

Раскройте Создать сервер → Скачать проект сервера. Архив содержит проект Node 22+, предоставляющий JSON-RPC, REST и gRPC через единый HTTP-обработчик бизнес-логики, а также публичную Agent Card. Выполните npm install, настройте A2A_TOKEN длиной не менее 32 случайных символов и HANDLER_URL, затем запустите npm start.

Обработчик получает {message, contextId} и возвращает Message с непустым parts. В архив не включаются секреты или учётные данные текущего запроса. Сгенерированный сервис ограничивает размеры данных, задаёт обработчику 60-секундный срок, ограничивает параллельные вызовы, очищает ресурсы при завершении и при необходимости подписывает JWS через SIGNING_JWK_FILE.

Это адаптер сообщений без состояния, а не автономная модель или движок долговременных задач. Долговременные задачи, их отмена и push-доставка требуют собственного исполнителя и постоянного хранилища. Карточка не заявляет поддержку push. Перед публичным развёртыванием настройте публичные URL, TLS и ограничения частоты запросов на обратном HTTP-прокси; для нескольких пользователей замените идентификацию по общему токену. Эти требования записаны в сгенерированном README.

Совместимость подписей

Проверка учитывает присутствие полей по A2A 1.0 и канонический JSON RFC 8785, включая обязательные пустые строки и массивы, а также явно заданные необязательные логические значения. Подписи, созданные после удаления обязательных полей, отклоняются: подпишите данные повторно совместимым канонизатором. Успешная проверка подтверждает стандартные поля относительно предоставленного публичного ключа, но не доказывает принадлежность недоверенного ключа заявленной организации.

Источники: Спецификация A2A 1.0 и Спецификация A2A 0.3.

Запускаемый локальный пример

В репозитории Powerduck React есть examples/a2a-demo. С Node.js 22+ выполните в этой папке npm ci и npm start. Импортируйте её openapi.json, чтобы отлаживать JSON-RPC, REST и настольный gRPC на одном локальном калькуляторе. README содержит демонстрационный bearer-токен, инструкции по обнаружению Agent Card, доверенному локальному JWKS и потоковой передаче. npm test проверяет реальные транспорты и отклонение подделанных подписей без внешних сервисов.

В панели протокола Создать тело запроса показывает шаблон выбранного метода. Заменить тело запроса явно применяет его; отмена или смена метода сохраняет существующий черновик.

cd powerduck-react/examples/a2a-demo
npm ci
npm start
# In another terminal, in the same directory:
npm test

Локальные эндпоинты: JSON-RPC http://127.0.0.1:9999/rpc, REST http://127.0.0.1:9999/rest, gRPC http://127.0.0.1:9998. Публичная карточка: http://127.0.0.1:9999/.well-known/agent-card.json. Используйте демонстрационный bearer-токен powerduck-local-demo-token-0123456789. Числа [12,30] возвращают Sum: 42 и структурированное значение total: 42. Доверенный публичный ключ хранится в .runtime/trusted-jwks.json и меняется при перезапуске. Демонстрация слушает только локальные адреса, не требует ключа ИИ, не содержит постоянного движка задач или push-доставки и не должна публиковаться с демонстрационным токеном. Разрешённые источники браузера по умолчанию — http://localhost:3000 и http://127.0.0.1:3000; для других используйте CORS_ORIGINS. Сгенерированный сервер также поддерживает этот явный список разрешённых источников.

Создание и отладка​

Agent Card​

Задачи и потоковая передача​

Расширение OpenAPI​

REST и gRPC​

Генерация сервера​

Совместимость подписей​

Запускаемый локальный пример​