Skip to main content
The Agents API has a single API surface, and the URL path selects the agent. 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

Send A2A-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:
Get a custom agent’s extended card:
A custom agent’s public card is generic. It identifies the agent only by its ID, uses the default description and icon, and declares 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.
The Box Agent’s public card:
The card lists HTTP+JSON first, so A2A clients use it by default. 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.
Last modified on November 17, 2026