Методы протокола

Операции описаны независимо от привязки. Имена и адреса для JSON-RPC, gRPC и HTTP+JSON определены в разделах 9–11 оригинала. Ниже — таблица операций и пересказ раздела 3 спецификации.

Таблица операций#

Во всех запросах есть необязательное поле tenant — непрозрачный идентификатор маршрутизации. Если он указан, он должен совпадать со значением tenant выбранного интерфейса AgentInterface из Agent Card.

Отправка сообщений#

SendMessage#

Основная операция начала взаимодействия. Клиент отправляет сообщение и получает либо Task, который отслеживает обработку, либо Message — прямой ответ для простых случаев, когда отслеживание задачи не нужно.

Ошибки:

• ContentTypeNotSupportedError: тип содержимого в частях сообщения не поддерживается агентом.
• UnsupportedOperationError: сообщения в задачи с конечным состоянием (TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED) не принимаются.
• TaskNotFoundError: идентификатор задачи не существует или недоступен.

Поведение. Агент МОЖЕТ создать новую задачу и обработать сообщение асинхронно или МОЖЕТ вернуть прямое сообщение-ответ для простого взаимодействия.

SendMessageRequest

SendMessageConfiguration

Режимы выполнения

Поле returnImmediately управляет тем, вернётся ли операция сразу или дождётся результата. По умолчанию операции блокирующие.

• Блокирующий режим (returnImmediately: false или не указано). Операция ДОЛЖНА дождаться, пока задача достигнет конечного (TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_CANCELED, TASK_STATE_REJECTED) или прерванного (TASK_STATE_INPUT_REQUIRED, TASK_STATE_AUTH_REQUIRED) состояния. Ответ ДОЛЖЕН содержать последнее состояние задачи со всеми артефактами и статусом.
• Неблокирующий режим (returnImmediately: true). Операция ДОЛЖНА вернуться сразу после создания задачи, даже если обработка идёт. У возвращённой задачи будет состояние «в процессе», например TASK_STATE_WORKING. Узнавать об обновлениях клиент должен сам: опросом через GetTask, подпиской через SubscribeToTask или push-уведомлениями.

SendStreamingMessage#

То же, что SendMessage, но с потоковой передачей обновлений во время обработки.

Результат. Объект StreamResponse: сначала Task или Message, затем (после Task) может идти поток событий TaskStatusUpdateEvent и TaskArtifactUpdateEvent, затем признак завершения.

Ошибки:

• UnsupportedOperationError: агент не поддерживает потоковую передачу (см. проверку возможностей) или задача находится в конечном состоянии.
• ContentTypeNotSupportedError: тип содержимого в частях сообщения не поддерживается.
• TaskNotFoundError: идентификатор задачи не существует или недоступен.

Поведение. Операция ДОЛЖНА открыть потоковое соединение для обновлений в реальном времени. Поток ДОЛЖЕН следовать одному из двух сценариев:

1. Только сообщение. Если агент возвращает Message, поток ДОЛЖЕН содержать ровно один объект Message и сразу закрыться. Отслеживания задачи и обновлений нет.
2. Жизненный цикл задачи. Если агент возвращает Task, поток ДОЛЖЕН начинаться с объекта Task, затем идут ноль или больше событий TaskStatusUpdateEvent или TaskArtifactUpdateEvent. Поток ДОЛЖЕН закрыться, когда задача достигнет конечного состояния.

Работа с задачами#

GetTask#

Возвращает текущее состояние ранее созданной задачи: статус, артефакты и (по желанию) историю. Обычно используется для опроса задачи, начатой через SendMessage, либо чтобы получить итоговое состояние после push-уведомления или окончания потока.

Результат: Task с текущим состоянием и артефактами. Ошибка: TaskNotFoundError.

Семантика historyLength

Параметр historyLength встречается в нескольких операциях и везде работает одинаково:

• не указан: ограничений нет, сервер возвращает столько истории, сколько решит (может быть вся);
• 0: историю возвращать не нужно, поле history СЛЕДУЕТ опустить;
• больше 0: вернуть не больше этого числа последних сообщений.

