Learn A2A - Registry & Discovery Service

#Introduction

In episode 15 we built observability: task lifecycle tracing and audit logs. All of that assumes we already know which agent is called. The earlier question — how to find the right agent among dozens or hundreds of agents? — we haven't answered.

In episode 3 we learned about the Agent Card for one-by-one discovery: the client fetches the card at the standard /.well-known/agent-card.json endpoint. That works at small scale. Once the number of agents grows, holding a list of URLs manually in every client won't be sustainable. We need a registry: one centralized place that stores, validates, and serves Agent Cards.

This episode's roadmap: we start with the problem of manual discovery, then build a service registry as the Agent Card store, learn dynamic discovery with heartbeat, look at an ecosystem catalog with hundreds of agents, and close with routing patterns for choosing the best agent.

#From Hard-Coded URLs to Discovery

At small scale, the common pattern is hard-coded URLs: the orchestrator keeps a dictionary of agent id to URL and exports it from configuration.

config.py — the fragile early approach

AGENTS = {
    "pricing": "https://pricing.example.com/.well-known/agent-card.json",
    "shipping": "https://shipping.example.com/.well-known/agent-card.json",
    "translation": "https://translation.example.com/.well-known/agent-card.json",
}

This approach is fragile. Every time a new agent appears, an address changes, or a version is deployed, all clients must be updated. Dead agents keep being called until errors surface. This is where a service registry replaces static configuration with dynamic discovery.

#Service Registry: The Agent Card Store

A service registry is a server that stores Agent Cards from many agents and provides APIs to register, search, and revoke. Some registry implementations provide a discovery module directly inside the SDK, for example the python_a2a.discovery module, which provides AgentRegistry, DiscoveryClient, and the enable_discovery helper.

Its flow is simple: an agent registers its card to the registry on startup, the registry stores and serves it, and clients query the registry to find agents.

Common endpoints a registry exposes:

POST /registry/register
POST /registry/unregister
GET  /registry/agents
POST /registry/heartbeat
GET  /a2a/agents

Example of running a registry and registering an agent:

registry.py — run the registry

from python_a2a.discovery import AgentRegistry, run_registry
 
registry = AgentRegistry(name="Registry Internal A2A")
run_registry(registry, host="0.0.0.0", port=8000)

agent.py — register the agent to the registry

from python_a2a import AgentCard, A2AServer, run_server
from python_a2a.discovery import enable_discovery
 
agent_card = AgentCard(
    name="kalkulator",
    description="Agent perhitungan harga dan ongkir.",
    url="http://localhost:8001",
    version="1.0.0",
)
agent = A2AServer(agent_card=agent_card)
enable_discovery(agent, registry_url="http://localhost:8000")
run_server(agent, host="0.0.0.0", port=8001)

SDK installation:

pip install python-a2a

#Dynamic Discovery and Heartbeat

A registry is only useful if its data is accurate. Agents can die at any time, and a registry must not serve agents that are no longer healthy. Two mechanisms keep it accurate:

1. Heartbeat — the agent sends a periodic signal, for example every 60 seconds. The registry marks agents that haven't sent a heartbeat within a certain time as inactive.
2. Pruning — the registry periodically removes agents past their grace period, so the list doesn't fill with garbage.

Clients run discovery to get the list of active agents, or check directly with curl http://localhost:8000/registry/agents:

client.py — find agents from the registry

from python_a2a.discovery import DiscoveryClient
 
client = DiscoveryClient(agent_card=None)
client.add_registry("http://localhost:8000")
agents = client.discover()
 
for agent in agents:
    print(f"{agent.name} at {agent.url} — {agent.description}")

Dynamic discovery lets the network topology change without changing client code. Add a new agent, start its heartbeat, and within seconds other agents find it. A retiring agent just stops its heartbeat and automatically disappears from discovery results.

#Ecosystem Catalog: Public Registry

Registries aren't only for internal use. The A2A ecosystem also has public registries holding agents from many organizations — catalogs that host hundreds of partners with verified AgentCards. Some public registries even display metrics like uptime and latency per agent.

Public registry models usually provide:

• Search by keyword and skill tags.
• Filter by conformance level (for example, conformant to a specific spec version).
• Verification — agent cards tested and verified by the registry team.
• Metrics — uptime, latency, and live status.

Example of a search pattern in a public registry:

curl "https://a2aregistry.org/api/agents?skill=translation"

The presence of a public catalog changes how the ecosystem works. Agents from different organizations can find each other without one-by-one negotiation — just register in the registry, publish a complete card, and other agents searching for the same capabilities will find you.

#Routing Patterns: Capabilities, Rating, and Latency

Finding an agent is only half the journey. Once you have the candidate list, you must choose the best one for a given task. Common criteria:

• Capabilities — the agent must have the skill the task needs. This is a hard filter constraint.
• Rating — trust from previous experience or registry verification.
• Latency — response speed; the lower the better.
• Health — active and stable status.

Twilio's pattern for real-time routing is worth copying: pick the node with the lowest latency among the healthy ones, with automatic failover to the second candidate if the first times out. Because latency changes, measurements are taken periodically, not once at startup.

A simple scoring implementation combining the three criteria:

router.py — score agent candidates

def score(candidate, task):
    if task.get("capability") not in candidate["capabilities"]:
        return -1
    if candidate["health"] != "healthy":
        return -1
    s = 50.0
    s += candidate["rating"] * 20
    s += max(0.0, 200.0 - candidate["latency_ms"]) * 0.1
    return s
 
def pick_agent(candidates, task):
    return max(candidates, key=lambda c: score(c, task))

A good pattern also adds sticky routing: a task that continues a previous task is forwarded to the same agent so session state stays consistent, unless that agent goes down. And when routing fails, falling back to the second candidate prevents a single point of failure.

#Conclusion

In this episode we resolved the discovery and routing question. The service registry becomes a centralized Agent Card store with registration, search, and heartbeat APIs to keep it accurate. Public registries open an ecosystem catalog of hundreds of agents with verification and metrics. And routing patterns based on capabilities, rating, and latency — inspired by Twilio's latency-aware pattern — ensure each task lands on the most appropriate agent.

Here's the core takeaway:

• A service registry replaces hard-coded URLs with dynamic discovery.
• Heartbeat and pruning keep the agent list accurate in the registry.
• Public registries provide search, filter, verification, and metrics for the ecosystem catalog.
• Routing uses capabilities as a hard filter, then scores based on rating and latency.
• Twilio-style latency-aware patterns pick the fastest healthy node with automatic failover.

Now agents can find and select each other dynamically. But the tasks sent are still simple patterns. What if one task needs to be split across many agents, wait for human approval, or be retried when it fails?

In the next episode, episode 17, we'll discuss Advanced Task Patterns: fan-out and fan-in orchestration between agents, human-in-the-loop workflows with the input-required state and resubmission, and state management like idempotency, retry, long-running tasks, and checkpoint-resume. See you there!