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

Одиннадцать операций A2A и их поведение

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/protocol/methods/). Тип: Перевод и пересказ. Основа: Спецификация, разделы 3.1–3.3; краткая справка (https://a2a-protocol.org/latest/specification/#31-core-operations). Версия спецификации 1.0.0, сверено 05.10.2026.

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

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

| Операция | Запрос | Ответ | Что делает |
| --- | --- | --- | --- |
| [`SendMessage`](#sendmessage) | `SendMessageRequest` | `SendMessageResponse` | Начинает или продолжает задачу. |
| [`SendStreamingMessage`](#sendstreamingmessage) | `SendMessageRequest` | поток `StreamResponse` | Отправляет сообщение и получает обновления в реальном времени. |
| [`GetTask`](#gettask) | `GetTaskRequest` | `Task` | Возвращает текущее состояние задачи. |
| [`ListTasks`](#listtasks) | `ListTasksRequest` | `ListTasksResponse` | Список задач с фильтрами и постраничной выдачей. |
| [`CancelTask`](#canceltask) | `CancelTaskRequest` | `Task` | Запрашивает отмену задачи. |
| [`SubscribeToTask`](#subscribetotask) | `SubscribeToTaskRequest` | поток `StreamResponse` | Подписывает на обновления существующей задачи. |
| [`GetExtendedAgentCard`](#getextendedagentcard) | `GetExtendedAgentCardRequest` | `AgentCard` | Возвращает расширенные метаданные агента после аутентификации. |
| [`CreateTaskPushNotificationConfig`](#push-uvedomleniya) | `TaskPushNotificationConfig` | `TaskPushNotificationConfig` | Регистрирует настройку push-уведомлений (вебхук) для задачи. |
| [`GetTaskPushNotificationConfig`](#push-uvedomleniya) | `GetTaskPushNotificationConfigRequest` | `TaskPushNotificationConfig` | Возвращает настройку push-уведомлений задачи. |
| [`ListTaskPushNotificationConfigs`](#push-uvedomleniya) | `ListTaskPushNotificationConfigsRequest` | `ListTaskPushNotificationConfigsResponse` | Список настроек push-уведомлений задачи. |
| [`DeleteTaskPushNotificationConfig`](#push-uvedomleniya) | `DeleteTaskPushNotificationConfigRequest` | `Empty` | Удаляет настройку push-уведомлений задачи. |

> **Заметка переводчика.** В версии 0.3 операции назывались иначе (`message/send`, `tasks/get` и т. д.). Таблица соответствия — на странице [«Миграция»](https://a2adocs.ru/migration/#pereimenovanie-operatsiy).

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

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

### SendMessage

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

**Ошибки:**

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

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

#### SendMessageRequest

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `message` | `Message` | Да | Сообщение, которое отправляется агенту. |
| `configuration` | `SendMessageConfiguration` | Нет | Настройки запроса. |
| `metadata` | `object` | Нет | Произвольные пары «ключ — значение» с дополнительным контекстом или параметрами. |

#### SendMessageConfiguration

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `acceptedOutputModes` | массив `string` | Нет | Типы содержимого (media types), которые клиент готов принять в частях ответа. Агентам СЛЕДУЕТ учитывать это при формировании вывода. |
| `taskPushNotificationConfig` | `TaskPushNotificationConfig` | Нет | Настройка push-уведомлений об обновлениях задачи. В запросе `SendMessage` идентификатор задачи в ней должен быть пустым. |
| `historyLength` | `integer` | Нет | Максимальное число последних сообщений истории в ответе. См. [семантику historyLength](#semantika-historylength). |
| `returnImmediately` | `boolean` | Нет | Если `true`, операция возвращает управление сразу после создания задачи, даже если обработка не закончена. Если `false` (по умолчанию), операция ДОЛЖНА дождаться конечного или прерванного состояния. |

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

Поле `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-уведомлениями.

Поле `returnImmediately` не действует: если операция вернула прямое `Message`, в потоковых операциях (они всегда присылают обновления в реальном времени) и на настроенные push-уведомления (они работают независимо от режима).

> **Заметка переводчика.** В описании `SendMessage` (3.1.1) сказано, что операция возвращается немедленно, а в разделе 3.2.2 по умолчанию она блокирующая. Формулировки расходятся; уточните по a2a.proto и по документации вашего SDK.

### SendStreamingMessage

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

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

**Ошибки:**

- `UnsupportedOperationError`: агент не поддерживает потоковую передачу (см. [проверку возможностей](https://a2adocs.ru/concepts/agent-card/#proverka-vozmozhnostey)) или задача находится в конечном состоянии.
- `ContentTypeNotSupportedError`: тип содержимого в частях сообщения не поддерживается.
- `TaskNotFoundError`: идентификатор задачи не существует или недоступен.

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

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

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

### GetTask

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

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `id` | `string` | Да | Идентификатор задачи. |
| `historyLength` | `integer` | Нет | Максимальное число последних сообщений истории. Не указано — клиент не ограничивает. `0` — не включать сообщения. Сервер НЕ ДОЛЖЕН вернуть больше, но МОЖЕТ применить меньший лимит. |

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

#### Семантика historyLength

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

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

### ListTasks

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

**Параметры:**

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `contextId` | `string` | Нет | Задачи только из этого контекста (разговора или сеанса). |
| `status` | `TaskState` | Нет | Задачи с этим состоянием. |
| `pageSize` | `integer` | Нет | Максимум задач в ответе. Сервер может вернуть меньше. По умолчанию не больше 50; минимум 1, максимум 100. |
| `pageToken` | `string` | Нет | Токен страницы из предыдущего вызова `ListTasks` (поле `nextPageToken`). |
| `historyLength` | `integer` | Нет | Максимум сообщений истории в каждой задаче. |
| `statusTimestampAfter` | `timestamp` | Нет | Только задачи, статус которых обновлён не раньше этого момента (ISO 8601, например `2023-10-27T10:00:00Z`). |
| `includeArtifacts` | `boolean` | Нет | Включать ли артефакты. По умолчанию `false`, чтобы уменьшить размер ответа. |

**Результат:**

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tasks` | массив `Task` | Да | Задачи, подходящие под условия. |
| `nextPageToken` | `string` | Да | Токен следующей страницы или пустая строка, если результатов больше нет. |
| `pageSize` | `integer` | Да | Размер страницы в этом ответе. |
| `totalSize` | `integer` | Да | Общее число доступных задач до постраничной разбивки. |

**Поведение.**

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

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

### CancelTask

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

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `id` | `string` | Да | Идентификатор отменяемой задачи. |
| `metadata` | `object` | Нет | Дополнительный контекст или параметры. |

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

**Ошибки:**

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

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

### SubscribeToTask

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

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `id` | `string` | Да | Идентификатор задачи, на которую оформляется подписка. |

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

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

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

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

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

| Операция | Что делает | Ошибки |
| --- | --- | --- |
| `CreateTaskPushNotificationConfig` | Создаёт настройку для задачи. Агент ДОЛЖЕН настроить вебхук, и при обновлениях задачи отправлять на него HTTP POST с данными `StreamResponse`. Настройка ДОЛЖНА храниться до завершения задачи или явного удаления. | `PushNotificationNotSupportedError`, `TaskNotFoundError` |
| `GetTaskPushNotificationConfig` | Возвращает настройку: адрес вебхука и параметры. ДОЛЖНА завершиться ошибкой, если настройки нет или у клиента нет доступа. | `PushNotificationNotSupportedError`, `TaskNotFoundError` |
| `ListTaskPushNotificationConfigs` | Возвращает все активные настройки задачи. МОЖЕТ поддерживать постраничную выдачу (`pageSize`, `pageToken`; в ответе `configs`, `nextPageToken`). | `PushNotificationNotSupportedError`, `TaskNotFoundError` |
| `DeleteTaskPushNotificationConfig` | Окончательно удаляет настройку. После этого уведомления на вебхук не отправляются. Операция ДОЛЖНА быть идемпотентной. | `PushNotificationNotSupportedError`, `TaskNotFoundError` |

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

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `tenant` | `string` | Нет | Идентификатор маршрутизации. |
| `id` | `string` | Нет | Уникальный идентификатор настройки (например, UUID). |
| `taskId` | `string` | Нет | Идентификатор задачи, к которой относится настройка. |
| `url` | `string` | Да | Адрес, на который отправляются уведомления. |
| `token` | `string` | Нет | Токен, уникальный для задачи или сеанса. |
| `authentication` | `AuthenticationInfo` | Нет | Данные аутентификации для отправки уведомления. |

Для операций `Get` и `Delete` в запросе нужны `taskId` (родительская задача) и `id` (настройка). Подробнее о доставке: [«Обновления задач»](https://a2adocs.ru/protocol/updates/#push-uvedomleniya).

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

### GetExtendedAgentCard

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

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

**Ошибки:**

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

Правила аутентификации, замены кэша и безопасности описаны на странице [«Agent Card»](https://a2adocs.ru/concepts/agent-card/#rasshirennaya-agent-card).

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

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

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

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

Операции A2A рассчитаны на асинхронное выполнение задач. Они возвращают `Task` или `Message`, а если вернулась задача, обработка продолжается в фоне. Обновления клиент получает опросом, потоком или push-уведомлениями. Агенты МОГУТ принимать дополнительные сообщения для задач в неконечных состояниях, что позволяет вести многоходовые взаимодействия: см. [«Задача»](https://a2adocs.ru/concepts/task/#mnogohodovye-vzaimodeystviya).

### Ошибки

Описание категорий и ошибок A2A: [«Ошибки»](https://a2adocs.ru/protocol/errors/).