Skip to main content
When you send a message to an agent, the result comes back as a task. The task reports the agent’s status, holds the answer and any structured output as artifacts, and records the messages exchanged. 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:
When you use the config extension, Box returns each kind of structured output as its own artifact:
Identify structured output by its media type, not by the artifact name or position.

Task states

Citations and search results

Every item reference in these artifacts uses the same id 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.
The following response has both turned on:
To separate the answer from its references, filter by media type:
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 with outputDestination. With the config extension turned on, the response includes a produced-items artifact that lists those files. Without it, the answer text names them.
Creating files requires the 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.
Each 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, SubscribeToTask returns UnsupportedOperationError, so poll GET /tasks/{taskId} instead.
  • The task you read with GET /tasks/{taskId} after it stops is complete, even if you missed stream events.
Last modified on November 17, 2026