Agent Discovery

Agent cards provide information about agents, and they can be discovered several ways.

A2A's discovery is based on modern web standards like JSON, HTTP, and OAuth. This allows a decentralized ecosystem with multiple actors, including agent developers, validators, registries, and agent hosting organizations.

Discovery Methods

Open Discovery

Individuals and organizations can publicly list and advertise their agent URLs:

https://customer.xyz/salesagent/card.json

These agent cards can be freely accessed by anyone with the URL. This can be suitable for agents that are meant to be used by the general public.

Curated Discovery

Organizations and communities may operate discovery networks or registries, which list and categorize agents that meet certain criteria. These registries can:

• Validate agents against security and quality standards
• Group agents by category, capabilities, or industry
• Provide search and recommendation functionality
• Offer ratings and reviews from users

Example of a registry endpoint:

https://registry.example.com/agents?category=travel&capability=booking

Registries can implement various levels of curation:

• Open registries that accept all self-published agents
• Verified registries that validate basic functionality and security
• Premium registries with extensive testing and certification

Private Discovery

Organizations may operate private agent catalogs accessible only to authorized users. This is appropriate for:

• Enterprise environments with proprietary agents
• Internal tools and utilities
• Agents that handle sensitive data

Private discovery typically requires authentication:

GET https://enterprise.internal/agents
Authorization: Bearer <token>

Securing Agent Cards

When hosting agent cards, consider these security practices:

1. HTTPS Only: Always serve agent cards over HTTPS
2. Access Control: Use appropriate authentication for private agents
3. Content Security: Set correct CORS headers to control which domains can access cards
4. Versioning: Include version information in agent cards
5. Immutable References: Consider using content-addressable references for immutable versions
6. Digital Signatures: Sign agent cards to verify authenticity

Discovery Protocol

Clients can discover agent capabilities through:

1. Direct Discovery: Access the agent card directly via its URL
2. Registry Query: Query a registry for agents matching specific criteria
3. Well-Known URI: Check for agent cards at standard locations like .well-known/a2a-agents

Example of checking a well-known URI:

GET /.well-known/a2a-agents HTTP/1.1
Host: example.com

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

{
  "agents": [
    {
      "name": "Customer Support",
      "endpoint": "https://example.com/agents/support",
      "description": "24/7 customer support agent"
    },
    {
      "name": "Sales Assistant",
      "endpoint": "https://example.com/agents/sales",
      "description": "Product information and ordering assistance"
    }
  ]
}

Agent Card Validation

Clients should validate agent cards by:

1. Verifying the HTTPS certificate
2. Checking for required fields
3. Validating against the A2A agent card schema
4. Ensuring the agent supports required capabilities
5. Verifying any digital signatures

Implementation Examples

The A2A repository contains examples of agent discovery:

• Agent Registry - A simple TypeScript implementation of an agent registry
• Python Client Discovery - Code for discovering and validating agent cards