Skip to main content
Every task you give a Box agent starts with a message. A message carries your prompt as text, and can also reference the Box files, folders, and hubs you want the agent to work with. Send it to message:send to get the finished task, or to message:stream to receive updates while the agent works. Both operations take the same request body. This page covers the request body, how to reference Box content, and how to control the response with the Box config extension. For a minimal working request, see Send your first request.

Request body

The request body is an A2A SendMessageRequest:
Box reads these fields from each part:

Reference Box content

Attach each Box item as its own data part with the media type application/vnd.box.source-reference+json:
Follow these rules when you build parts:
  • Include at least one text part. A request that contains only data parts is rejected.
  • Include both id and type in every content reference, and use a supported type. Otherwise, the request fails with InvalidParamsError.
  • Set the source-reference media type on every content reference. Box ignores data parts with any other media type.
  • Use data parts for Box content. Box doesn’t treat A2A file parts that carry url or filename as Box content references.

Example: prompt with a file, folder, and hub

The JavaScript examples on this page use the client and auth objects from Send your first request.
To call a custom agent instead, change only the URL. For example: https://api.box.com/a2a/$AGENT_ID/message:send.

Configure the response

By default, the response is plain text. Citations, search results, and the names of any files the agent creates are part of the answer text, and the agent saves created files in the session’s own folder. To get these as structured data, or to save files in a folder you choose, use the Box config extension: https://api.box.com/a2a/extensions/config/v1. To use the extension:
  1. Send the A2A-Extensions header with the extension URI. The header turns the extension on.
  2. List the URI in message.extensions.
  3. Add your settings to message.metadata, keyed by the extension URI.
How Box applies settings:
  • Without the A2A-Extensions header, Box ignores the settings in metadata and uses the defaults.
  • Omitted keys use their defaults.
  • Unknown keys are ignored.
  • Invalid values, such as a string where a Boolean is expected, fail with InvalidParamsError before the agent runs.
To read the structured artifacts these settings return, see Read the response.
Last modified on November 17, 2026