Agent Discovery in A2A

To collaborate over the A2A protocol, agents first need to find each other and understand each other’s capabilities. A2A standardizes agent self-description through the Agent Card, but how clients discover those cards varies with the environment and requirements. The Agent Card defines what an agent offers; the discovery strategy depends on the deployment environment and security needs.

The role of the Agent Card

The Agent Card is a JSON document that serves as a digital business card for an A2A server (the remote agent), and it is central to discovery and interaction. It includes:

Identity: name, description, and provider information.
Service interfaces: supportedInterfaces lists the interfaces the server supports. Each has a url, a protocolBinding (such as JSONRPC, GRPC, or HTTP+JSON), a protocolVersion, and an optional tenant.
A2A capabilities: capabilities declares supported features such as streaming, pushNotifications, and extensions, as well as whether an authenticated extended Agent Card is available (extendedAgentCard).
Authentication: securitySchemes and securityRequirements declare the authentication schemes and requirements.
Skills: AgentSkill objects describe what the agent can do, with id, name, description, tags, inputModes, outputModes, and examples.
Default modes: defaultInputModes and defaultOutputModes.

Client agents use the Agent Card to judge suitability, structure requests, and communicate securely. For the full field definitions, see Specification: agent discovery .

Discovery strategies

1. Well-known URI

Recommended for public agents, or agents meant for broad discovery within a domain.

Mechanism: The A2A server hosts its Agent Card at a standardized well-known URI on its domain. The standard path is https://{agent-server-domain}/.well-known/agent-card.json, following the principles of RFC 8615 .
Process:
1. A client agent knows or programmatically discovers the domain of a potential A2A server (for example smart-thermostat.example.com).
2. The client sends an HTTP GET to https://smart-thermostat.example.com/.well-known/agent-card.json.
3. If the Agent Card exists and is accessible, the server returns it as JSON.
Advantages: Easy to implement, adheres to standards, enables automated discovery.
Considerations: Best for open or domain-controlled discovery. If the card contains sensitive details, the endpoint serving it needs authentication.

2. Curated registries (catalog-based discovery)

Used in enterprise environments or public marketplaces, where Agent Cards are often managed by a central registry. The registry acts as a central repository that lets clients query and discover agents by criteria such as skills or tags.

Mechanism: An intermediary service (the registry) maintains a collection of Agent Cards. Clients query it by criteria such as offered skills, tags, provider name, or capabilities.
Process:
1. A2A servers publish their Agent Cards to the registry.
2. Client agents query the registry API, searching by criteria such as specific skills.
3. The registry returns matching Agent Cards or references.
Advantages: Centralized management and governance; capability-based discovery (by skill, for example); support for access controls and trust frameworks; works for both private and public marketplaces.
Considerations: Requires deploying and maintaining a registry service. The current A2A specification does not prescribe a standard API for curated registries.

3. Direct configuration / private discovery

Used for tightly coupled systems, private agents, or development, where clients are configured directly with Agent Card information or URLs.

Mechanism: Client applications use hardcoded details, configuration files, environment variables, or proprietary APIs.
Process: Specific to the application’s deployment and configuration strategy.
Advantages: Straightforward for known, static relationships.
Considerations: Inflexible for dynamic discovery; changes to Agent Card information require reconfiguring clients; proprietary API-based discovery also lacks standardization.

Securing Agent Cards

Agent Cards can include sensitive information, such as URLs for internal or restricted agents and descriptions of sensitive skills.

Protection mechanisms

Authenticated extended Agent Cards: For sensitive information, or to serve a more detailed version of the card, use an authenticated extended Agent Card (GetExtendedAgentCard; the server declares support through capabilities.extendedAgentCard).
Secure endpoints: Apply access controls to the HTTP endpoint that serves the card (such as /.well-known/agent-card.json or a registry API) with mutual TLS (mTLS), network restrictions (for example IP ranges), or HTTP authentication (for example OAuth 2.0).
Registry selective disclosure: Registries return different Agent Cards depending on the client’s identity and permissions.

Any Agent Card that contains sensitive data must be protected with authentication and authorization. The A2A specification strongly recommends out-of-band dynamic credentials rather than embedding static secrets in the card.

Agent Card signing

Agent Cards can be digitally signed with JSON Web Signature (JWS, RFC 7515 ) so clients can verify that a card has not been tampered with and comes from the claimed provider. Before signing, the card content must be canonicalized with the JSON Canonicalization Scheme (JCS, RFC 8785 ), and the signatures field itself is excluded from what is signed. The signature format and verification procedure are described in the specification .

Caching

Agent Cards describe an agent’s capabilities and typically change infrequently, for example when skills are added or authentication requirements are updated. Applying standard HTTP caching to Agent Card endpoints reduces unnecessary requests while ensuring clients eventually receive updated information.

Server guidance: Servers hosting Agent Card endpoints should include HTTP caching headers. A Cache-Control header with an appropriate max-age lets clients and intermediaries cache the card for a set duration. Adding an ETag derived from the card’s version field or a content hash lets clients make conditional requests and avoid re-downloading unchanged cards.

Client guidance: Clients should honor standard HTTP caching semantics. When a cached card expires, use conditional requests (for example If-None-Match with the stored ETag, or If-Modified-Since) instead of unconditionally re-fetching the full card. When the server provides no caching headers, clients may apply a reasonable default cache duration. For extended Agent Cards, clients should also follow the session-scoped caching guidance in the specification.

For normative requirements, see the caching section of the agent discovery chapter in the specification.

Future considerations

The A2A community is exploring standardized registry interactions and more advanced discovery protocols.