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

# Box Agents API over A2A

> Call the Box Agent or a custom AI Studio agent from your own application, or from any external agent that supports the open Agent2Agent (A2A) protocol.

The Box Agents API lets your application or agent hand a task to a Box AI agent. You send a prompt, and optionally the Box files, folders, and hubs to work with. The agent plans and runs the work across that content, then returns an answer and any files it created.

The API uses the open [Agent2Agent (A2A) protocol](https://a2a-protocol.org), so you can call Box agents from your own code, or from any external agent that supports A2A. Agents run with the caller's Box permissions, and can only use content that the authenticated user or service account can already open.

## Capabilities

| Capability | Description | Guide |
| - | - | - |
| **Work across Box content** | Ask questions across files, folders, and hubs in one request. For example, compare payment terms across a set of contracts and flag anything non-standard. | [Send requests](https://developer.box.com/ai/agents-api/send-requests.md) |
| **Call the Box Agent or a custom agent** | Send requests to the Box Agent at `https://api.box.com/a2a`, or to a custom agent your organization built in Box AI Studio at `https://api.box.com/a2a/{agent_id}`. | [Choose an agent](https://developer.box.com/ai/agents-api/agents.md) |
| **Discover agents with Agent Cards** | Read an agent's public Agent Card, without a token, to find its endpoints, authentication, and capabilities. | [Agent Cards](https://developer.box.com/ai/agents-api/agents.md#agent-cards) |
| **Hold multi-turn conversations** | Send follow-up messages in the same session to continue a conversation. | [Continue a conversation](https://developer.box.com/ai/agents-api/sessions.md#continue-a-conversation) |
| **Get structured citations and search results** | Receive the items cited in the answer, and the items a search step found, as structured data instead of text. | [Citations and search results](https://developer.box.com/ai/agents-api/responses.md#citations-and-search-results) |
| **Create files in Box** | Let the agent save its output, such as a Box Note with a summary, in a folder you choose. | [Files the agent creates](https://developer.box.com/ai/agents-api/responses.md#files-the-agent-creates) |
| **Stream responses** | Receive status updates and the answer as server-sent events while the agent works. | [Stream the response](https://developer.box.com/ai/agents-api/responses.md#stream-the-response) |

## How it works

Box implements A2A v1.0 over two protocol bindings:

* HTTP+JSON (REST), the preferred binding
* JSON-RPC 2.0

Because Box follows the A2A standard, any A2A client library works with the Agents API. These guides cover the Box-specific parts you need: [authentication](https://developer.box.com/ai/agents-api/authentication.md), [choosing an agent](https://developer.box.com/ai/agents-api/agents.md), [referencing Box content](https://developer.box.com/ai/agents-api/send-requests.md), [sessions](https://developer.box.com/ai/agents-api/sessions.md), [reading responses](https://developer.box.com/ai/agents-api/responses.md), and [handling errors](https://developer.box.com/ai/agents-api/errors.md). For the protocol itself, see the [A2A specification](https://a2a-protocol.org/latest/specification).

## Prerequisites

Before you call the Agents API, make sure you have:

* A [free Box developer account](https://account.box.com/signup/developer), or a Box enterprise with **Box AI** enabled in the Admin Console
* **AI via API/MCP/A2A/CLI** enabled for the enterprise in the Admin Console
* A platform app with the **Manage AI** scope
* Box AI Studio enabled, if you plan to call custom agents. Box AI Studio is an Enterprise Advanced feature.

## Set up a platform app

1. [Create a platform app](https://developer.box.com/guides/applications/index.md). Select **User** for OAuth 2.0, or **Server** for JWT or Client Credentials Grant.
2. Configure authentication with [OAuth 2.0](https://developer.box.com/guides/authentication/oauth2/oauth2-setup.md), [JWT](https://developer.box.com/guides/authentication/jwt/jwt-setup.md), or [Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup.md).
3. In the [Developer Console](https://app.box.com/developers/console), open your app and go to **Configuration** > **Required Access Scopes** > **Content Actions**.
4. Select these scopes:
   * **Manage AI** (`ai.readwrite`). Required to call agents and manage sessions.
   * **Read all files and folders stored in Box** (`root_readonly`). Recommended, so the agent can read the files, folders, and hubs you reference.
   * **Write all files and folders stored in Box** (`root_readwrite`). Recommended, so the agent can create files, such as a Box Note with a summary.
5. Save your changes and submit the app for authorization.

> [!WARNING]
>
> If you add **Manage AI** to an app that's already authorized, [reauthorize the app](https://developer.box.com/guides/authorization/platform-app-approval.md) before the scope takes effect.

> [!NOTE]
>
> If **Manage AI** does not display in your app's scope list, have your Box admin enable **AI via API/MCP/A2A/CLI** for the enterprise in the Admin Console.

Reading an agent's public Agent Card doesn't require a token or scope. For a full walkthrough of enabling the AI scope, see [Box AI API prerequisites](https://developer.box.com/guides/box-ai/ai-tutorials/prerequisites.md). For more on scopes, see [Scopes](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes.md).

For quick experiments, generate a [developer token](https://developer.box.com/guides/authentication/tokens/developer-tokens.md). Developer tokens are for development and testing only, and expire after 60 minutes. For production, get an access token with one of the flows in [Authentication](https://developer.box.com/ai/agents-api/authentication.md).

## Send your first request

Get an access token as described in [Authentication](https://developer.box.com/ai/agents-api/authentication.md), then send a message to the Box Agent. The JavaScript examples in these guides use the [A2A JavaScript SDK](https://github.com/a2aproject/a2a-js), and the `client` and `auth` objects this example creates.

```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": "What is Box AI?", "mediaType": "text/plain" }]
    }
  }'
```

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

// Reads the public Agent Card and connects over HTTP+JSON.
const client = await new ClientFactory().createFromUrl('https://api.box.com/a2a/');
const auth = { serviceParameters: { Authorization: `Bearer ${accessToken}` } };

const task = await client.sendMessage(
  SendMessageRequest.fromJSON({
    message: {
      messageId: crypto.randomUUID(),
      role: 'ROLE_USER',
      parts: [{ text: 'What is Box AI?' }],
    },
  }),
  auth
);

// The answer is in the task's "response" artifact.
console.log(task.artifacts);
```

Each message needs a `messageId` that you generate, a `role`, and `parts` that hold the prompt. Messages you send always use `ROLE_USER`. Messages from the agent, such as those in a task's history, use `ROLE_AGENT`. For all request fields, see [Send requests](https://developer.box.com/ai/agents-api/send-requests.md).

## Next steps

After your first request, you can point the agent at your own Box content, call a custom agent, and continue the conversation:

* [Reference Box content](https://developer.box.com/ai/agents-api/send-requests.md#reference-box-content). Attach files, folders, and hubs for the agent to work with.
* [Call a custom agent](https://developer.box.com/ai/agents-api/agents.md). Send the same request to an agent your organization built in Box AI Studio.
* [Continue a conversation](https://developer.box.com/ai/agents-api/sessions.md#continue-a-conversation). Send follow-up messages in the same session.

When you're ready to build on the results, [read and stream responses](https://developer.box.com/ai/agents-api/responses.md) to get citations, search results, and created files as structured data, and [handle errors](https://developer.box.com/ai/agents-api/errors.md) when a request or task fails.

**RELATED GUIDES**
