What Is A2A Agent Discovery?

A2A Agent Discovery is the mechanism by which AI agents locate and understand each other's capabilities within the A2A Protocol ecosystem. It answers a foundational question in multi-agent system design: how does an orchestrator know which agents exist, what they can do, and how to reach them?

The A2A Protocol solves this through a combination of standardized well-known URIs and structured Agent Cards — making agent discovery automatic, decentralized, and compatible with existing HTTP infrastructure.

The Discovery Problem in Multi-Agent Systems#

Traditional multi-agent systems often rely on hardcoded routing: the orchestrator is programmed with explicit knowledge of which downstream agents handle which task types. This approach works at small scale but fails as systems grow. Adding a new agent means updating orchestrator code. Changing an agent's capabilities creates drift between the orchestrator's model and reality.

A2A Agent Discovery eliminates this by making capability knowledge external and dynamic. Orchestrators fetch capability metadata at runtime rather than relying on compile-time knowledge. This enables genuinely modular agent ecosystems where components can be added, removed, or updated without central coordination.

How Discovery Works: Step by Step#

The A2A discovery flow is intentionally simple:

Step 1: Retrieve the Agent Card#

Given a peer agent's base URL, the discovering agent makes an HTTP GET request to the well-known URI:

GET /.well-known/agent.json HTTP/1.1
Host: data-analysis-agent.example.com
Accept: application/json

The agent at that URL responds with its Agent Card:

{
  "name": "Data Analysis Agent",
  "description": "Performs statistical analysis, data visualization, and predictive modeling on structured datasets.",
  "url": "https://data-analysis-agent.example.com/a2a",
  "version": "2.1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/csv", "application/json", "application/vnd.ms-excel"],
  "defaultOutputModes": ["application/json", "image/png", "text/plain"],
  "skills": [
    {
      "id": "statistical-summary",
      "name": "Statistical Summary",
      "description": "Generates descriptive statistics (mean, median, std dev, percentiles, outlier detection) for numerical datasets.",
      "inputModes": ["text/csv", "application/json"],
      "outputModes": ["application/json"]
    },
    {
      "id": "trend-forecast",
      "name": "Trend Forecasting",
      "description": "Applies time-series forecasting models (ARIMA, Prophet, LSTM) to predict future values from historical data.",
      "inputModes": ["text/csv"],
      "outputModes": ["application/json", "image/png"]
    }
  ]
}

Step 2: Parse and Cache the Card#

The discovering agent parses the JSON, validates it against the A2A schema, and stores it — typically keyed by the agent's base URL and version string. HTTP cache headers (ETag, Cache-Control: max-age) should govern how long the cached card is considered fresh.

Step 3: Reason Over Capabilities#

The orchestrating agent (or its LLM) compares the task at hand against the discovered skills. This reasoning can be rule-based ("does skill description contain 'CSV' and 'statistics'?") or LLM-driven (passing the skill descriptions and task description to a language model to select the best match).

Step 4: Delegate the Task#

Once a matching agent and skill are identified, the orchestrator initiates an A2A task via the endpoint in the card's url field:

POST /a2a/tasks/send HTTP/1.1
Host: data-analysis-agent.example.com
Authorization: Bearer <oauth-token>
Content-Type: application/json

{
  "id": "task-abc-123",
  "message": {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "text": "Generate a statistical summary of the attached sales dataset."
      },
      {
        "type": "data",
        "mimeType": "text/csv",
        "data": "<base64-encoded-csv>"
      }
    ]
  }
}

Discovery Patterns in Practice#

Bootstrapped Discovery#

The simplest pattern: the orchestrator is initialized with a list of trusted agent base URLs. At startup, it fetches and caches all their Agent Cards. This works well for closed systems with a known set of agents.

from a2a.client import A2AClient

TRUSTED_AGENTS = [
    "https://research-agent.example.com",
    "https://data-agent.example.com",
    "https://email-agent.example.com",
]

async def load_agent_registry():
    registry = {}
    async with A2AClient() as client:
        for base_url in TRUSTED_AGENTS:
            card = await client.get_agent_card(base_url)
            registry[base_url] = card
    return registry

Registry-Assisted Discovery#

For larger deployments, a central Agent Registry stores known agent URLs. Orchestrators query the registry rather than maintaining their own agent lists:

async def discover_agent_for_task(task_description: str, registry_url: str):
    # Query registry for candidate agents
    candidates = await registry.search(task_description)
    # Fetch cards for top candidates
    cards = [await client.get_agent_card(c.url) for c in candidates[:5]]
    # LLM selects best match
    best_match = await llm.select_agent(task_description, cards)
    return best_match

Dynamic Discovery via LLM Reasoning#

Advanced orchestrators use LLM reasoning to evaluate Agent Cards:

async def select_best_agent(task: str, available_cards: list[AgentCard]) -> AgentCard:
    card_summaries = [
        f"Agent: {c.name}\nSkills: {[s.description for s in c.skills]}"
        for c in available_cards
    ]

    response = await llm.complete(
        system="You are an agent orchestrator. Select the most capable agent for the given task.",
        user=f"Task: {task}\n\nAvailable agents:\n" + "\n\n".join(card_summaries)
    )

    selected_name = parse_agent_selection(response)
    return next(c for c in available_cards if c.name == selected_name)

Security Considerations in Agent Discovery#

Discovery introduces security risks that must be addressed explicitly:

Agent impersonation: A malicious actor could stand up an agent at a domain that mimics a legitimate service. Orchestrators must validate Agent Card authenticity using TLS certificate verification and, for high-trust environments, signed Agent Cards using JSON Web Signatures (JWS).

Discovery poisoning: If using a centralized registry, compromise of the registry could redirect task delegation to malicious agents. Implement registry integrity verification and audit all registry updates. See agent audit trail for logging requirements.

Capability spoofing: Agents could claim capabilities they cannot actually fulfill, causing silent failures or data exposure. Orchestrators should implement health checks and track per-agent success rates.

Least privilege routing: Apply least privilege principles when delegating — only share the data and context a downstream agent needs to fulfill its specific skill.

Relationship to MCP Server Discovery#

The Model Context Protocol (MCP) has its own server discovery mechanism, separate from A2A. MCP servers are typically discovered through local configuration files or environment variables, not well-known URIs. A2A's HTTP-native discovery model is more suited to distributed, internet-scale deployments where agents run as independent services.

In practice, an agent might use A2A discovery to find peer agents for task delegation, while using MCP's configuration-driven discovery to connect to tools and data sources. See the MCP vs A2A Protocol comparison for a detailed breakdown.

Building Discovery Into Your A2A Implementation#

When building A2A-compatible agents, ensure your discovery implementation:

1. Serves a valid Agent Card at /.well-known/agent.json over HTTPS
2. Updates the card when capabilities change (including a version bump)
3. Validates incoming cards before trusting and delegating to them
4. Implements caching with appropriate TTL and invalidation logic
5. Logs all discovery events for security auditing
6. Handles discovery failures gracefully with fallback routing

Agent discovery is the foundation of dynamic multi-agent composition. Getting it right — with proper validation, caching, and security controls — enables the kind of flexible, evolving agent ecosystems that make agent swarms and large-scale multi-agent systems viable in production.

More Resources#

Browse the complete AI agent glossary for more AI agent terminology.

See also: tutorials for practical examples.