Agent Discovery

• Understand an agent’s capabilities and skills.
• Learn how to communicate with the agent (endpoints and message formats).
• Authenticate and establish a secure connection.
• Construct requests appropriate to the agent’s capabilities.

​

Well-Known URI (recommended for public agents)

https://smartthermostat.example.com/.well-known/agent-card.json

1. Client knows or learns a candidate domain (DNS, search, or user input).
2. Client performs an HTTP GET to the well-known path on that domain.
3. If available and accessible, the server returns a JSON agent card describing the agent(s) and connection details.

curl -sS https://smartthermostat.example.com/.well-known/agent-card.json

• The card may describe a single agent or multiple agents hosted at the domain.
• Sensitive fields (internal URIs, auth endpoints) should be protected; authentication on the well-known endpoint may be required.
• Advantages: easy to implement, friendly to automated discovery, suitable for public or domain-controlled agents.
• Best suited for: open discovery scenarios, public-facing agents, or where domain-based discovery is appropriate.

​

Curated Registries (catalog-based discovery)

1. A2A servers publish (push) agent cards to the registry.
2. Clients query the registry API using search criteria (skills, tags, provider).
3. The registry returns matching agent cards, potentially filtered by client permissions.

• Centralized governance, auditing, and lifecycle management.
• Capability-based discovery: search by skill, tag, or provider.
• Built-in access control and trust networks.
• Enables discovery without knowing individual agent domains.

• Requires deploying and operating registry infrastructure.
• A2A spec currently does not define a standard registry API; implementations vary.
• The registry becomes a critical component for availability and trust.

• Enterprise agent catalogs and marketplaces.
• Skill-based discovery in multi-tenant environments.
• Public marketplaces and curated app stores.

​

Direct Configuration (private or tightly-coupled discovery)

• Agent card details are provisioned to the client at deployment or startup.

{
  "agent_id": "internal-thermostat-1",
  "agent_card": {
    "name": "Internal Thermostat Agent",
    "endpoint": "https://10.0.1.42:8443/a2a",
    "auth": {
      "type": "mTLS"
    },
    "capabilities": ["temperature.read", "temperature.set"]
  }
}

• Simple and reliable for known relationships.
• Ideal for development, testing, and tightly coupled microservices.
• No discovery infrastructure required; full control over agent relationships.

• Limited flexibility in dynamic environments.
• Updating agent details often requires redeployment or reconfiguration.
• Not standardized or scalable for large, dynamic agent networks.

• Development and QA.
• Private/internal agent networks.
• Tightly-coupled microservice integrations.

​

Strategy comparison

​

Securing Agent Cards

• Authenticated agent cards
  • Serve extended or sensitive fields only to authenticated, authorized clients.
  • Provide different card versions depending on client permissions (selective disclosure).
• Secure endpoints
  • Use mutual TLS (mTLS) for certificate-based authentication of clients.
  • Apply network-level controls (IP allowlists, private network access).
  • Protect APIs with OAuth 2.0, API keys, signed tokens, or equivalent HTTP auth.
• Registry-based selective disclosure
  • Registries can return filtered agent cards depending on client identity and access rights.
  • Role-based access control (RBAC) lets registries hide sensitive fields from unauthorized clients.

​

Best practices

• Prefer out-of-band dynamic credentials (short-lived tokens or ephemeral certificates) rather than embedding long-lived static credentials in agent cards.
• Implement strong authentication and authorization for endpoints that serve agent cards.
• Protect discovery endpoints (well-known URIs and registry APIs) with appropriate transport and network security (HTTPS, mTLS, allowlists).
• Consider publishing multiple card views (public summary vs. internal full card) and only reveal sensitive details to authorized clients.
• Audit access to agent cards and monitor discovery traffic for anomalies and abuse.

​

Future considerations

• Standardized registry APIs and discovery protocols.
• Enhanced selective disclosure and privacy-preserving card formats.
• Improved scalability for large agent networks and federated discovery.
• Better tooling for catalog governance and trust establishment.

​

Links and references

• RFC 8615 — Well-Known URIs
• OAuth 2.0 overview: https://oauth.net/2/
• mTLS concept summary: https://en.wikipedia.org/wiki/Mutual_authentication