Agent Discovery

Agent Discovery in A2A

To collaborate using the Agent2Agent (A2A) protocol, client agents must first find remote agents and understand their capabilities. A2A standardizes the self-description format via the AgentCard, but it intentionally leaves room for multiple discovery strategies depending on environment and security requirements.

The role of the AgentCard

An AgentCard is a JSON document that acts as a digital “business card” for an A2A server. It typically includes:

• Identity: name, description, and provider
• Service endpoint: url
• Capabilities: e.g. streaming, pushNotifications, and optional extensions
• Authentication: supported schemes and requirements
• Skills: what the agent can do (ids, descriptions, input/output modes, examples)

Clients use the AgentCard to decide whether an agent is suitable, how to authenticate, and how to structure requests.

Discovery strategies

1) Well-known URI

Recommended for public agents or agents intended for broad discovery within a domain.

• Mechanism: host the AgentCard at a standardized well-known path, commonly:
  • https://{agent-domain}/.well-known/agent-card.json
• Process:
  1. Client learns the domain (configured, discovered, or user-provided).
  2. Client fetches the AgentCard via HTTP GET.
  3. Client validates and caches metadata as appropriate.

2) Curated registries (catalog-based discovery)

Common in enterprise environments or marketplaces.

• Mechanism: a central registry stores and serves AgentCards (or references).
• Process:
  1. Agents publish cards to the registry.
  2. Clients query by criteria such as skills, tags, provider, or capabilities.
  3. Registry returns matching cards (possibly filtered by access policy).

The A2A specification does not mandate a single standard registry API.

3) Direct configuration / private discovery

Used for tightly-coupled systems, private agents, and development setups.

Clients may be configured with AgentCard URLs (or the card contents) via configuration files, environment variables, secrets managers, or proprietary APIs.

Securing AgentCards

AgentCards may expose sensitive details (internal URLs, restricted skills, authentication metadata). Consider:

• Protecting the endpoint (mTLS, IP allowlists, OAuth, etc.)
• Serving different card variants depending on client identity/permissions
• Avoiding static secrets embedded in cards; prefer out-of-band credentials

Future considerations

The A2A ecosystem continues to explore best practices for registries, trust frameworks, and richer discovery protocols. If your environment needs a registry, design it with authentication, authorization, and selective disclosure from day one.