Capabilities
How it works
Box implements A2A v1.0 over two protocol bindings:- HTTP+JSON (REST), the preferred binding
- JSON-RPC 2.0
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
- Create a platform app. Select User for OAuth 2.0, or Server for JWT or Client Credentials Grant.
- Configure authentication with OAuth 2.0, JWT, or Client Credentials Grant.
- In the Developer Console, open your app and go to Configuration > Required Access Scopes > Content Actions.
- 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.
- Manage AI (
- Save your changes and submit the app for authorization.
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.
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 theclient and auth objects this example creates.
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:- Reference Box content. Attach files, folders, and hubs for the agent to work with.
- Call a custom agent. Send the same request to an agent your organization built in Box AI Studio.
- Continue a conversation. Send follow-up messages in the same session.
