Обновления задач

В A2A есть три взаимодополняющих способа узнать о ходе задачи и её завершении: опрос, потоковая передача и push-уведомления.

Сравнение способов#

Способ	Как работает	Плюсы и минусы	Когда подходит	Требует
Опрос	Клиент периодически вызывает `GetTask` и проверяет статус.	Просто реализовать, работает во всех привязках. Выше задержка, возможны лишние запросы.	Простые интеграции, редкие обновления, клиенты за строгими межсетевыми экранами.	Ничего
Потоковая передача	События приходят по мере появления. Операции: `SendStreamingMessage` и `SubscribeToTask`.	Низкая задержка, эффективна при частых обновлениях. Нужна поддержка постоянного соединения.	Интерактивные приложения, панели в реальном времени, наблюдение за прогрессом.	`AgentCard.capabilities.streaming` равно `true`
Push-уведомления (вебхуки)	Агент отправляет HTTP POST на адрес, который зарегистрировал клиент, когда состояние задачи меняется.	Клиенту не нужно держать соединение. Доставка асинхронная, клиент должен быть доступен по HTTP.	Интеграции сервер–сервер, долгие задачи, событийные архитектуры.	`AgentCard.capabilities.pushNotifications` равно `true`

Опрос#

Клиент периодически вызывает GetTask, чтобы проверить состояние задачи. Это самый простой способ, он работает со всеми привязками. Цена — задержка и лишние запросы.

Потоковая передача#

Операции SendStreamingMessage и SubscribeToTask открывают поток событий. Если агент не объявил потоковую передачу, он вернёт UnsupportedOperationError.

Порядок событий#

Все реализации ДОЛЖНЫ доставлять события в том порядке, в котором они созданы. Переупорядочивать события при передаче НЕЛЬЗЯ ни в одной привязке.

Несколько потоков на одну задачу#

Агент МОЖЕТ обслуживать несколько одновременных потоков одной задачи, для одного клиента или для нескольких. Если потоков несколько:

события ДОЛЖНЫ рассылаться во все активные потоки этой задачи;
каждый поток ДОЛЖЕН получать одни и те же события в одном и том же порядке;
закрытие одного потока НЕ ДОЛЖНО влиять на остальные;
жизненный цикл задачи не зависит от жизненного цикла отдельного потока.

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

Формат StreamResponse#

Обёртка для разных видов данных в потоковых операциях. Объект ДОЛЖЕН содержать ровно одно из полей.

Поле	Тип	Описание
`task`	`Task`	Объект задачи с текущим состоянием.
`message`	`Message`	Сообщение от агента.
`statusUpdate`	`TaskStatusUpdateEvent`	Событие обновления статуса задачи.
`artifactUpdate`	`TaskArtifactUpdateEvent`	Событие обновления артефакта задачи.

События#

TaskStatusUpdateEvent сообщает клиенту об изменении статуса задачи.

Поле	Тип	Обязательное	Описание
`taskId`	`string`	Да	Идентификатор изменившейся задачи.
`contextId`	`string`	Да	Идентификатор контекста, которому принадлежит задача.
`status`	`TaskStatus`	Да	Новый статус задачи.
`metadata`	`object`	Нет	Метаданные обновления.

TaskArtifactUpdateEvent сообщает о создании или обновлении артефакта. Поля описаны на странице «Артефакт».

Push-уведомления#

Push-уведомления доставляются HTTP POST на вебхук, зарегистрированный клиентом. Настройка выполняется операциями из группы push-уведомлений.

Когда задача обновляется, агент отправляет HTTP POST на настроенный адрес. Содержимое запроса — тот же формат StreamResponse, что и в потоковых операциях, поэтому push-уведомления несут те же виды событий, что и потоки.

http

POST {webhook_url}
Authorization: {authentication_scheme} {credentials}
Content-Type: application/a2a+json

Независимо от привязки, которую использует агент, вебхуки работают по обычному HTTP с JSON-представлением из HTTP-привязки.

Данные аутентификации#

Объект AuthenticationInfo описывает, как агенту аутентифицироваться на вебхуке клиента.

Поле	Тип	Обязательное	Описание
`scheme`	`string`	Да	Схема HTTP-аутентификации из реестра IANA, например `Bearer`, `Basic`, `Digest`. Названия схем не зависят от регистра (RFC 9110, раздел 11.1).
`credentials`	`string`	Нет	Учётные данные для push-уведомлений. Формат зависит от схемы, например токен для `Bearer`.