ListTasks#

Возвращает список задач с необязательной фильтрацией и постраничной выдачей. Позволяет находить задачи в разных контекстах и с нужным статусом.

Параметры:

Результат:

Поведение.

• Операция ДОЛЖНА возвращать только задачи, видимые аутентифицированному клиенту. Реализации ДОЛЖНЫ ограничивать доступ по авторизации (см. раздел 13.1 оригинала).
• Выдача ДОЛЖНА быть курсорной, а задачи — отсортированы по времени статуса от новых к старым.
• Поле nextPageToken ДОЛЖНО присутствовать всегда. На последней странице оно ДОЛЖНО быть пустой строкой "": по ней клиент понимает, что страниц больше нет.
• Если includeArtifacts равен false, поле artifacts ДОЛЖНО быть опущено в каждой задаче полностью, без пустого массива и null.

Курсорная выдача выбрана вместо смещения (offset) ради производительности и согласованности на больших наборах: она не страдает от проблемы глубокой пагинации и согласуется с gRPC, где тоже используются page_token и next_page_token.

CancelTask#

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

Результат: обновлённая Task со статусом отмены.

Ошибки:

• TaskNotCancelableError: задача не в том состоянии, когда её можно отменить (уже завершена, провалена или отменена);
• TaskNotFoundError: идентификатор задачи не существует или недоступен.

Операция идемпотентна: повторные запросы на отмену имеют тот же эффект. Повторный запрос МОЖЕТ вернуть TaskNotFoundError, если задача уже отменена и удалена.

SubscribeToTask#

Открывает потоковое соединение для получения обновлений существующей задачи. Подходит для любой задачи, которая не в конечном состоянии.

Результат: StreamResponse: первым событием идёт Task с текущим состоянием, затем поток событий TaskStatusUpdateEvent и TaskArtifactUpdateEvent.

Ошибки: UnsupportedOperationError (потоковая передача не поддерживается или задача уже в конечном состоянии); TaskNotFoundError.

Поведение. Первым событием в потоке ДОЛЖЕН быть объект Task с состоянием на момент подписки. Это защищает от потери информации между вызовами GetTask и SubscribeToTask. Поток ДОЛЖЕН завершиться, когда задача достигнет конечного состояния.

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

Четыре операции управляют настройкой, по которой агент отправляет обновления задачи на вебхук клиента. Они доступны, только если агент объявил capabilities.pushNotifications: true.

Поля настройки TaskPushNotificationConfig:

Для операций Get и Delete в запросе нужны taskId (родительская задача) и id (настройка). Подробнее о доставке: «Обновления задач».

Получение расширенной Agent Card#

GetExtendedAgentCard#

Возвращает более подробную версию Agent Card после аутентификации клиента. Доступна, только если AgentCard.capabilities.extendedAgentCard равно true.

Результат: полный объект AgentCard, который может содержать дополнительные сведения или навыки, которых нет в публичной карточке.

Ошибки:

• UnsupportedOperationError: агент не поддерживает расширенные карточки;
• ExtendedAgentCardNotConfiguredError: возможность объявлена, но расширенная карточка не настроена.

Правила аутентификации, замены кэша и безопасности описаны на странице «Agent Card».

Общая семантика операций#

Идемпотентность#

• Операции чтения (GetTask, ListTasks, GetExtendedAgentCard) идемпотентны по природе.
• SendMessage МОЖЕТ быть идемпотентной. Агенты могут использовать messageId, чтобы обнаруживать дубли.
• CancelTask идемпотентна: повторные запросы на отмену имеют тот же эффект.

Асинхронная обработка#

Операции A2A рассчитаны на асинхронное выполнение задач. Они возвращают Task или Message, а если вернулась задача, обработка продолжается в фоне. Обновления клиент получает опросом, потоком или push-уведомлениями. Агенты МОГУТ принимать дополнительные сообщения для задач в неконечных состояниях, что позволяет вести многоходовые взаимодействия: см. «Задача».

Ошибки#

Описание категорий и ошибок A2A: «Ошибки».