# Сообщение и часть (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).