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 A2ASendMessageRequest:
Box reads these fields from each part:
Reference Box content
Attach each Box item as its owndata 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
dataparts is rejected. - Include both
idandtypein every content reference, and use a supportedtype. Otherwise, the request fails withInvalidParamsError. - Set the source-reference media type on every content reference. Box ignores
dataparts with any other media type. - Use
dataparts for Box content. Box doesn’t treat A2A file parts that carryurlorfilenameas Box content references.
Example: prompt with a file, folder, and hub
The JavaScript examples on this page use theclient and auth objects from Send your first request.
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:
- Send the
A2A-Extensionsheader with the extension URI. The header turns the extension on. - List the URI in
message.extensions. - Add your settings to
message.metadata, keyed by the extension URI.
- Without the
A2A-Extensionsheader, Box ignores the settings inmetadataand 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
InvalidParamsErrorbefore the agent runs.
