Manuals / A2A 101 / Part 2 · AgentCard
2.2

Discovery and supportedInterfaces

The spec standardizes only the well-known path to a card, and a client takes the first supportedInterfaces entry it speaks before it checks a capability flag.

The planner starts with three ports in its configuration: 41241, 41242, and 41243. Before it delegates any work, it fetches three cards, picks one interface from each, and records which agents stream and which one wants a token.

When you finish this section, you can locate an agent's card, pick the interface to call, and avoid the calls its card rules out.

Three routes to a card

The spec names three ways to reach a card, and it standardizes the details of only one:

  • Well-known URI. The client fetches https://{server_domain}/.well-known/agent-card.json from a host it already knows. The project recommends this route for public agents.
  • Registry or catalog. The client queries a curated catalog of agents, and the current specification sets no standard API for such a registry.
  • Direct configuration. The client starts from Agent Card URLs or card content that it already has, kept in code, a configuration file, or an environment variable.

The planner's ports come from direct configuration in the kit's run script, and each card from the well-known path.

discovery is one GET on the well-known pathhttpFull log
### 1 · discover test-runner
GET /.well-known/agent-card.json HTTP/1.1
Host: localhost:41241
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "test-runner",
…
}
The response body is cut after its first field. Figure 2.1 draws the whole card.

Use the path exactly as the spec writes it. One diagram in the project's guides still shows /.well-known/agent-card with no .json, and POST /sendMessage where 1.0 has POST /message:send (conflict D32). PR #2261 fixed the diagram on main after v1.0.1, not yet released.

Figure 2.2 follows the planner from its configuration to a checked call on code-reviewer.

Fig. 2.2from a host to a checked callflow
From a host to a checked call Three stages, top to bottom, drawn step by step. First, the planner finds the code-reviewer card: direct configuration gives it the host, and a GET of /.well-known/agent-card.json returns the card, while a registry is a third route the kit does not use. Second, the planner takes interface 0, JSON-RPC 1.0 at /a2a/jsonrpc, and skips interface 1, HTTP+JSON. Third, it reads the capability flags: streaming is true and pushNotifications is absent, and a CreateTaskPushNotificationConfig call that ignores the absent flag fails with error -32003. 1 · FIND THE CARD 2 · TAKE THE FIRST INTERFACE YOU SPEAK 3 · CHECK THE FLAG BEFORE AN OPTIONAL CALL direct configuration ports 41241, 41242, 41243 well-known URI GET /.well-known/ agent-card.json GET code-reviewer agent card 200 OK registry or catalog no standard query API or a registry query [0] JSONRPC, "1.0", http://localhost:41242/a2a/jsonrpc chosen [1] HTTP+JSON, "1.0", http://localhost:41242/a2a/rest skipped: not JSON-RPC streaming: true SendStreamingMessage, SubscribeToTask pushNotifications: absent the four push config operations fail exchange 6 of 11-errors.http calls one anyway: planner client code-reviewer /a2a/jsonrpc CreateTaskPushNotificationConfig -32003 PUSH_NOTIFICATION_NOT_SUPPORTED
Three routes lead to one card, and a client takes the first interface it speaks and checks a capability flag before each optional operation. Read top to bottom. The planner finds the code-reviewer card through configuration and the well-known path, takes interface 0, and reads two flags. The failed call is exchange 6 of the error capture.

Choosing from supportedInterfaces

The spec gives the client four rules for supportedInterfaces, all of them MUST. The first one decides the endpoint:

Supported means a binding and a version that the client implements. A JSON-RPC 1.0 client skips a GRPC entry and a JSONRPC entry at 0.3, since one card can list a binding at several versions.

The other three rules ask the client to prefer earlier entries and to use the URL of the chosen entry. The client also sets the tenant field of every request message to the exact value of that AgentInterface entry. No kit card sets a tenant.

Checking capabilities before a call

On the server side the rule is a MUST: a call that the card rules out fails with a fixed error. The table gives each error with its JSON-RPC code.

Flag in capabilitiesOperations it allowsError when the flag is absent or false
streamingSendStreamingMessage, SubscribeToTaskUnsupportedOperationError, -32004
pushNotificationsCreateTaskPushNotificationConfig, GetTaskPushNotificationConfig, ListTaskPushNotificationConfigs, DeleteTaskPushNotificationConfigPushNotificationNotSupportedError, -32003
extendedAgentCardGetExtendedAgentCardUnsupportedOperationError, -32004

Section 3 says that every A2A implementation must support its operations. Yet an agent declines streaming, push, or the extended card by leaving its flag out. The flags decide (conflict D26).

The code-reviewer card has no pushNotifications flag, and the kit's error scenario registers a webhook with it anyway:

a push configuration on an agent that declares no push supporthttpFull log
### 6 · CreateTaskPushNotificationConfig: not supported
POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41242
…
  "method": "CreateTaskPushNotificationConfig",
  "params": {
    "taskId": "00000000-0000-4000-8000-000000000000",
…
HTTP/1.1 200 OK
…
    "code": -32003,
    "message": "Push notifications are not supported",
…
        "reason": "PUSH_NOTIFICATION_NOT_SUPPORTED",
Exchange 6, cut to the method, the task id, and the error. The JSON-RPC error arrives with HTTP 200, as Errors explains.

The task id does not exist, yet the error names the missing capability, so the call cost a round trip the card had answered.

Skills, modes, and security fields say whether the agent fits the job and what it needs. The planner maps run-tests to test-runner and attaches a bearer token to every deployer call (the planner code). Part and security schemes read those fields.

Caching the card

A card changes rarely, so the spec asks both sides to use ordinary HTTP caching. A server should send a Cache-Control response header with a max-age directive. It also sends an ETag derived from the card's version or a hash of its content. A client honors those headers and revalidates an expired card with If-None-Match or If-Modified-Since.

The kit sends no Cache-Control or ETag header, as the kit README lists. An extended card replaces the cached public card for an authenticated session, as extended cards and signatures explains.

A2A protocol 1.0.1 · 3303592 · 2026-05-28 · Edition 2026.10