Skip to main content
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, 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

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, choosing an agent, referencing Box content, sessions, reading responses, and handling errors. For the protocol itself, see the A2A specification.

Prerequisites

Before you call the Agents API, make sure you have:
  • A free Box developer account, 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. Select User for OAuth 2.0, or Server for JWT or Client Credentials Grant.
  2. Configure authentication with OAuth 2.0, JWT, or Client Credentials Grant.
  3. In the Developer 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.
If you add Manage AI to an app that’s already authorized, reauthorize the app before the scope takes effect.
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. For more on scopes, see Scopes. For quick experiments, generate a developer token. 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.

Send your first request

Get an access token as described in Authentication, then send a message to the Box Agent. The JavaScript examples in these guides use the A2A JavaScript SDK, and the client and auth objects this example creates.
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.

Next steps

After your first request, you can point the agent at your own Box content, call a custom agent, and continue the conversation: When you’re ready to build on the results, read and stream responses to get citations, search results, and created files as structured data, and handle errors when a request or task fails.
Last modified on November 17, 2026