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

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

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"
}

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

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

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

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

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

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

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