The unnamed base URL is an alias. A request to
https://api.box.com/a2a/message:send is handled exactly like a request to https://api.box.com/a2a/box-default-agent/message:send. Every operation is available under all three base URLs.
box-default-agent is a stable name. The model behind the Box Agent can change without any change on your side.
To call a custom agent, first create it in AI Studio. Then get the agent ID, which you use as {agent_id} in every custom agent path, including the Agent Card URLs. In the Admin Console, go to Box AI > AI Studio and open the agent in the builder. Select the External Discoverability tab, then copy the Agent ID or the Agent Card.
Operations
All paths are relative to the base URL you chose.
JSON-RPC requests all use
POST on the base URL itself and select the operation with the method field.
Protocol version
SendA2A-Version: 1.0 on every request.
- HTTP+JSON requests without the header are treated as version 1.0.
- JSON-RPC requests require the header. Without it, the request fails with
VersionNotSupportedError(-32009).
Agent Cards
An Agent Card is the standard A2A discovery document. Every agent has a public card that doesn’t require credentials, so an A2A client can discover Box before it has a token. Custom agents also have an extended card, which requires a token and includes the agent’s own name, description, and icon.
The JavaScript examples on this page use the
client and auth objects from Send your first request.
Get a public card:
capabilities.extendedAgentCard: true. Box returns a public card for any ID, so a public card doesn’t confirm that a custom agent exists.
For extended cards:
- A request without a valid token returns
401. - A request for an agent that doesn’t exist, or that the caller can’t access, returns
404. - The Box Agent has no extended card. A request for one fails with
ExtendedAgentCardNotConfiguredError.
securityRequirements describes what you need to call the agent, not what you need to read the card. A custom agent’s public card has the same structure, with interface URLs that use the agent’s ID.
