message:send returns the finished task, and message:stream sends updates while the agent works. To read a stored task later, see Get a task.
This page covers the task response, task states, citations and search results, files the agent creates, and streaming.
Task response
message:send always returns a task, never a standalone message. The answer is in the artifact named response:
Task states
Citations and search results
Every item reference in these artifacts uses the sameid and type keys as content references in requests, plus the item’s name:
- Inline citations are the items cited within the answer text.
- Search results are the items a search step found, in ranked order.
cURL
Files the agent creates
The agent can create files as part of its work, such as a Box Note with a summary. Created files are saved in the session’s own folder, or in the folder you set withoutputDestination. With the config extension turned on, the response includes a produced-items artifact that lists those files. Without it, the answer text names them.
root_readwrite scope. To save files in a folder you choose with outputDestination, the caller also needs write access to that folder.
Stream the response
message:stream takes the same request body as message:send and returns server-sent events (Content-Type: text/event-stream). With cURL, send Accept: text/event-stream and use -N to turn off output buffering. The SDK exposes streaming as sendMessageStream, which parses the events for you.
The JavaScript example uses the client and auth objects from Send your first request.
data: line in the stream holds one JSON event:
The server closes the connection after a
statusUpdate reports a terminal state, which also ends the SDK’s loop.
- You can open only one stream per task. Box refuses a second stream for the same task.
- Disconnecting doesn’t stop the task. The agent runs to completion and saves its output, which you can read with
GET /tasks/{taskId}. - Reattaching to a running task’s stream is coming later. Until then,
SubscribeToTaskreturnsUnsupportedOperationError, so pollGET /tasks/{taskId}instead. - The task you read with
GET /tasks/{taskId}after it stops is complete, even if you missed stream events.
