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

# Choose an agent

> Select the Box Agent or a custom AI Studio agent by URL, find the supported A2A operations, and read Agent Cards.

The Agents API has a single API surface, and the URL path selects the agent.

| Agent | Base URL |
| - | - |
| Box Agent (default) | `https://api.box.com/a2a` |
| Box Agent, named explicitly | `https://api.box.com/a2a/box-default-agent` |
| Custom agent | `https://api.box.com/a2a/{agent_id}` |

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](https://developer.box.com/guides/ai-studio/getting-started-ai-studio.md). 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.

| Operation | HTTP+JSON | JSON-RPC method |
| - | - | - |
| Send a message | `POST /message:send` | `SendMessage` |
| Stream a message | `POST /message:stream` | `SendStreamingMessage` |
| Get a task | `GET /tasks/{taskId}` | `GetTask` |

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.

| Card | Path | Token required |
| - | - | - |
| Box Agent | `https://api.box.com/a2a/box-default-agent/.well-known/agent-card.json` | No |
| Box Agent, unnamed | `https://api.box.com/a2a/.well-known/agent-card.json` | No |
| Custom agent, public | `https://api.box.com/a2a/{agent_id}/.well-known/agent-card.json` | No |
| Custom agent, extended | `https://api.box.com/a2a/{agent_id}/extendedAgentCard` | Yes |

The JavaScript examples on this page use the `client` and `auth` objects from [Send your first request](https://developer.box.com/ai/agents-api/index.md#send-your-first-request).

Get a public card:

```bash cURL theme={null}
curl -sS "https://api.box.com/a2a/.well-known/agent-card.json" | jq
```

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

const card = await new DefaultAgentCardResolver().resolve('https://api.box.com/a2a/');
console.log(card.supportedInterfaces);
```

Get a custom agent's extended card:

```bash cURL theme={null}
curl -sS "https://api.box.com/a2a/$AGENT_ID/extendedAgentCard" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "A2A-Version: 1.0" | jq
```

```javascript JavaScript theme={null}
// The client upgrades to the extended card because the public card
// declares extendedAgentCard: true.
const card = await client.getAgentCard(auth);
```

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:

```json theme={null}
{
  "name": "Box Agent",
  "description": "Answers questions and acts on Box content using Box AI.",
  "version": "1.0.0",
  "iconUrl": "https://cdn01.boxcdn.net/_assets/img/favicons/favicon.svg",
  "supportedInterfaces": [
    { "url": "https://api.box.com/a2a/box-default-agent", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" },
    { "url": "https://api.box.com/a2a/box-default-agent", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "securitySchemes": {
    "box_oauth2": {
      "oauth2SecurityScheme": {
        "description": "Box OAuth 2.0 authorization-code flow",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://account.box.com/api/oauth2/authorize",
            "tokenUrl": "https://api.box.com/oauth2/token",
            "refreshUrl": "https://api.box.com/oauth2/token"
          }
        }
      }
    }
  },
  "securityRequirements": [{ "schemes": { "box_oauth2": { "list": ["ai.readwrite"] } } }],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false,
    "extensions": [
      {
        "uri": "https://api.box.com/a2a/extensions/config/v1",
        "required": false,
        "description": "Configure how the agent executes and shapes its response.",
        "params": {
          "inlineCitations": { "type": "boolean", "default": false },
          "searchResults": { "type": "boolean", "default": false },
          "outputDestination": { "type": "object", "default": null }
        }
      }
    ]
  },
  "defaultInputModes": ["text/plain", "application/vnd.box.source-reference+json"],
  "defaultOutputModes": [
    "text/plain",
    "application/vnd.box.execution-error+json",
    "application/vnd.box.inline-citations+json",
    "application/vnd.box.search-results+json"
  ],
  "skills": [
    {
      "id": "find-content",
      "name": "Find the right content in Box",
      "description": "Locate the files, folders, or Hubs you're looking for across the content you can access in Box.",
      "examples": [
        "Find my Q4 sales report in Box.",
        "Locate the latest signed MSA for Acme Corp.",
        "Which folder has our onboarding materials?"
      ],
      "tags": ["find", "search", "discovery", "content", "files", "folders", "hubs"]
    },
    {
      "id": "content-qa",
      "name": "Answer questions about your content",
      "description": "Answer questions grounded in Box content, with citations - either from sources you provide, or by searching the content you can access when no sources are given.",
      "examples": [
        "What are the payment terms in this contract?",
        "Explain our latest security policy.",
        "Which of these files mention the Q3 renewal date?"
      ],
      "tags": ["q&a", "answer", "content", "documents", "hubs", "citations"]
    },
    {
      "id": "analyze-summarize",
      "name": "Analyze and summarize across documents",
      "description": "Analyze and summarize across your documents, combining information from multiple sources into a single answer, grounded in Box content with citations.",
      "examples": [
        "Summarize this report.",
        "Compare the pricing across these three vendor proposals.",
        "Summarize the key risks mentioned across these documents."
      ],
      "tags": ["summary", "analysis", "research", "multi-document"]
    },
    {
      "id": "content-creation",
      "name": "Create documents and Box Notes",
      "description": "Create new text-based documents and Box Notes grounded in your Box content, and save them back to Box.",
      "examples": [
        "Create a Box Note outlining a proposal based on these files.",
        "Draft a summary document of the decisions in these files and save it to Box."
      ],
      "tags": ["create", "draft", "documents", "box notes", "writing"]
    }
  ]
}
```

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.

**RELATED GUIDES**
