> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read and stream responses

> Read Box Agents API task responses, task states, citations, search results, and created files, and stream responses with server-sent events.

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](https://developer.box.com/ai/agents-api/sessions.md#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`:

```json theme={null}
{
  "task": {
    "id": "3706d316-0832-421d-9ce6-5aa645598ce9",
    "contextId": "410109491801",
    "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2022-01-01T00:00:00Z" },
    "artifacts": [
      {
        "artifactId": "77ffd0f5-7d7c-4908-8dd8-06ca288f4fb9",
        "name": "response",
        "parts": [{ "text": "The three contracts use net-30 payment terms, ..." }]
      }
    ],
    "history": [
      {
        "messageId": "m-1",
        "contextId": "410109491801",
        "taskId": "3706d316-0832-421d-9ce6-5aa645598ce9",
        "role": "ROLE_USER",
        "parts": [{ "text": "Compare the terms across these contracts." }]
      },
      {
        "messageId": "m-2",
        "contextId": "410109491801",
        "taskId": "3706d316-0832-421d-9ce6-5aa645598ce9",
        "role": "ROLE_AGENT",
        "parts": [{ "text": "The three contracts use net-30 payment terms, ..." }]
      }
    ]
  }
}
```

When you use the [config extension](https://developer.box.com/ai/agents-api/send-requests.md#configure-the-response), Box returns each kind of structured output as its own artifact:

| Artifact name | Media type | Included when |
| - | - | - |
| `response` | None (text) | Always |
| `inline-citations` | `application/vnd.box.inline-citations+json` | `inlineCitations` is `true` and the answer cites items inline |
| `search-results` | `application/vnd.box.search-results+json` | `searchResults` is `true` and a search step ran |
| `produced-items` | `application/vnd.box.output-item+json` | The agent created files |

> [!TIP]
>
> Identify structured output by its media type, not by the artifact name or position.

## Task states

| State | Meaning |
| - | - |
| `TASK_STATE_SUBMITTED` | Accepted but not yet running |
| `TASK_STATE_WORKING` | The agent is running |
| `TASK_STATE_COMPLETED` | Finished successfully |
| `TASK_STATE_FAILED` | Finished with a failure. The status message includes the reason. See [Failed tasks](https://developer.box.com/ai/agents-api/errors.md#failed-tasks). |
| `TASK_STATE_REJECTED` | Refused before the agent ran, for example because the caller can't access content the request references. See [Rejected tasks](https://developer.box.com/ai/agents-api/errors.md#rejected-tasks). |

## 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:

| Key | Value |
| - | - |
| `id` | The Box item ID |
| `type` | `file`, `folder`, or `hubs` |
| `name` | The item name |
| `sharedLink` | The shared link URL, included when the item was reached through one |

* **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:

```json theme={null}
{
  "task": {
    "id": "3706d316-0832-421d-9ce6-5aa645598ce9",
    "contextId": "410109491801",
    "status": { "state": "TASK_STATE_COMPLETED" },
    "metadata": {
      "https://api.box.com/a2a/extensions/config/v1": {
        "inlineCitations": true,
        "searchResults": true,
        "outputDestination": null
      }
    },
    "artifacts": [
      {
        "artifactId": "77ffd0f5-7d7c-4908-8dd8-06ca288f4fb9",
        "name": "response",
        "parts": [
          { "text": "All three reseller agreements use net-30 payment terms, except the Vendor A contract (Reseller Agreement - Vendor A.txt), which specifies net-45." }
        ]
      },
      {
        "artifactId": "f7b3d0e2-8c4a-4b19-a258-2e9f1b8c3d75",
        "name": "inline-citations",
        "extensions": ["https://api.box.com/a2a/extensions/config/v1"],
        "parts": [
          {
            "data": {
              "inlineCitations": [
                { "id": "15728655283", "type": "file", "name": "Reseller Agreement - Vendor A.txt" }
              ]
            },
            "mediaType": "application/vnd.box.inline-citations+json"
          }
        ]
      },
      {
        "artifactId": "b93d5f10-8a62-4c77-b105-9e2f4a8c6d51",
        "name": "search-results",
        "extensions": ["https://api.box.com/a2a/extensions/config/v1"],
        "parts": [
          {
            "data": {
              "results": [
                { "id": "15728655283", "type": "file", "name": "Reseller Agreement - Vendor A.txt" },
                { "id": "13835268094", "type": "folder", "name": "Contracts 2025" }
              ]
            },
            "mediaType": "application/vnd.box.search-results+json"
          }
        ]
      }
    ]
  }
}
```

To separate the answer from its references, filter by media type:

```bash cURL theme={null}
echo "$RESPONSE" | jq -r '.task.artifacts[].parts[] | select(.text) | .text'
echo "$RESPONSE" | jq '.task.artifacts[].parts[] | select(.mediaType == "application/vnd.box.search-results+json") | .data.results'
```

## 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.

```json theme={null}
{
  "artifactId": "c04a7e93-1b58-4d26-aa3f-7c81b6e05f42",
  "name": "produced-items",
  "extensions": ["https://api.box.com/a2a/extensions/config/v1"],
  "parts": [
    {
      "data": {
        "items": [
          { "id": "310488204711", "type": "file", "name": "Q3 Pipeline Summary.boxnote" }
        ]
      },
      "mediaType": "application/vnd.box.output-item+json"
    }
  ]
}
```

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](https://developer.box.com/ai/agents-api/index.md#send-your-first-request).

```bash cURL theme={null}
curl -sS -N -X POST "https://api.box.com/a2a/message:stream" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": {
      "messageId": "'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "parts": [
        { "text": "Summarize this contract." },
        {
          "data": { "id": "1728901234567", "type": "file" },
          "mediaType": "application/vnd.box.source-reference+json"
        }
      ]
    }
  }'
```

```javascript JavaScript theme={null}
import { taskStateToJSON } from '@a2a-js/sdk';

const SOURCE_REF = 'application/vnd.box.source-reference+json';

const stream = client.sendMessageStream(
  SendMessageRequest.fromJSON({
    message: {
      messageId: crypto.randomUUID(),
      role: 'ROLE_USER',
      parts: [
        { text: 'Summarize this contract.' },
        { data: { id: '1728901234567', type: 'file' }, mediaType: SOURCE_REF },
      ],
    },
  }),
  auth
);

for await (const event of stream) {
  switch (event.payload?.$case) {
    case 'task':
      console.log('submitted', event.payload.value.id);
      break;
    case 'statusUpdate':
      console.log('status', taskStateToJSON(event.payload.value.status.state));
      break;
    case 'artifactUpdate':
      for (const part of event.payload.value.artifact?.parts ?? []) {
        if (part.content?.$case === 'text') process.stdout.write(part.content.value);
      }
      break;
  }
}
```

Each `data:` line in the stream holds one JSON event:

```text theme={null}
data: {"task": {"id": "478314f7-...", "contextId": "410109491801", "status": {"state": "TASK_STATE_SUBMITTED"}, "history": [ ... ]}}
data: {"statusUpdate": {"taskId": "478314f7-...", "contextId": "410109491801", "status": {"state": "TASK_STATE_WORKING", "timestamp": "2022-01-01T00:00:00Z"}}}
data: {"artifactUpdate": {"taskId": "478314f7-...", "contextId": "410109491801", "artifact": {"artifactId": "c15f5542-...", "name": "response", "parts": [{"text": "The contract runs ..."}]}, "lastChunk": true}}
data: {"statusUpdate": {"taskId": "478314f7-...", "contextId": "410109491801", "status": {"state": "TASK_STATE_COMPLETED", "timestamp": "2022-01-01T00:00:00Z"}}}
```

| Event | Payload |
| - | - |
| `task` | The first event. The full task in `TASK_STATE_SUBMITTED`, with your message in `history`. |
| `statusUpdate` | Sent for `TASK_STATE_WORKING` and for the state the task stops in |
| `artifactUpdate` | The `response` artifact and any structured artifacts you requested. `lastChunk: true` marks the end of an artifact. |

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}`](https://developer.box.com/ai/agents-api/sessions#get-a-task).
* 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.

**RELATED GUIDES**
