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

# Send requests to an agent

> Build Box Agents API requests, reference Box files, folders, and hubs, and configure citations, search results, and output folders.

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

## Request body

The request body is an A2A `SendMessageRequest`:

```json theme={null}
{
  "message": {
    "messageId": "9f2b6c1e-4d3a-4b8e-a1f0-7c5d2e9b3a61",
    "role": "ROLE_USER",
    "parts": [
      { "text": "Summarize this contract.", "mediaType": "text/plain" },
      {
        "data": { "id": "1728901234567", "type": "file" },
        "mediaType": "application/vnd.box.source-reference+json"
      }
    ],
    "contextId": "410109491801",
    "extensions": ["https://api.box.com/a2a/extensions/config/v1"],
    "metadata": {
      "https://api.box.com/a2a/extensions/config/v1": { "inlineCitations": true }
    }
  },
  "configuration": {
    "returnImmediately": false
  }
}
```

| Field | Required | Description |
| - | - | - |
| `message.messageId` | Yes | A client-generated ID, unique for each message |
| `message.role` | Yes | Always `ROLE_USER`. Messages from the agent, such as those in a task's history, use `ROLE_AGENT`. |
| `message.parts` | Yes | The message content. Include at least one text part. |
| `message.contextId` | No | The session ID. Omit it on the first message. See [Continue a conversation](https://developer.box.com/ai/agents-api/sessions.md#continue-a-conversation). |
| `message.extensions` | No | The extensions this message uses. See [Configure the response](#configure-the-response). |
| `message.metadata` | No | Extension settings, keyed by extension URI |
| `configuration.returnImmediately` | No | Defaults to `false`, which waits for the task to finish |

Box reads these fields from each part:

| Field | Purpose |
| - | - |
| `text` | The prompt text. You can pair it with `mediaType: "text/plain"`. |
| `data` and `mediaType` | A Box content reference |

## Reference Box content

Attach each Box item as its own `data` part with the media type `application/vnd.box.source-reference+json`:

```json theme={null}
{
  "data": { "id": "1728901234567", "type": "file" },
  "mediaType": "application/vnd.box.source-reference+json"
}
```

| Key | Required | Value |
| - | - | - |
| `id` | Yes | The Box item ID, as a string |
| `type` | Yes | `file`, `folder`, or `hubs` |
| `sharedLink` | No | The shared link URL, for items reached through a shared link |

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

```bash cURL theme={null}
curl -sS -X POST "https://api.box.com/a2a/message:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "Compare the payment terms across these contracts and flag anything non-standard.",
          "mediaType": "text/plain"
        },
        {
          "data": { "id": "1728901234567", "type": "file" },
          "mediaType": "application/vnd.box.source-reference+json"
        },
        {
          "data": { "id": "298374651", "type": "folder" },
          "mediaType": "application/vnd.box.source-reference+json"
        },
        {
          "data": { "id": "77112233", "type": "hubs" },
          "mediaType": "application/vnd.box.source-reference+json"
        }
      ]
    }
  }'
```

```javascript JavaScript theme={null}
const SOURCE_REF = 'application/vnd.box.source-reference+json';

const task = await client.sendMessage(
  SendMessageRequest.fromJSON({
    message: {
      messageId: crypto.randomUUID(),
      role: 'ROLE_USER',
      parts: [
        {
          text: 'Compare the payment terms across these contracts and flag anything non-standard.',
          mediaType: 'text/plain',
        },
        { data: { id: '1728901234567', type: 'file' }, mediaType: SOURCE_REF },
        { data: { id: '298374651', type: 'folder' }, mediaType: SOURCE_REF },
        { data: { id: '77112233', type: 'hubs' }, mediaType: SOURCE_REF },
      ],
    },
  }),
  auth
);
```

```bash JSON-RPC theme={null}
curl -sS -X POST "https://api.box.com/a2a" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "m-1",
        "role": "ROLE_USER",
        "parts": [
          { "text": "Summarize this contract." },
          {
            "data": { "id": "1728901234567", "type": "file" },
            "mediaType": "application/vnd.box.source-reference+json"
          }
        ]
      }
    }
  }'
```

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.

| Key | Type | Default | Behavior |
| - | - | - | - |
| `inlineCitations` | Boolean | `false` | When `true`, returns the items cited inline as a separate `inline-citations` artifact. The answer text doesn't change. |
| `searchResults` | Boolean | `false` | When `true`, returns the items a search step found as a separate `search-results` artifact instead of listing them in the text. |
| `outputDestination` | Object, `{ "id": "string", "type": "folder" }` | `null` | Sets the folder where the agent saves the files it creates. When `null`, files go in the session's own folder. The caller must have write access to the folder you set. |

```bash cURL theme={null}
curl -sS -X POST "https://api.box.com/a2a/message:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" \
  -H "A2A-Extensions: https://api.box.com/a2a/extensions/config/v1" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "extensions": ["https://api.box.com/a2a/extensions/config/v1"],
      "parts": [
        { "text": "Summarize the Q3 pipeline and save the summary as a note." },
        {
          "data": { "id": "2388350166142", "type": "file" },
          "mediaType": "application/vnd.box.source-reference+json"
        }
      ],
      "metadata": {
        "https://api.box.com/a2a/extensions/config/v1": {
          "inlineCitations": true,
          "searchResults": true,
          "outputDestination": { "id": "310477298844", "type": "folder" }
        }
      }
    }
  }'
```

```javascript JavaScript theme={null}
const SOURCE_REF = 'application/vnd.box.source-reference+json';
const CONFIG_EXT = 'https://api.box.com/a2a/extensions/config/v1';

const task = await client.sendMessage(
  SendMessageRequest.fromJSON({
    message: {
      messageId: crypto.randomUUID(),
      role: 'ROLE_USER',
      extensions: [CONFIG_EXT],
      parts: [
        { text: 'Summarize the Q3 pipeline and save the summary as a note.' },
        { data: { id: '2388350166142', type: 'file' }, mediaType: SOURCE_REF },
      ],
      metadata: {
        [CONFIG_EXT]: {
          inlineCitations: true,
          searchResults: true,
          outputDestination: { id: '310477298844', type: 'folder' },
        },
      },
    },
  }),
  { serviceParameters: { Authorization: `Bearer ${accessToken}`, 'A2A-Extensions': CONFIG_EXT } }
);
```

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

**RELATED GUIDES**
