Skip to content

7.6 Discoverability

7.6.1 A2A

Key concepts from the A2A spec relevant to registries & discovery. - Agent Card: A JSON document that describes an agent: identity, endpoint, skills, capabilities, authentication schemes, etc. - Discovery Strategies: Ways a client finds other agents / their Agent Cards - e.g. via well-known URI, curated registries (catalog-based discovery), direct configuration/private discovery.

Registries are intermediary services that collect Agent Cards, allow querying them (by skills, provider, etc.), possibly with governance, permissions, etc.

Here we show an example of how A2A can be used:

1. Agent Card JSON (agent-card.json)

// at https://agent.example.com/.well-known/agent-card.json
{
  "name": "ExampleAgent",
  "description": "Agent that provides currency conversion",
  "provider": {
    "organization": "ExampleOrg",
    "url": "https://example.com"
  },
  "url": "https://agent.example.com/a2a",
  "version": "1.0.0",
  "protocolVersion": "0.2.5",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "currency_convert",
      "name": "Convert Currency",
      "description": "Convert between currencies given amount and currency codes",
      "inputModes": ["text"],
      "outputModes": ["text"],
      "examples": [
        {
          "input": "Convert 100 USD to EUR",
          "output": "≈ 92 EUR"
        }
      ]
    }
  ],
  "authentication": {
    "schemes": ["Bearer"]
  }
}

2. Registry Server

# registry_server.py

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Dict, Any
from python_a2a import AgentCard, AgentRegistry  # assuming A2A SDK

class AgentCardPayload(BaseModel):
    __root__: Dict[str, Any]  # accept raw JSON

app = FastAPI()
registry = AgentRegistry(
    name="MyAgentRegistry",
    description="Simple registry for agents"
)

@app.post("/register")
def register_agent(payload: AgentCardPayload):
    ac = AgentCard.from_dict(payload.__root__)
    registry.register(ac)
    return {"status": "ok"}

@app.get("/agents")
def list_agents():
    cards = registry.list_agent_cards()
    return {"agents": [c.to_dict() for c in cards]}

3. Registering an agent in the registry

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  --data-binary @agent-card.json

4. Using an agent from the registry

import requests
from python_a2a import AgentCard, Client  # assuming A2A SDK

REGISTRY_URL = "http://localhost:8000/agents"

def discover_agents():
    resp = requests.get(REGISTRY_URL)
    resp.raise_for_status()
    cards = resp.json()["agents"]
    return [AgentCard.from_dict(c) for c in cards]

def use_first_agent(skill_id: str, input_text: str):
    agents = discover_agents()
    if not agents:
        raise Exception("No agents available in the registry")

    agent = agents[0]  # pick the first one
    client = Client(agent.url, auth_scheme=agent.authentication)

    result = client.create_task(
        skill_id=skill_id,
        input={"text": input_text}
    )
    return result

if __name__ == "__main__":
    res = use_first_agent("currency_convert", "Convert 100 USD to EUR")
    print("Result:", res)

Summary

Putting all the above pieces together, A2A enables agent registries & discovery in this way:

  • Agents expose their metadata (Agent Card) in a standardized format. Client agents can rely on parsing Agent Cards to discover what skills, capabilities, authentication schemes etc. an agent has.
  • Registries centralize publishing of these Agent Cards. Agents register themselves; client agents query the registry to discover which other agents can help with a given need.
  • Well-known URI provides a lightweight, decentralized method: no central registry needed if agents are known via domain names.
  • Private / direct discovery supports closed or internal ecosystems.