# A2A Docs — все страницы одним файлом


---

# Протокол Agent-to-Agent (A2A)

Документация на русском: перевод и разборы

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/).

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

> **Заметка переводчика.** Подчёркнутые слова можно навести мышью или выбрать с клавиатуры: появится короткое определение. Полный словарь терминов ведётся на [a2aprotocol.ru](https://a2aprotocol.ru).

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

> **Заметка переводчика.** Если вы знакомы с MCP: он описывает, как агент пользуется инструментами, а A2A — как агенты общаются между собой. Подробнее на странице [«Введение»](https://a2adocs.ru/intro/).

## Маршрут чтения

Страницы идут от общего к частному. Если вы подключаетесь к агенту на версии 0.3, начните с четвёртой.

1. [Введение](https://a2adocs.ru/intro/)
2. [Понятия](https://a2adocs.ru/concepts/)
3. [Протокол](https://a2adocs.ru/protocol/)
4. [Миграция с 0.3 на 1.0](https://a2adocs.ru/migration/)
5. [Безопасность](https://a2adocs.ru/security/) (в разработке)
6. [Руководства](https://a2adocs.ru/guides/) (в разработке)
7. [Справочник](https://a2adocs.ru/reference/)
8. [Инструменты](https://a2adocs.ru/tools/) (в разработке)
9. [О проекте](https://a2adocs.ru/about/)

> **Заметка переводчика.** Отметка «готово» значит, что страница написана и сверена с оригиналом на дату в шапке сайта. Разделы «в разработке» появятся позже, а пока читайте соответствующие разделы оригинала.

## Какую версию читать

Сайт описывает версию 1.0.0. Но в реальных проектах вы ещё долго будете встречать предыдущую.

| Версия | Статус | Что важно знать |
| --- | --- | --- |
| 1.0.0 | Последняя выпущенная версия, основа этого сайта | В протоколе взаимодействия есть ломающие изменения относительно 0.3. Агент может объявлять поддержку и 0.3, и 1.0 одновременно. |
| 0.3.0 | Предыдущая версия | Часть SDK и фреймворков пока реализует именно её. Если подключаетесь к такому агенту, откройте страницу [«Миграция»](https://a2adocs.ru/migration/). |
| 0.2.6, 0.1.0 | Исторические версии | Сохранены в официальной документации, для новых проектов не подходят. |

## О переводе

Это неофициальный перевод. Оригинал и права на него принадлежат авторам проекта A2A. Если перевод и оригинал расходятся, верен оригинал. Подробнее о том, как мы переводим и как отмечены страницы, на странице [«О проекте»](https://a2adocs.ru/about/).

> **Заметка переводчика.** Дата последней сверки с оригиналом указана в шапке каждой страницы. Имена полей, методов и ошибок остаются как в оригинале.


---

# Введение

Зачем нужен A2A и как устроена спецификация

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

Протокол Agent2Agent (A2A) — открытый стандарт, созданный для того, чтобы независимые и потенциально «непрозрачные» системы ИИ-агентов могли общаться и работать вместе. Агенты могут быть построены на разных фреймворках и языках или разными поставщиками. A2A даёт им общий язык и общую модель взаимодействия.

> **Заметка переводчика.** Слово opaque переводим как «непрозрачный»: для партнёра агент остаётся чёрным ящиком. Это сознательное свойство протокола, а не недостаток.

## Что позволяет протокол

Агенты, поддерживающие A2A, могут:

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

## Цели

- **Совместимость (Interoperability).** Преодолеть разрыв в общении между разнородными агентными системами.
- **Сотрудничество (Collaboration).** Дать агентам возможность передавать друг другу задачи, обмениваться контекстом и вместе решать сложные запросы пользователей.
- **Обнаружение (Discovery).** Позволить агентам динамически находить и понимать возможности других агентов.
- **Гибкость (Flexibility).** Поддержать разные режимы взаимодействия: синхронный запрос и ответ, потоковую передачу обновлений в реальном времени и асинхронные push-уведомления для долгих задач.
- **Безопасность (Security).** Обеспечить защищённый обмен, пригодный для корпоративных сред и опирающийся на стандартные веб-практики.
- **Асинхронность (Asynchronicity).** Изначально поддерживать долгие задачи и взаимодействия, в которых участвует человек.

## Принципы

- **Простота.** Повторно используются существующие понятные стандарты: HTTP, JSON-RPC 2.0, Server-Sent Events.
- **Готовность для предприятий.** Аутентификация, авторизация, безопасность, приватность, трассировка и мониторинг решаются в рамках устоявшихся корпоративных практик.
- **Асинхронность прежде всего.** Протокол рассчитан на (возможно, очень) долгие задачи и взаимодействие с человеком в контуре.
- **Независимость от формата.** Поддерживается обмен разными типами содержимого: текст, аудио и видео (через ссылки на файлы), структурированные данные и формы, а также потенциально встраиваемые интерфейсы (например, iframe, на который ссылаются из частей).
- **Непрозрачное выполнение.** Агенты сотрудничают на основе заявленных возможностей и обмена информацией, не раскрывая друг другу внутренние рассуждения, планы и устройство своих инструментов.

## Три слоя спецификации

Спецификация разделена на три слоя, которые вместе дают полное определение протокола.



- **Слой 1. Каноническая модель данных.** Основные структуры данных и форматы сообщений, которые должны понимать все реализации. Они не зависят от протокола и описаны как сообщения Protocol Buffers.
- **Слой 2. Абстрактные операции.** Базовые возможности и поведение, которые обязаны поддерживать агенты A2A независимо от того, как эти операции опубликованы.
- **Слой 3. Привязки к протоколам.** Конкретное отображение операций и структур данных на JSON-RPC, gRPC и HTTP/REST: имена методов, шаблоны адресов, особенности каждого протокола.

Такое устройство даёт четыре свойства:

- базовая семантика одинакова во всех привязках;
- новые привязки можно добавлять, не меняя модель данных;
- об операциях A2A можно рассуждать независимо от привязки;
- совместимость поддерживается общим пониманием канонической модели.

> **Заметка переводчика.** Единственным нормативным определением объектов и сообщений служит файл a2a.proto. JSON Schema создаётся из него при сборке и нормативным не является. SDK и схемы должны генерироваться из proto, а не правиться вручную (раздел 1.4).

## A2A и MCP

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

Подробное сравнение, таблица различий и типичные заблуждения — на странице [«A2A и MCP» справочника a2aprotocol.ru](https://a2aprotocol.ru/a2a-vs-mcp/). Оригинал: [A2A and MCP](https://a2a-protocol.org/latest/topics/a2a-and-mcp/).

## Что читать дальше

- [Понятия](https://a2adocs.ru/concepts/): клиент, сервер, Agent Card, задача, сообщение, часть, артефакт.
- [Протокол](https://a2adocs.ru/protocol/): привязки, версии и параметры сервиса.
- [Методы](https://a2adocs.ru/protocol/methods/): таблица операций с описанием каждой.
- [Миграция с 0.3 на 1.0](https://a2adocs.ru/migration/): если вы работаете с агентами прошлой версии.


---

# Понятия

Основные объекты и роли протокола

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

A2A строится вокруг нескольких ключевых понятий. Ниже они перечислены так, как определены в разделе 2.2 спецификации; отдельные страницы разбирают главные объекты подробно. Краткие определения и рекомендации по переводу терминов — в [глоссарии a2aprotocol.ru](https://a2aprotocol.ru/glossary/).

## Словарь понятий

| Понятие | Что это |
| --- | --- |
| A2A-клиент (A2A Client) | Приложение или агент, который обращается к A2A-серверу от имени пользователя или другой системы. |
| A2A-сервер, удалённый агент (A2A Server) | Агент или система агентов, которая открывает совместимую с A2A точку входа, обрабатывает задачи и отдаёт ответы. |
| [Agent Card](https://a2adocs.ru/concepts/agent-card/) | JSON-документ, который публикует A2A-сервер. Описывает его идентичность, возможности, навыки, адрес сервиса и требования к аутентификации. |
| [Сообщение (Message)](https://a2adocs.ru/concepts/message-and-part/) | Реплика в обмене между клиентом и удалённым агентом. Имеет роль (`user` или `agent`) и содержит одну или несколько частей. |
| [Задача (Task)](https://a2adocs.ru/concepts/task/) | Основная единица работы в A2A с уникальным идентификатором. Задачи хранят состояние и проходят заданный жизненный цикл. |
| [Часть (Part)](https://a2adocs.ru/concepts/message-and-part/#part) | Наименьшая единица содержимого сообщения или артефакта. Может содержать текст, ссылки на файлы или структурированные данные. |
| [Артефакт (Artifact)](https://a2adocs.ru/concepts/artifact/) | Результат, созданный агентом при выполнении задачи: документ, изображение, структурированные данные. Состоит из частей. |
| Потоковая передача (Streaming) | Обновления задачи в реальном времени: изменения статуса и фрагменты артефактов, которые приходят механизмом конкретной привязки. |
| Push-уведомления | Асинхронные обновления задачи: сервер сам отправляет HTTP POST на адрес вебхука, указанный клиентом. Для долгих задач и отключённых клиентов. |
| Контекст (Context) | Необязательный идентификатор, который логически объединяет связанные задачи и сообщения. |
| Расширение (Extension) | Механизм, позволяющий агентам предоставлять дополнительные функции или данные сверх базовой спецификации. |

> **Заметка переводчика.** В оригинале роли сообщения записаны как `user` и `agent`. В версии 1.0 в самом протоколе они передаются значениями `ROLE_USER` и `ROLE_AGENT`.

## Как это работает вместе

Типичный обмен состоит из четырёх шагов.

1. **Знакомство.** Клиент читает Agent Card удалённого агента: кто это, что он умеет, как подключиться и как аутентифицироваться.
2. **Запрос.** Клиент отправляет сообщение. Оно состоит из частей: текста, файлов или структурированных данных.
3. **Работа.** Если работа не мгновенная, агент оформляет задачу со статусом. За ходом можно следить опросом, потоком событий или получать push-уведомления.
4. **Результат.** Итог работы приходит как артефакт, а задача переходит в конечное состояние.

Агент может ответить и сразу сообщением, без создания задачи: так устроены простые взаимодействия.

## Три способа получать обновления

Для долгих задач в A2A есть три взаимодополняющих механизма: опрос (запрос состояния задачи), потоковая передача и push-уведомления. Их сравнение и требования к Agent Card описаны на странице [«Обновления задач»](https://a2adocs.ru/protocol/updates/).

## Что читать дальше

- [Agent Card](https://a2adocs.ru/concepts/agent-card/): как агент рассказывает о себе.
- [Задача](https://a2adocs.ru/concepts/task/): поля, состояния, идентификаторы.
- [Сообщение и часть](https://a2adocs.ru/concepts/message-and-part/): из чего состоит обмен.
- [Артефакт](https://a2adocs.ru/concepts/artifact/): как приходит результат.


---

# Agent Card

Как агент рассказывает о себе

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/concepts/agent-card/). Тип: Перевод и пересказ. Основа: Спецификация, разделы 3.1.11 и 3.3.4; What's New; краткая справка (https://a2a-protocol.org/latest/specification/#3111-get-extended-agent-card). Версия спецификации 1.0.0, сверено 05.10.2026.

Agent Card — JSON-документ, который публикует A2A-сервер. В нём описаны идентичность агента, его возможности, навыки, адрес сервиса и требования к аутентификации. Клиент читает Agent Card, прежде чем обращаться к агенту.

## Где лежит

Стандартное расположение — путь `/.well-known/agent-card.json` (well-known URI по RFC 8615). Другие механизмы обнаружения описаны в разделе 8.2 оригинала.

> **Заметка переводчика.** В версии 0.3 карточка тоже публиковалась по пути `/.well-known/agent-card.json`. Изменилась структура содержимого, а не адрес: см. [«Миграцию»](https://a2adocs.ru/migration/#agent-card).

## Из чего состоит

Карточка разобрана на семь групп полей. Наведите на деталь или перемещайтесь стрелками: справа от каждой стоит её назначение, внизу прочитайте подробности.



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

В JSON имена полей записываются в стиле camelCase. Таблица составлена по краткой справке и странице «What's New» оригинальной документации; полный перечень полей смотрите в разделе 4.4.1 оригинала.

| Поле | Что описывает |
| --- | --- |
| `name`, `description`, `version` | Имя, описание и версия агента. |
| `supportedInterfaces` | Список интерфейсов, через которые можно обратиться к агенту. У каждого есть `url`, `protocolBinding` (например, `JSONRPC`), `protocolVersion` (например, `1.0`) и необязательный `tenant`. |
| `capabilities` | Необязательные возможности: `streaming`, `pushNotifications`, `extendedAgentCard`, `extensions`. |
| `skills` | Список навыков агента. У каждого есть идентификатор, название, описание, теги и примеры. |
| `securitySchemes` и требования безопасности | Способы аутентификации: API-ключ, HTTP-аутентификация, OAuth 2.0, OpenID Connect, mTLS. |
| `defaultInputModes`, `defaultOutputModes` | Типы содержимого (MIME), которые агент принимает и отдаёт по умолчанию, например `text/plain`, `application/json`. |
| `provider` | Необязательно. Организация, отвечающая за агента: название и адрес сайта. |
| `documentationUrl` | Необязательно. Ссылка на дополнительную документацию об агенте. |
| `iconUrl` | Необязательно. Ссылка на значок агента. |
| `signatures` | Необязательные подписи Agent Card. |

Обязательными в таблице спецификации (раздел 4.4.1) помечены `supportedInterfaces` и `skills`; `provider`, `documentationUrl` и `iconUrl` необязательны. Для остальных полей обязательность смотрите в оригинале.

> **Заметка переводчика.** Требования безопасности названы в источниках по-разному: в тексте спецификации встречается `AgentCard.security`, в краткой справке — `security_requirements`, а в справочнике Google Cloud JSON-представление карточки использует `securityRequirements`. Точное имя берите из a2a.proto.

## Фрагмент из оригинала

Так выглядит часть Agent Card в версии 1.0 (пример со страницы «What's New»; многоточие заменяет содержимое подписей):

```json
{
  "supportedInterfaces": [
    {
      "url": "https://agent.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "extendedAgentCard": true
  },
  "signatures": [...]
}
```

Полный пример Agent Card приведён в разделе 8.5 оригинала.

## Проверка возможностей

Агент объявляет необязательные возможности в Agent Card. Если клиент пытается воспользоваться возможностью, которая не объявлена, агент ДОЛЖЕН вернуть соответствующую ошибку.

| Возможность | Если не объявлена (`false` или поле отсутствует) | Ошибка |
| --- | --- | --- |
| Push-уведомления, `capabilities.pushNotifications` | Операции настройки push-уведомлений: создание, получение, список, удаление | `PushNotificationNotSupportedError` |
| Потоковая передача, `capabilities.streaming` | `SendStreamingMessage`, `SubscribeToTask` | `UnsupportedOperationError` |
| Расширенная карточка, `capabilities.extendedAgentCard` | `GetExtendedAgentCard` | `UnsupportedOperationError`; если возможность объявлена, но карточка не настроена, то `ExtendedAgentCardNotConfiguredError` |
| Расширение с `required: true` | Клиент не заявил его поддержку в запросе | `ExtensionSupportRequiredError` |

Клиентам СЛЕДУЕТ проверять поддержку по Agent Card, прежде чем использовать необязательные возможности.

## Расширенная Agent Card

Агент может отдавать более подробную версию Agent Card после аутентификации клиента. Для этого служит операция `GetExtendedAgentCard`; она доступна, только если в публичной карточке указано `capabilities.extendedAgentCard: true`.

- **Аутентификация.** Клиент ДОЛЖЕН аутентифицировать запрос одной из схем, объявленных в публичной карточке.
- **Расширенные сведения.** В зависимости от уровня аутентификации агент МОЖЕТ вернуть дополнительные навыки, возможности или настройки, которых нет в публичной карточке.
- **Замена карточки.** Клиентам СЛЕДУЕТ заменить кэшированную публичную карточку полученной на время аутентифицированного сеанса или до смены версии карточки.

Рекомендации по безопасности смотрите в разделе 13.3 оригинала.

## Подпись Agent Card

Версия 1.0 позволяет подписывать Agent Card. Подпись делается по стандарту JWS (RFC 7515) над канонической формой JSON по RFC 8785 (JCS). Поле `signatures` при вычислении канонической формы исключается. Поддерживаются отделённые подписи с получением открытого ключа по `jku` или из доверенных хранилищ.

Если в карточке есть подписи, клиенту стоит проверить их до использования карточки.

## Версия протокола

В версии 1.0 версия протокола указывается не в карточке целиком, а в каждом интерфейсе (`supportedInterfaces[].protocolVersion`). Поэтому агент может открыть несколько интерфейсов с разными версиями, а клиент выбирает подходящий. Подробнее: [«Протокол»](https://a2adocs.ru/protocol/#versionirovanie).


---

# Задача (Task)

Единица работы и её состояния

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

Task — основная единица работы в A2A. У задачи есть текущий статус. Результаты работы сохраняются в артефактах, а если над задачей было несколько обменов, то и в истории.

## Поля Task

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `id` | `string` | Да | Уникальный идентификатор (например, UUID). Для новой задачи создаётся сервером. |
| `contextId` | `string` | Нет | Идентификатор контекста: набора связанных взаимодействий (задач и сообщений). |
| `status` | `TaskStatus` | Да | Текущий статус задачи: состояние и необязательное сообщение. |
| `artifacts` | массив [`Artifact`](https://a2adocs.ru/concepts/artifact/) | Нет | Набор артефактов, полученных в результате задачи. |
| `history` | массив [`Message`](https://a2adocs.ru/concepts/message-and-part/) | Нет | История взаимодействий в рамках задачи. |
| `metadata` | `object` | Нет | Произвольные метаданные о задаче в виде пар «ключ — значение». |

## TaskStatus

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `state` | `TaskState` | Да | Текущее состояние задачи. |
| `message` | `Message` | Нет | Сообщение, связанное со статусом. |
| `timestamp` | `timestamp` | Нет | Время фиксации статуса по ISO 8601, например `2023-10-27T10:00:00Z`. |

> **Заметка переводчика.** В версии 1.0 формат времени уточнён: UTC с точностью до миллисекунд, `YYYY-MM-DDTHH:mm:ss.sssZ`.

## Состояния

Перечисление `TaskState` определяет возможные состояния жизненного цикла задачи. Наведите на состояние на шкале, чтобы прочитать его описание.



| Значение | Класс | Описание |
| --- | --- | --- |
| `TASK_STATE_UNSPECIFIED` | не указан | Задача в неизвестном или неопределённом состоянии. |
| `TASK_STATE_SUBMITTED` | не указан | Задача успешно отправлена и принята. |
| `TASK_STATE_WORKING` | не указан | Агент активно обрабатывает задачу. |
| `TASK_STATE_COMPLETED` | конечное | Задача успешно завершена. |
| `TASK_STATE_FAILED` | конечное | Задача завершена с ошибкой. |
| `TASK_STATE_CANCELED` | конечное | Задача отменена до завершения. |
| `TASK_STATE_REJECTED` | конечное | Агент решил не выполнять задачу. Это может произойти при создании задачи или позже, когда агент понял, что не может или не будет продолжать. |
| `TASK_STATE_INPUT_REQUIRED` | прерванное | Агенту нужен дополнительный ввод пользователя, чтобы продолжить. |
| `TASK_STATE_AUTH_REQUIRED` | прерванное | Для продолжения требуется аутентификация. |

> **Заметка переводчика.** Оригинал называет конечными (terminal) и прерванными (interrupted) только перечисленные состояния. Для остальных класса не указано, поэтому в таблице стоит «не указан».

Сообщения в задачи с конечным состоянием не принимаются: сервер вернёт `UnsupportedOperationError`. Режимы выполнения, при которых операция ждёт конечного или прерванного состояния, описаны на странице [«Методы»](https://a2adocs.ru/protocol/methods/#sendmessage).

## Идентификаторы: контекст и задача

### Идентификатор контекста

`contextId` логически объединяет несколько связанных задач и сообщений и обеспечивает непрерывность разговора.

- Агент МОЖЕТ сгенерировать новый `contextId`, если пришло сообщение без него. Сгенерированный идентификатор ДОЛЖЕН попасть в ответ (в `Task` или `Message`).
- Агент МОЖЕТ принять и сохранить `contextId`, присланный клиентом. Если принять его нельзя, агент ДОЛЖЕН отклонить запрос ошибкой и НЕ ДОЛЖЕН создавать новый `contextId` для ответа.
- Клиентам СЛЕДУЕТ НЕ присылать собственный `contextId`, пока они не понимают, как сервер его обработает. Идентификаторы, созданные сервером, СЛЕДУЕТ считать непрозрачными.
- Все задачи и сообщения с одним `contextId` СЛЕДУЕТ считать частью одного разговора. Агент МОЖЕТ использовать его, чтобы хранить внутреннее состояние, историю или контекст LLM. Агент МОЖЕТ ввести политику истечения срока контекста и СЛЕДУЕТ её описать.

### Идентификатор задачи

`taskId` — уникальный идентификатор объекта `Task`.

- Идентификаторы задач создаёт **сервер**, когда в ответ на сообщение появляется новая задача. Для каждой новой задачи агент ДОЛЖЕН создать уникальный `taskId` и вернуть его в объекте `Task`.
- Если клиент указывает `taskId` в сообщении, он ДОЛЖЕН ссылаться на существующую задачу. Иначе агент ДОЛЖЕН вернуть `TaskNotFoundError`.
- Создавать новые задачи с идентификатором, придуманным клиентом, **нельзя**.

## Многоходовые взаимодействия

A2A поддерживает диалоги из нескольких обменов через идентификаторы контекста и ссылки на задачи.

- **Преемственность контекста.** Клиент МОЖЕТ указывать `contextId` в следующих сообщениях, продолжая прежнее взаимодействие. Клиент МОЖЕТ указать `taskId` (с `contextId` или без), чтобы продолжить или уточнить конкретную задачу. Указав только `contextId`, клиент начинает новую задачу в существующем разговоре.
- **Состояние «нужен ввод».** Агент может запросить дополнительные данные, переведя задачу в `TASK_STATE_INPUT_REQUIRED`. Клиент продолжает, отправив новое сообщение с тем же `taskId` и `contextId`.
- **Уточняющие сообщения.** Клиенты могут присылать дополнительные сообщения со ссылкой на `taskId`. В поле `referenceTaskIds` сообщения СЛЕДУЕТ явно указывать связанные задачи; агентам СЛЕДУЕТ использовать их, чтобы лучше понять смысл последующих запросов.
- **Наследование контекста.** Новые задачи в том же `contextId` могут наследовать контекст прежних взаимодействий.

Правила согласованности:

- если указан только `taskId`, агент ДОЛЖЕН вывести `contextId` из задачи;
- сообщения, у которых `contextId` не совпадает с контекстом указанной задачи, агент ДОЛЖЕН отклонять.


---

# Сообщение и часть (Message и Part)

Из чего состоит обмен

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/concepts/message-and-part/). Тип: Перевод. Основа: Спецификация, разделы 4.1.4–4.1.6 и 3.7 (https://a2a-protocol.org/latest/specification/#414-message). Версия спецификации 1.0.0, сверено 05.10.2026.

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

## Message

Message — единица общения между клиентом и сервером. Оно может быть связано с контекстом и (или) задачей.

- Для сообщений сервера `contextId` обязателен, а `taskId` указывается, только если была создана задача.
- Для сообщений клиента оба поля необязательны. Если указаны оба, они должны совпадать: `contextId` должен быть тем, что задан у задачи.
- Если указан только `taskId`, сервер сам определит `contextId` по задаче.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `messageId` | `string` | Да | Уникальный идентификатор сообщения (например, UUID). Создаётся автором сообщения. |
| `contextId` | `string` | Нет | Идентификатор контекста. Если указан, сообщение связано с этим контекстом. |
| `taskId` | `string` | Нет | Идентификатор задачи. Если указан, сообщение связано с этой задачей. |
| `role` | `Role` | Да | Отправитель сообщения. |
| `parts` | массив `Part` | Да | Содержимое сообщения. |
| `metadata` | `object` | Нет | Любые метаданные, которые нужно передать с сообщением. |
| `extensions` | массив `string` | Нет | URI расширений, которые присутствуют в сообщении или внесли в него вклад. |
| `referenceTaskIds` | массив `string` | Нет | Идентификаторы задач, на которые ссылается сообщение для дополнительного контекста. |

## Role

Роль определяет отправителя сообщения.

| Значение | Описание |
| --- | --- |
| `ROLE_UNSPECIFIED` | Роль не указана. |
| `ROLE_USER` | Сообщение от клиента серверу. |
| `ROLE_AGENT` | Сообщение от сервера клиенту. |

## Part

Part — контейнер для фрагмента содержимого. Часть может быть текстом, файлом (изображение, видео и т. п.) или блоком структурированных данных (JSON).

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `text` | `string` | Одно из четырёх | Текстовое содержимое. |
| `raw` | `bytes` | Одно из четырёх | Содержимое файла в виде байтов. В JSON кодируется строкой base64. |
| `url` | `string` | Одно из четырёх | Ссылка на содержимое файла. |
| `data` | `any` | Одно из четырёх | Произвольные структурированные данные: любое значение JSON (объект, массив, строка, число, логическое значение или null). |
| `metadata` | `object` | Нет | Метаданные части. |
| `filename` | `string` | Нет | Имя файла, например `document.pdf`. |
| `mediaType` | `string` | Нет | MIME-тип содержимого, например `text/plain`, `application/json`, `image/png`. Доступен для всех видов частей. |

Часть ДОЛЖНА содержать ровно одно из полей: `text`, `raw`, `url` или `data`.

Примеры частей в версии 1.0 (со страницы «What's New» оригинальной документации):

```json
// Текст
{
  "text": "Hello world",
  "mediaType": "text/plain"
}

// Файл по ссылке
{
  "url": "https://example.com/doc.pdf",
  "filename": "doc.pdf",
  "mediaType": "application/pdf"
}

// Файл в байтах
{
  "raw": "base64encodedcontent==",
  "filename": "image.png",
  "mediaType": "image/png"
}

// Структурированные данные
{
  "data": {"key": "value"},
  "mediaType": "application/json"
}
```

> **Заметка переводчика.** В версии 0.3 части делились на `TextPart`, `FilePart` и `DataPart` и различались полем `kind`. В 1.0 тип определяется тем, какое поле присутствует. Подробнее: [«Миграция»](https://a2adocs.ru/migration/#part).

## Сообщения и артефакты

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

Сообщения выполняют несколько ролей:

- **Начало задачи.** Клиенты отправляют сообщения, чтобы запустить новые задачи.
- **Уточнения.** Агент может отправить клиенту сообщение с просьбой уточнить детали до начала задачи.
- **Статусные сообщения.** Агенты прикрепляют сообщения к событиям обновления статуса, чтобы сообщить о прогрессе, запросить дополнительный ввод или дать информацию.
- **Работа внутри задачи.** Клиенты отправляют сообщения, чтобы дать дополнительные данные или указания для уже идущей задачи.

Сообщения НЕ СЛЕДУЕТ использовать для доставки результатов работы. Результаты СЛЕДУЕТ возвращать как [артефакты](https://a2adocs.ru/concepts/artifact/), связанные с задачей. Так разделяются общение (сообщения) и выходные данные (артефакты).

### Что не гарантируется

- Поле `history` задачи содержит сообщения, которыми обменивались во время выполнения. Но сохранение всех сообщений не гарантируется: временные информационные сообщения могут не храниться, как и сообщения, отправленные до создания задачи. Что сохранять, решает агент.
- Клиент, который получает обновления по потоку, может не получить часть статусных сообщений, если соединение оборвалось и восстановилось. Поэтому сообщения НЕЛЬЗЯ считать надёжным способом доставки критичной информации.
- Агент МОЖЕТ сохранять в истории все сообщения с важной информацией, чтобы клиент позже мог их получить. Но клиенты НЕ ДОЛЖНЫ на это полагаться, если иное не согласовано отдельно, вне протокола.

> **Заметка переводчика.** Для защиты от дублей агент может использовать `messageId`: отправка сообщения МОЖЕТ быть идемпотентной (раздел 3.3.1).


---

# Артефакт (Artifact)

Как приходит результат работы агента

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/concepts/artifact/). Тип: Перевод. Основа: Спецификация, разделы 4.1.7, 4.2.2 и 3.7 (https://a2a-protocol.org/latest/specification/#417-artifact). Версия спецификации 1.0.0, сверено 05.10.2026.

Артефакт — результат, который агент создаёт при выполнении задачи: документ, изображение, набор структурированных данных. Он состоит из [частей](https://a2adocs.ru/concepts/message-and-part/#part).

## Поля Artifact

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `artifactId` | `string` | Да | Уникальный идентификатор (например, UUID). Должен быть уникален в пределах задачи. |
| `name` | `string` | Нет | Название артефакта, понятное человеку. |
| `description` | `string` | Нет | Описание артефакта, понятное человеку. |
| `parts` | массив `Part` | Да | Содержимое артефакта. Должна быть хотя бы одна часть. |
| `metadata` | `object` | Нет | Метаданные артефакта. |
| `extensions` | массив `string` | Нет | URI расширений, которые присутствуют в артефакте или внесли в него вклад. |

## Артефакт или сообщение

Результаты работы СЛЕДУЕТ возвращать артефактами, а сообщения оставлять для общения: уточнений, статусов, дополнительного ввода. Подробнее об этом разделении: [«Сообщение и часть»](https://a2adocs.ru/concepts/message-and-part/#soobscheniya-i-artefakty).

## Артефакты при потоковой передаче

Когда клиент получает обновления потоком, новые и изменённые артефакты приходят событием `TaskArtifactUpdateEvent`. Событие позволяет присылать артефакт частями.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `taskId` | `string` | Да | Идентификатор задачи, к которой относится артефакт. |
| `contextId` | `string` | Да | Идентификатор контекста, которому принадлежит задача. |
| `artifact` | `Artifact` | Да | Созданный или обновлённый артефакт. |
| `append` | `boolean` | Нет | Если `true`, содержимое нужно дописать к ранее отправленному артефакту с тем же идентификатором. |
| `lastChunk` | `boolean` | Нет | Если `true`, это последний фрагмент артефакта. |
| `metadata` | `object` | Нет | Метаданные обновления артефакта. |

> **Заметка переводчика.** На странице «What's New» у события в версии 1.0 упомянуто поле `index` (позиция артефакта в массиве артефактов задачи), но в таблице спецификации его нет. Сверяйтесь с a2a.proto.

## Артефакты в списке задач

В операции `ListTasks` артефакты по умолчанию не возвращаются, чтобы не раздувать ответ. Если параметр `includeArtifacts` равен `false` (по умолчанию), поле `artifacts` ДОЛЖНО быть полностью опущено в каждой задаче: оно не должно присутствовать даже как пустой массив или `null`. При `true` поле включается с реальным содержимым (оно может быть пустым массивом, если у задачи нет артефактов). Подробнее: [«Методы»](https://a2adocs.ru/protocol/methods/#listtasks).


---

# Протокол

Привязки, версии и параметры сервиса

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

Протокол описывает, как клиент и агент обмениваются данными. Модель данных и операции сформулированы независимо от транспорта, а на практике вы выбираете одну из привязок и пользуетесь одиннадцатью операциями.

## Привязки

A2A определён в трёх привязках. Все они ДОЛЖНЫ давать функционально эквивалентные представления структур данных.

| Привязка | Как устроена |
| --- | --- |
| JSON-RPC 2.0 | Запросы JSON-RPC по HTTP, потоковая передача через Server-Sent Events. Раздел 9 оригинала. |
| gRPC | Службы и вызовы gRPC на основе a2a.proto. Раздел 10 оригинала. |
| HTTP+JSON/REST | Ресурсные адреса и методы HTTP, например `POST /message:send`. Раздел 11 оригинала. |

Для HTTP+JSON/REST зарегистрирован тип содержимого `application/a2a+json`. Протокол можно переносить и на другие транспорты: см. страницу [«Custom Protocol Bindings»](https://a2a-protocol.org/latest/topics/custom-protocol-bindings/) оригинальной документации.

Пример запроса в привязке HTTP+JSON:

```http
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
A2A-Version: 1.0
Authorization: Bearer token

{
  "message": {
    "role": "ROLE_USER",
    "parts": [{"text": "Найди рестораны рядом"}],
    "messageId": "msg-uuid"
  }
}
```

> **Заметка переводчика.** Пример составлен по образцу из оригинала. Заголовок `A2A-Version: 1.0` добавлен по требованию раздела 3.6.1. В примерах оригинала значения этого заголовка отличаются, поэтому ориентируйтесь на текст раздела 3.6.

## Версионирование

Версия протокола задаётся элементами `Major.Minor` версии спецификации, например `1.0`. Номера патчей не влияют на совместимость: их НЕ СЛЕДУЕТ указывать в запросах, ответах и Agent Card, и они НЕ ДОЛЖНЫ учитываться, когда клиент и сервер согласуют версию.

### Что делает клиент

- Клиент ДОЛЖЕН отправлять заголовок `A2A-Version` с каждым запросом. Это сохраняет совместимость после того, как агент обновится до новой версии протокола. Исключение — клиенты версии 0.3: при пустом заголовке считается, что версия 0.3.
- Версию МОЖНО передать и параметром запроса `A2A-Version=1.0` вместо заголовка.
- Клиентским агентам, которым нужны новейшие возможности, СЛЕДУЕТ запрашивать конкретные версии и избегать автоматического отката на старые, чтобы незаметно не потерять функциональность.

### Что делает сервер

- Агент ДОЛЖЕН обрабатывать запрос по семантике запрошенной версии (совпадение `Major.Minor`). Если интерфейс эту версию не поддерживает, агент ДОЛЖЕН вернуть `VersionNotSupportedError`.
- Пустое значение агент ДОЛЖЕН трактовать как версию 0.3.
- Агент МОЖЕТ открыть несколько интерфейсов одного транспорта с разными версиями, по одному и тому же или по разным адресам.

### Инструменты и SDK

Библиотеки и SDK, которые реализуют A2A, ДОЛЖНЫ помогать клиентам управлять версиями: например, согласовывать транспорт и версию протокола.

## Параметры сервиса

Параметры сервиса — пары «ключ — значение», которые передаются вместе с операциями и применимы ко всем запросам. Ключи не зависят от регистра, значения зависят. Способ передачи определяет привязка: HTTP-заголовки для HTTP-привязок, метаданные для gRPC. Пользовательские привязки ДОЛЖНЫ описать этот способ.

| Имя | Описание | Пример значения |
| --- | --- | --- |
| `A2A-Extensions` | Список URI расширений через запятую, которые клиент хочет использовать в запросе. | `https://example.com/extensions/geolocation/v1` |
| `A2A-Version` | Версия протокола A2A, которую использует клиент. Если версия не поддерживается, агент возвращает `VersionNotSupportedError`. | `1.0` |

Все параметры сервиса, определённые спецификацией, начинаются с `a2a-`, чтобы не конфликтовать с параметрами транспорта и инфраструктуры.

## Операции

Одиннадцать операций делятся на четыре группы. Таблица с запросами, ответами и описанием приведена на странице [«Методы»](https://a2adocs.ru/protocol/methods/).

- **Отправка сообщений:** `SendMessage`, `SendStreamingMessage`.
- **Работа с задачами:** `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`.
- **Push-уведомления:** `CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs`, `DeleteTaskPushNotificationConfig`.
- **Agent Card:** `GetExtendedAgentCard`.

## Дальше

- [Методы](https://a2adocs.ru/protocol/methods/): операции и их поведение.
- [Обновления задач](https://a2adocs.ru/protocol/updates/): опрос, поток и push.
- [Ошибки](https://a2adocs.ru/protocol/errors/): категории и ошибки A2A.
- [Миграция с 0.3 на 1.0](https://a2adocs.ru/migration/): что изменилось в протоколе.


---

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

Одиннадцать операций 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/).


---

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

Опрос, потоковая передача и push-уведомления

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/protocol/updates/). Тип: Перевод. Основа: Спецификация, разделы 3.5, 4.2 и 4.3 (https://a2a-protocol.org/latest/specification/#35-task-update-delivery-mechanisms). Версия спецификации 1.0.0, сверено 05.10.2026.

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

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

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

## Опрос

Клиент периодически вызывает [`GetTask`](https://a2adocs.ru/protocol/methods/#gettask), чтобы проверить состояние задачи. Это самый простой способ, он работает со всеми привязками. Цена — задержка и лишние запросы.

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

Операции [`SendStreamingMessage`](https://a2adocs.ru/protocol/methods/#sendstreamingmessage) и [`SubscribeToTask`](https://a2adocs.ru/protocol/methods/#subscribetotask) открывают поток событий. Если агент не объявил потоковую передачу, он вернёт `UnsupportedOperationError`.

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

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

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

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

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

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

### Формат StreamResponse

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

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

### События

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

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

**TaskArtifactUpdateEvent** сообщает о создании или обновлении артефакта. Поля описаны на странице [«Артефакт»](https://a2adocs.ru/concepts/artifact/#artefakty-pri-potokovoy-peredache).

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

Push-уведомления доставляются HTTP POST на вебхук, зарегистрированный клиентом. Настройка выполняется операциями из группы [push-уведомлений](https://a2adocs.ru/protocol/methods/#push-uvedomleniya).

Когда задача обновляется, агент отправляет 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](https://www.iana.org/assignments/http-authschemes/), например `Bearer`, `Basic`, `Digest`. Названия схем не зависят от регистра (RFC 9110, раздел 11.1). |
| `credentials` | `string` | Нет | Учётные данные для push-уведомлений. Формат зависит от схемы, например токен для `Bearer`. |

> **Заметка переводчика.** Семантика доставки и гарантии надёжности определены в разделе 4.3 оригинала; требования безопасности для вебхуков — в разделе 13.2.


---

# Ошибки

Категории ошибок и ошибки, специфичные для A2A

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/protocol/errors/). Тип: Перевод. Основа: Спецификация, раздел 3.3.2; What's New (https://a2a-protocol.org/latest/specification/#332-error-handling). Версия спецификации 1.0.0, сверено 05.10.2026.

Любая операция может вернуть ошибку. Серверы ДОЛЖНЫ возвращать подходящие ошибки и СЛЕДУЕТ давать полезную информацию, которая помогает клиентам устранить проблему.

## Категории ошибок

| Категория | Требования к серверу | Примеры кодов | Типичные сценарии |
| --- | --- | --- | --- |
| Аутентификация: неверные или отсутствующие учётные данные | ДОЛЖЕН отклонять запросы с неверными или отсутствующими учётными данными. СЛЕДУЕТ включать в ответ сведения о вызове аутентификации и указывать нужную схему. | HTTP `401 Unauthorized`, gRPC `UNAUTHENTICATED`, особая ошибка JSON-RPC | Нет bearer-токена, истёк API-ключ, неверный токен OAuth. |
| Авторизация: недостаточно прав | ДОЛЖЕН вернуть ошибку авторизации, если у аутентифицированного клиента не хватает прав. СЛЕДУЕТ указывать, какого права или scope не хватает, не раскрывая сведений о недоступных ресурсах. НЕ ДОЛЖЕН раскрывать существование ресурсов, к которым у клиента нет доступа. | HTTP `403 Forbidden`, gRPC `PERMISSION_DENIED`, особая ошибка JSON-RPC | Попытка получить задачу другого пользователя, недостаточные scope OAuth. |
| Валидация: неверные параметры или формат | ДОЛЖЕН проверять все входные параметры до обработки. СЛЕДУЕТ указывать, какие параметры не прошли проверку и почему, и подсказывать допустимые значения или форматы. | HTTP `400 Bad Request`, gRPC `INVALID_ARGUMENT`, JSON-RPC `-32602 Invalid params` | Неверный формат идентификатора задачи, нет обязательных частей сообщения, неподдерживаемый тип содержимого. |
| Ресурсы: задача не найдена или недоступна | ДОЛЖЕН вернуть «не найдено», если ресурса нет или он недоступен аутентифицированному клиенту. НЕ СЛЕДУЕТ различать «не существует» и «нет доступа», чтобы не допустить утечки информации. | HTTP `404 Not Found`, gRPC `NOT_FOUND`, особая ошибка JSON-RPC | Идентификатора задачи нет, задача удалена, настройка не найдена. |
| Системные: внутренний сбой или временная недоступность | СЛЕДУЕТ возвращать разные коды для временных и постоянных сбоев. МОЖЕТ давать рекомендации по повтору (например, заголовок `Retry-After` в HTTP). СЛЕДУЕТ записывать системные ошибки в журнал. | HTTP `500` или `503`, gRPC `INTERNAL` или `UNAVAILABLE`, JSON-RPC `-32603 Internal error` | Сбой соединения с базой данных, таймаут нижестоящего сервиса, превышение лимита запросов. |

## Структура ошибки

Все ответы с ошибкой в протоколе A2A, независимо от привязки, ДОЛЖНЫ передавать:

1. **Код ошибки.** Машиночитаемый идентификатор типа ошибки: строковый или числовой код либо статус, принятый в протоколе.
2. **Сообщение об ошибке.** Описание, понятное человеку.
3. **Подробности** (необязательно). Массив объектов с дополнительной структурированной информацией. Каждый объект ДОЛЖЕН содержать ключ `@type`, определяющий тип объекта (представление `Any` из ProtoJSON). Где это уместно, СЛЕДУЕТ использовать типы из модели ошибок `google.rpc`, например `ErrorInfo` и `BadRequest`. В подробностях можно указать затронутые поля, контекст (идентификатор задачи, время) и подсказки по устранению.

Привязки ДОЛЖНЫ отображать эти элементы в свои родные представления ошибок, сохраняя смысл.

## Ошибки A2A

| Ошибка | Описание |
| --- | --- |
| `TaskNotFoundError` | Указанный идентификатор не соответствует существующей или доступной задаче. Он может быть неверным, истёкшим или относиться к завершённой и удалённой задаче. |
| `TaskNotCancelableError` | Попытка отменить задачу, которую отменить нельзя: она уже в конечном состоянии (`TASK_STATE_COMPLETED`, `TASK_STATE_FAILED`, `TASK_STATE_CANCELED`, `TASK_STATE_REJECTED`). |
| `PushNotificationNotSupportedError` | Клиент пытается использовать push-уведомления, но агент их не поддерживает (`AgentCard.capabilities.pushNotifications` равно `false`). |
| `UnsupportedOperationError` | Запрошенная операция или её отдельный аспект не поддерживается этой реализацией агента. |
| `ContentTypeNotSupportedError` | Тип содержимого в частях сообщения или предполагаемый для артефакта не поддерживается агентом или конкретным навыком. |
| `InvalidAgentResponseError` | Агент вернул ответ, не соответствующий спецификации для текущего метода. |
| `ExtendedAgentCardNotConfiguredError` | У агента нет расширенной Agent Card, хотя она требуется для запрошенной операции. |
| `ExtensionSupportRequiredError` | Сервер потребовал использовать расширение с `required: true` из Agent Card, но клиент не заявил его поддержку в запросе. |
| `VersionNotSupportedError` | Версия протокола, указанная в запросе (параметром `A2A-Version`), не поддерживается агентом. |

## Модель ошибок в версии 1.0

В версии 1.0 ошибки приведены к ProtoJSON-представлению `google.rpc.Status` вместо RFC 9457 (Problem Details). Для JSON-RPC и HTTP+JSON действует единое правило:

- в `details` (в JSON-RPC это поле `data`) ДОЛЖЕН быть объект `google.rpc.ErrorInfo`;
- в нём поле `reason` содержит тип ошибки A2A в формате UPPER_SNAKE_CASE (например, `TASK_NOT_FOUND`);
- поле `domain` равно `a2a-protocol.org`;
- тип содержимого HTTP+JSON-ответа с ошибкой теперь `application/json`, а не `application/problem+json`.

Пример для JSON-RPC (со страницы «What's New»):

```json
"error": {
  "code": -32001,
  "message": "Task not found",
  "data": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "TASK_NOT_FOUND",
      "domain": "a2a-protocol.org",
      "metadata": { "taskId": "123" }
    }
  ]
}
```

Пример для HTTP+JSON:

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The specified task ID does not exist",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org"
      }
    ]
  }
}
```

Соответствие ошибок конкретным кодам привязок смотрите в разделах 5.4, 9.5, 10.6 и 11.6 оригинала.


---

# Миграция с 0.3 на 1.0

Что изменилось и в каком порядке обновлять

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/migration/). Тип: Перевод. Основа: What's New in v1.0 (https://a2a-protocol.org/latest/whats-new-v1/). Версия спецификации 1.0.0, сверено 05.10.2026.

Версия 1.0 — первая стабильная версия A2A. Она делает протокол строже и понятнее, но содержит ломающие изменения во взаимодействии, поэтому код, написанный для 0.3, придётся обновить. Страница систематизирует и переводит документ «What's New in v1.0» из официальной документации.

> **Заметка переводчика.** В анонсе релиза сказано, что Agent Card изменён так, что агент может объявлять поддержку и 0.3, и 1.0 одновременно. Но структура полей карточки при этом изменилась (см. [ниже](#agent-card)), так что код разбора карточки обновлять всё равно нужно.

## С чего начать

Официальная документация расставляет приоритеты так.

| Приоритет | Что сделать |
| --- | --- |
| Критично, сразу | Обновить разбор частей (`Part`) и событий потока (способ различения типов). Обновить разбор Agent Card (структура). Добавить заголовок `A2A-Version` во все запросы. |
| Высокий, в течение месяца | Перейти на курсорную пагинацию. Обновить обработку значений состояния и ролей. Добавить поддержку параметра `returnImmediately`. |
| Средний, в течение трёх месяцев | Реализовать проверку подписи Agent Card. Проверять требуемые расширения. Привести временные метки к ISO 8601. Реализовать новые типы ошибок. |
| Низкий, по возможности | Использовать расширенные метаданные. Реализовать аутентификацию mTLS. |

## Переименование операций

| Версия 0.3.0 | Версия 1.0 |
| --- | --- |
| `message/send` | `SendMessage` |
| `message/stream` | `SendStreamingMessage` |
| `tasks/get` | `GetTask` |
| (не было) | `ListTasks` — новая операция |
| `tasks/cancel` | `CancelTask` |
| `tasks/resubscribe` | `SubscribeToTask` |
| `agent/getAuthenticatedExtendedCard` | `GetExtendedAgentCard` |
| `tasks/pushNotificationConfig/set` | `CreateTaskPushNotificationConfig` |
| `tasks/pushNotificationConfig/get` | `GetTaskPushNotificationConfig` |
| `tasks/pushNotificationConfig/list` | `ListTaskPushNotificationConfigs` |
| `tasks/pushNotificationConfig/delete` | `DeleteTaskPushNotificationConfig` |

Модель запросов всех операций push-уведомлений изменилась, а `TaskPushNotificationConfig` стала плоской. Оригинал отмечает, что на время перехода предусмотрены псевдонимы имён операций.

## Значения перечислений

Все значения перечислений теперь записываются в стиле `SCREAMING_SNAKE_CASE` с префиксом типа. Так требует спецификация ProtoJSON. Это один из самых заметных ломающих изменений.

| Версия 0.3.0 | Версия 1.0 |
| --- | --- |
| `"submitted"` | `"TASK_STATE_SUBMITTED"` |
| `"working"` | `"TASK_STATE_WORKING"` |
| `"completed"` | `"TASK_STATE_COMPLETED"` |
| `"failed"` | `"TASK_STATE_FAILED"` |
| `"canceled"` | `"TASK_STATE_CANCELED"` |
| `"rejected"` | `"TASK_STATE_REJECTED"` |
| `"input-required"` | `"TASK_STATE_INPUT_REQUIRED"` |
| `"auth-required"` | `"TASK_STATE_AUTH_REQUIRED"` |
| `"user"` | `"ROLE_USER"` |
| `"agent"` | `"ROLE_AGENT"` |

```json
// 0.3.0
{ "status": { "state": "completed", "timestamp": "2024-03-15T10:15:00Z" } }

// 1.0
{ "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2024-03-15T10:15:00.000Z" } }
```

Время теперь указывается строго по ISO 8601 в UTC с миллисекундами: `YYYY-MM-DDTHH:mm:ss.sssZ`.

## Part

Структура частей полностью переработана. Вместо отдельных `TextPart`, `FilePart` и `DataPart` теперь одно сообщение `Part`.

**Что изменилось:**

- удалены отдельные типы `TextPart`, `FilePart`, `DataPart`;
- удалено поле-различитель `kind`;
- удалён вложенный объект `file`;
- появилось единое сообщение `Part` с полем `oneof content`: тип определяется тем, какое поле есть: `text`, `raw`, `url` или `data`;
- `mediaType` заменяет `mimeType` и доступно для всех видов частей;
- `filename` доступно для всех видов частей, а не только для файлов;
- `raw` — встроенное двоичное содержимое (в JSON — base64);
- `url` — ссылка на файл, заменяет `file.fileWithUri`.

```json
// 0.3.0
{ "kind": "text", "text": "Hello world" }
{ "kind": "file", "file": { "fileWithUri": "https://example.com/doc.pdf", "mimeType": "application/pdf" } }
{ "kind": "data", "data": { "key": "value" } }

// 1.0
{ "text": "Hello world", "mediaType": "text/plain" }
{ "url": "https://example.com/doc.pdf", "filename": "doc.pdf", "mediaType": "application/pdf" }
{ "data": { "key": "value" }, "mediaType": "application/json" }
```

Код, который определял тип по `kind`, нужно заменить проверкой наличия поля:

```javascript
// 0.3.0
if (part.kind === "text") { return part.text; }
else if (part.kind === "file") { /* part.file.fileWithUri или fileWithBytes */ }
else if (part.kind === "data") { return part.data; }

// 1.0
if ("text" in part) { return part.text; }
else if ("url" in part) { return fetchFile(part.url); }
else if ("raw" in part) { return decodeBase64(part.raw); }
else if ("data" in part) { return part.data; }
```

В `Message` и `Artifact` появилось поле `extensions[]` с URI расширений.

## События потока

Тип события больше не определяется полем `kind`: его определяет имя JSON-поля-обёртки.

- удалено поле `kind`;
- удалено логическое поле `final` у `TaskStatusUpdateEvent`: завершение потока определяется механизмом закрытия потока конкретной привязки;
- новый шаблон: тип события определяется именем члена JSON, `statusUpdate` или `artifactUpdate`.

```json
// 0.3.0
{ "kind": "status-update", "taskId": "...", "contextId": "...", "status": {}, "final": true }

// 1.0
{ "statusUpdate": { "taskId": "...", "contextId": "...", "status": {} } }
```

```javascript
// 0.3.0
if (event.kind === "status-update") { handleStatusUpdate(event); }
else if (event.kind === "artifact-update") { handleArtifactUpdate(event); }

// 1.0
if ("statusUpdate" in event) { handleStatusUpdate(event.statusUpdate); }
else if ("artifactUpdate" in event) { handleArtifactUpdate(event.artifactUpdate); }
```

Дополнительно уточнено, что допускается несколько одновременных потоков одной задачи, и все они получают одни и те же события в одном порядке. Подробнее: [«Обновления задач»](https://a2adocs.ru/protocol/updates/).

## Agent Card

Структура карточки переработана: сведения об интерфейсах собраны в один список.

| Что | Как было в 0.3.0 | Как стало в 1.0 |
| --- | --- | --- |
| Версия протокола | `protocolVersion` в карточке | В каждом интерфейсе: `supportedInterfaces[].protocolVersion` |
| Основной адрес | `url` | `supportedInterfaces[0].url` |
| Предпочтительный транспорт и дополнительные интерфейсы | `preferredTransport`, `additionalInterfaces` | Единый список `supportedInterfaces[]` (у каждого `url`, `protocolBinding`, `protocolVersion`) |
| Расширенная карточка | `supportsAuthenticatedExtendedCard` в корне | `capabilities.extendedAgentCard` |
| Подписи | Не было | Необязательное поле `signatures` |

```json
// 0.3.0
{
  "protocolVersion": "0.3",
  "url": "https://agent.example.com/a2a",
  "preferredTransport": "JSONRPC",
  "supportsAuthenticatedExtendedCard": true,
  "additionalInterfaces": [...]
}

// 1.0
{
  "supportedInterfaces": [
    { "url": "https://agent.example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "extendedAgentCard": true },
  "signatures": [...]
}
```

```javascript
// 0.3.0
const endpoint = agentCard.url;
const transport = agentCard.preferredTransport;
const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;

// 1.0
const primaryInterface = agentCard.supportedInterfaces[0];
const endpoint = primaryInterface.url;
const transport = primaryInterface.protocolBinding;
const supportsExtended = agentCard.capabilities.extendedAgentCard;
```

Адрес публикации остался прежним: `/.well-known/agent-card.json`. Подробнее: [«Agent Card»](https://a2adocs.ru/concepts/agent-card/).

## Пагинация

Операция `ListTasks` появилась только в 1.0, и она сразу курсорная. Если вы реализовывали постраничный список по-своему, перейдите на `pageToken` и `nextPageToken`:

```javascript
let pageToken = undefined;
do {
  const response = await listTasks({ pageToken, pageSize: 50 });
  // обработать response.tasks
  pageToken = response.nextPageToken;
} while (pageToken);
```

Подробнее: [«Методы»](https://a2adocs.ru/protocol/methods/#listtasks).

## Ошибки

HTTP+JSON-ответы с ошибкой теперь используют ProtoJSON-представление `google.rpc.Status` вместо RFC 9457. Тип содержимого изменился с `application/problem+json` на `application/json`. Для ошибок A2A в `details` (JSON-RPC: `data`) ДОЛЖЕН быть объект `google.rpc.ErrorInfo` с полями `reason` и `domain: "a2a-protocol.org"`. Примеры и список ошибок: [«Ошибки»](https://a2adocs.ru/protocol/errors/#model-oshibok-v-versii-1-0).

## HTTP-адреса и идентификаторы

- **Без префикса `/v1`.** В HTTP+JSON-привязке убран префикс `/v1`. Было `POST /v1/message:send`, стало `POST /message:send` и `GET /tasks/{id}`. Версию при необходимости владелец агента может включить в базовый адрес.
- **Простые идентификаторы.** Все идентификаторы теперь простые значения. Составные идентификаторы вида `tasks/{taskId}` ушли: операции, где раньше использовались составные идентификаторы, теперь принимают родителя и ресурс отдельными полями. Например, `tasks/{taskId}/pushNotificationConfigs/{configId}` превратилось в отдельные `task_id` и `id`. Идентификаторы прямо соответствуют ключам в базе данных.

## OAuth 2.0

Поддержка OAuth 2.0 приведена в соответствие с актуальными рекомендациями по безопасности (BCP).

- **Удалены потоки:** `ImplicitOAuthFlow` (риск утечки токена через историю и журналы браузера) и `PasswordOAuthFlow` (риск раскрытия учётных данных).
- **Добавлен поток:** `DeviceCodeOAuthFlow` (RFC 8628) для консольных инструментов, IoT-устройств и сред без удобного ввода.
- **Усилена безопасность:** в `AuthorizationCodeOAuthFlow` добавлено поле `pkceRequired` (RFC 7636): оно показывает, обязателен ли PKCE. PKCE рекомендуется всем OAuth-клиентам и обязателен для публичных клиентов.

```json
// 0.3.0: поток implicit (теперь удалён)
{ "implicitFlow": { "authorizationUrl": "https://auth.example.com/authorize", "scopes": { "read": "Read access" } } }

// 1.0: вместо него код авторизации + PKCE
{
  "authorizationCodeFlow": {
    "authorizationUrl": "https://auth.example.com/authorize",
    "tokenUrl": "https://auth.example.com/token",
    "pkceRequired": true,
    "scopes": { "read": "Read access" }
  }
}
```

## Что нового в 1.0

- **Новая операция `ListTasks`** с фильтрацией и курсорной пагинацией.
- **Мультитенантность.** Поле `tenant` во всех запросах и в `AgentInterface`: так можно обслуживать несколько агентов с одной точки входа.
- **Режим выполнения.** Параметр `returnImmediately` в `SendMessageConfiguration`: ждать завершения задачи (по умолчанию) или вернуться сразу.
- **Подпись Agent Card.** JWS и каноническая форма JSON (RFC 8785).
- **Требуемые расширения.** Расширение в Agent Card можно пометить как обязательное (`required`).
- **Согласование версий.** Заголовок `A2A-Version` и версия протокола в каждом интерфейсе.
- **Взаимная аутентификация TLS.** Объявление схемы mTLS среди схем безопасности.
- **Новые зависимости.** `google.rpc.Status` и `ErrorInfo`, RFC 8785, RFC 7515, руководства по проектированию API Google и ISO 8601.

## Порядок миграции

Оригинал советует мигрировать поэтапно.

1. **Слой совместимости.** Научитесь разбирать оба шаблона различения типов (старый и новый), определять версию протокола и поддерживать обе структуры Agent Card на время перехода.
2. **Двойная поддержка.** Переведите все API на выдачу формата 1.0, оставив читателей для 0.3.0. Добавьте обработку заголовка `A2A-Version` и курсорную пагинацию рядом со старой постраничной.
3. **Только 1.0.** Уберите код совместимости с 0.3.0: старый разбор различителей, постраничную выдачу и поддержку двух форматов.

### Стратегия обратной совместимости

Каждый интерфейс (`AgentInterface`) объявляет собственную версию протокола. Агент может поддерживать несколько версий одновременно, открыв несколько интерфейсов. Клиент выбирает подходящий интерфейс из Agent Card, а SDK могут поддерживать несколько версий протокола и постепенно отказываться от старых.

### Что проверить тестами

- работу с данными и формата 0.3.0, и формата 1.0;
- проверку подписи Agent Card;
- курсорную пагинацию в крайних случаях: пустой результат, единственная страница;
- обработку новых типов ошибок;
- проверку требуемых расширений.

> **Заметка переводчика.** Заголовок `A2A-Version` клиент обязан отправлять с каждым запросом, кроме клиентов версии 0.3: если заголовок пуст, агент считает, что запрос версии 0.3. Это основа безопасной поэтапной миграции. Подробнее: [«Протокол»](https://a2adocs.ru/protocol/#versionirovanie).

## Расхождения внутри оригинала

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

- У события `TaskArtifactUpdateEvent` на странице «What's New» есть поле `index`, а в таблице спецификации (раздел 4.2.2) его нет.
- Примеры заголовка `A2A-Version` в разных местах спецификации показывают разные значения.
- Для требований безопасности Agent Card встречаются два названия: `security` и `security_requirements`.


---

# Справочник

Версии спецификации, SDK и нормативные источники

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/reference/). Тип: Справочник. Основа: Официальная документация A2A (https://a2a-protocol.org/latest/sdk/). Версия спецификации 1.0.0, сверено 05.10.2026.

Здесь собраны сведения, к которым удобно возвращаться: какие бывают версии спецификации, где взять SDK и что считается нормативным источником.

## Версии спецификации

Последняя выпущенная версия — 1.0.0. У каждой версии на официальном сайте есть своя копия спецификации.

| Версия | Статус | Спецификация |
| --- | --- | --- |
| 1.0.0 | Последняя выпущенная версия, основа этого сайта | [a2a-protocol.org/v1.0.0/specification](https://a2a-protocol.org/v1.0.0/specification) |
| 0.3.0 | Предыдущая версия | [a2a-protocol.org/v0.3.0/specification](https://a2a-protocol.org/v0.3.0/specification) |
| 0.2.6 | Историческая | [a2a-protocol.org/v0.2.6/specification](https://a2a-protocol.org/v0.2.6/specification) |
| 0.1.0 | Историческая | [a2a-protocol.org/v0.1.0/specification](https://a2a-protocol.org/v0.1.0/specification) |

Изменения между версиями собраны в [примечаниях к релизам](https://github.com/a2aproject/A2A/releases) проекта. Разбор перехода с 0.3 на 1.0: [«Миграция»](https://a2adocs.ru/migration/).

> **Заметка переводчика.** Версия протокола определяется элементами `Major.Minor`, например `1.0`. Номер патча (последняя цифра) на совместимость не влияет. Подробнее: [«Протокол»](https://a2adocs.ru/protocol/#versionirovanie).

## Официальные SDK

Проект поддерживает SDK для шести языков. Какие версии протокола поддерживает конкретная версия SDK, смотрите в документации самого SDK: не все библиотеки обновились до 1.0 одновременно.

| Язык | Пакет или модуль | Репозиторий |
| --- | --- | --- |
| Python | `a2a-sdk` | [a2aproject/a2a-python](https://github.com/a2aproject/a2a-python) |
| JavaScript и TypeScript | `@a2a-js/sdk` | [a2aproject/a2a-js](https://github.com/a2aproject/a2a-js) |
| Java | — | [a2aproject/a2a-java](https://github.com/a2aproject/a2a-java) |
| Go | `github.com/a2aproject/a2a-go` | [a2aproject/a2a-go](https://github.com/a2aproject/a2a-go) |
| C# и .NET | `A2A` | [a2aproject/a2a-dotnet](https://github.com/a2aproject/a2a-dotnet) |
| Rust | `a2a-rs` | [a2aproject/a2a-rs](https://github.com/a2aproject/a2a-rs) |

Кроме SDK, у проекта есть [примеры реализаций](https://github.com/a2aproject/a2a-samples) с интеграциями в популярные агентные фреймворки и официальный консольный клиент [a2a-cli](https://github.com/a2aproject/a2a-cli). Пошаговый учебный пример на Python: [Quickstart](https://a2a-protocol.org/latest/tutorials/python/1-introduction/) из восьми шагов.

## Нормативные источники

| Источник | Что это | Статус |
| --- | --- | --- |
| [Спецификация](https://a2a-protocol.org/latest/specification/) | Человекочитаемый текст протокола. | Нормативная вместе с a2a.proto |
| [a2a.proto](https://a2a-protocol.org/latest/spec/a2a.proto) | Определение всех объектов и сообщений в Protocol Buffers. | Единственное нормативное определение данных |
| [a2a.json](https://a2a-protocol.org/latest/spec/a2a.json) | JSON Schema (2020-12), создаётся из proto при сборке. | Не нормативный |
| [Protocol Definition](https://a2a-protocol.org/latest/definitions/) | Страница с proto и схемой. | Справочная |
| [llms-reference.txt](https://a2a-protocol.org/llms-reference.txt) | Краткая справка для агентов и людей. | Не нормативная |

> **Заметка переводчика.** Когда формулировки в тексте спецификации расходятся, решает a2a.proto. Примеры таких расхождений мы отмечаем на странице [«Миграция»](https://a2adocs.ru/migration/#rashozhdeniya-vnutri-originala).

## Словарь терминов

Русскоязычный словарь терминов A2A (29 терминов с английскими оригиналами и рекомендациями по переводу) ведётся на отдельном сайте: [глоссарий a2aprotocol.ru](https://a2aprotocol.ru/glossary/). Он же доступен в машиночитаемом виде: [glossary.json](https://a2aprotocol.ru/glossary.json). Принципы перевода, принятые на этом сайте, описаны на странице [«О проекте»](https://a2adocs.ru/about/#printsipy-perevoda).

## Прочие материалы оригинальной документации

- [Core Concepts](https://a2a-protocol.org/latest/topics/key-concepts/), [Life of a Task](https://a2a-protocol.org/latest/topics/life-of-a-task/), [Agent Discovery](https://a2a-protocol.org/latest/topics/agent-discovery/)
- [Enterprise Features](https://a2a-protocol.org/latest/topics/enterprise-ready/), [Streaming & Asynchronous Operations](https://a2a-protocol.org/latest/topics/streaming-and-async/), [Multi-Tenancy](https://a2a-protocol.org/latest/topics/multi-tenancy/)
- [Extensions](https://a2a-protocol.org/latest/topics/extensions/), [Custom Protocol Bindings](https://a2a-protocol.org/latest/topics/custom-protocol-bindings/)
- [Roadmap](https://a2a-protocol.org/latest/roadmap/) и [Community](https://a2a-protocol.org/latest/community/)


---

# О проекте

Статус перевода, принципы и лицензия

> Страница сайта A2A Docs — неофициального перевода документации протокола Agent2Agent (https://a2adocs.ru/about/). Тип: Справочник. Версия спецификации 1.0.0, сверено 05.10.2026.

A2A Docs — русскоязычный справочный сайт по протоколу Agent2Agent. Он содержит перевод и пересказ официальной документации, а со временем и авторские разборы. Сайт неофициальный.

## Статус

- Сайт не является официальным ресурсом проекта A2A. Оригинал документации находится на [a2a-protocol.org](https://a2a-protocol.org/latest/).
- Основа перевода — версия спецификации 1.0.0. Дата последней сверки указана в шапке каждой страницы.
- Если перевод и оригинал расходятся, верен оригинал.
- Нормативным определением структур данных считается файл a2a.proto, а не текст сайта.

## Как отмечены страницы

В шапке каждой страницы стоит отметка о том, чем она является.

| Отметка | Что это |
| --- | --- |
| Перевод | Близкий к тексту перевод раздела оригинала. Таблицы и перечни сохранены. |
| Перевод и пересказ | Часть материала переведена близко к тексту, часть пересказана и собрана из нескольких мест оригинала. |
| Авторский разбор | Текст, написанный нами на основе документации. Такие страницы будут отмечены отдельно. |
| Справочник | Сводные сведения со ссылками на источники. |
| Раздел готовится | Страница-заглушка: перевода ещё нет. Такие страницы закрыты от индексации. |

Рядом с отметкой указан раздел оригинала, на котором основана страница.

## Принципы перевода

- **Нормативные слова** в стиле RFC 2119 передаются так: MUST — ДОЛЖЕН, MUST NOT — НЕ ДОЛЖЕН, SHOULD — СЛЕДУЕТ, SHOULD NOT — НЕ СЛЕДУЕТ, MAY — МОЖЕТ. В тексте сайта они выделены заглавными буквами.
- **Имена** полей, методов, ошибок, значений перечислений и заголовков остаются как в оригинале и набираются моноширинным шрифтом.
- **Термины** берутся из [глоссария a2aprotocol.ru](https://a2aprotocol.ru/glossary/) и при первом появлении даются с оригинальным названием: «задача (Task)», «артефакт (Artifact)», «навык (Skill)». Объект Agent Card в заголовках, таблицах и коде пишется по-английски, как в спецификации, а в тексте допустима форма «карточка агента», принятая в глоссарии.
- **Заметки переводчика** на полях отмечают места, где перевод неоднозначен или где внутри оригинала есть расхождения.
- **Примеры кода** берутся из оригинала. Если мы составляем пример сами, это сказано рядом.

## Лицензия и авторство

Документация и спецификация проекта A2A распространяются на условиях лицензии Apache License 2.0 (Copyright The Linux Foundation). Проект A2A передан Linux Foundation компанией Google. Материалы этого сайта — производная работа от оригинальной документации.

- Лицензия: [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
- Оригинальный проект: [github.com/a2aproject/A2A](https://github.com/a2aproject/A2A).
- **Внесённые изменения:** перевод на русский язык; сокращение, пересказ и перегруппировка материала; добавление пояснений и заметок переводчика; оформление.
- Название A2A и знаки принадлежат их правообладателям. Сайт не использует логотипы проекта и не выдаёт себя за официальный.

## Связанный сайт

Справочник [a2aprotocol.ru](https://a2aprotocol.ru/) отвечает на вопросы «что это» и «как называется»: определения, терминология, сравнение с MCP, A2A в коммерции, хронология стандарта. Здесь, на A2A Docs, разбирается устройство протокола: поля, методы, ошибки, миграция. Сайты ведёт один владелец. Определения терминов лучше цитировать по справочнику, а описание полей и операций по этому сайту.

## Сообщить об ошибке

Нашли неточность в переводе или устаревшее место? Напишите на [info@a2adocs.ru](mailto:info@a2adocs.ru). Укажите адрес страницы и фрагмент: так мы быстрее проверим его по оригиналу.

## Кто ведёт сайт

Справочный сайт. Владелец: ООО «САРМАТЕХ», ИНН 4725011864.

## Машиночитаемые версии

Каждая страница сайта доступна и в виде Markdown: добавьте к адресу страницы `index.md` или нажмите «Открыть .md» в шапке страницы. Весь сайт одним файлом: [llms-full.txt](https://a2adocs.ru/llms-full.txt). Список страниц для ИИ-агентов: [llms.txt](https://a2adocs.ru/llms.txt).