Спецификация A2A 1.0

Паспорт протокола#

Три уровня спецификации#

Спецификация разделена на три уровня, и это главное, что нужно понять перед чтением:

1. Модель данных. Задача, сообщение, часть, артефакт, карточка агента и другие объекты. Описаны один раз, независимо от способа передачи.
2. Абстрактные операции. Что можно сделать: отправить сообщение, получить задачу, отменить, подписаться на обновления.
3. Привязки протокола. Как операции выглядят на проводе в JSON-RPC, gRPC и HTTP+JSON. Все три привязки обязаны быть функционально равнозначными — см. привязка протокола.

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

Операции#

Пример запроса в привязке JSON-RPC. Клиент передаёт версию протокола в заголовке A2A-Version: 1.0.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "9b6f3a2e-5c1d-4e8a-9f0b-7d2c1a4e6b35",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "Подбери стеллаж для склада высотой 2 м, бюджет до 30 000 ₽"
        }
      ]
    },
    "configuration": {
      "acceptedOutputModes": [
        "application/json"
      ],
      "returnImmediately": false
    }
  }
}

По умолчанию операция ждёт, пока задача дойдёт до конечного или прерванного состояния. С returnImmediately: true сервер сразу возвращает задачу в работе, а обновления клиент получает опросом, потоком или push-уведомлениями.

Жизненный цикл задачи#

• Рабочие: TASK_STATE_SUBMITTED — задача принята, TASK_STATE_WORKING — выполняется.
• Прерванные: TASK_STATE_INPUT_REQUIRED — агенту нужны данные от клиента, TASK_STATE_AUTH_REQUIRED — нужна аутентификация.
• Конечные: TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED. После них задача сообщений не принимает.

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

Доставка обновлений#

Клиент узнаёт о ходе задачи одним из трёх способов:

• Опрос через GetTask. Прост, работает везде, но с задержкой.
• Потоковая передача через SendStreamingMessage или SubscribeToTask. Требует capabilities.streaming. События приходят строго по порядку, к одной задаче можно подключить несколько потоков.
• Push-уведомления на вебхук клиента. Требуют capabilities.pushNotifications. Подходят для задач, которые идут часами.

Ошибки#

Спецификация требует не различать «не существует» и «нет доступа»: агент не должен раскрывать существование чужих задач.

Что изменилось в 1.0#

Версия 1.0 несовместима с 0.3 на уровне формата. Если вы читаете статью или код, где встречаются message/send, kind: "text" или TextPart, — это материал о прошлой версии.

• Операции переименованы: message/send → SendMessage, tasks/get → GetTask, tasks/resubscribe → SubscribeToTask и так далее.
• Три типа частей (TextPart, FilePart, DataPart) объединены в одну часть: тип определяется тем, какое поле заполнено — text, raw, url или data. Поле kind удалено, mimeType заменено на mediaType.
• Значения перечислений записываются как TASK_STATE_COMPLETED и ROLE_USER вместо completed и user.
• Адреса подключения собраны в supportedInterfaces, версия протокола указывается для каждого интерфейса отдельно.
• Появились ListTasks с постраничным выводом по курсору, поле tenant для обслуживания нескольких агентов по одному адресу и параметр returnImmediately.
• Ошибки передаются в формате google.rpc.Status.
• В OAuth 2.0 удалены устаревшие потоки implicit и password, добавлены device code и признак обязательного PKCE.
• Версия согласуется заголовком A2A-Version; пустое значение сервер трактует как 0.3. Официальные SDK поддерживают слой совместимости для поэтапного перехода.