Agent Registries and Discovery

Picture a system where adding one agent means redeploying every other agent, because they all hold a hardcoded list of who exists. You want to add a translation agent, and suddenly you're editing and shipping six services that need to "know" the new agent is available. That's the world without agent registry discovery, and it's where a surprising number of multi-agent systems live - they hardcode the roster and pay a redeploy tax on every change.

A registry fixes this by letting agents find each other at runtime. Instead of "I know exactly which agents exist and how to reach them," each agent asks a registry "who can do X right now?" and gets a live answer. This guide builds one you can drop into an existing system, and it covers the parts people get wrong - health checking and capability matching - not just the happy path.

Quick-Start (Copy This Right Now)

Here's a minimal registry where agents register their capabilities and others look them up:

[object Object], time

,[object Object], ,[object Object],:
    ,[object Object], ,[object Object],(,[object Object],):
        ,[object Object],._agents = {}   ,[object Object],

    ,[object Object], ,[object Object],(,[object Object],):
        ,[object Object],._agents[agent_id] = {
            ,[object Object],: ,[object Object],(capabilities),
            ,[object Object],: endpoint,
            ,[object Object],: time.time(),
        }

    ,[object Object], ,[object Object],(,[object Object],):
        ,[object Object], [a ,[object Object], a ,[object Object], ,[object Object],._agents.values()
                ,[object Object], capability ,[object Object], a[,[object Object],]]

What this does: It lets each agent announce what it can do and where to reach it, and lets any agent query for others by capability. Asking find("translation") returns every agent currently offering translation - so a caller discovers who can help without ever hardcoding the translator's identity.

Understanding the Variables

Three concepts make agent registry discovery work: capabilities, health, and resolution.

Capabilities are what an agent advertises it can do, and they should be named abilities, not agent identities. "translation," "code-review," "web-search" - not "agent-7." This is the crucial design choice. When agents discover each other by capability rather than name, you can swap, add, or remove the agents behind a capability freely, because callers were never coupled to identity in the first place.

Health is whether a registered agent is actually alive. A registry that returns dead agents is worse than no registry - it hands callers endpoints that time out. So registration must expire; an agent that stops checking in gets removed. This is the single most-skipped part of a first registry, and its absence is why homegrown registries develop a reputation for "returning agents that don't work."

Resolution is how a caller picks among multiple agents offering the same capability. If three agents can translate, which one gets the request? This is where discovery meets load balancing, and a good registry gives you a hook to plug in a selection strategy.

There's a fourth concept that separates a toy registry from a production one: staleness tolerance. A caller that discovers an agent and then holds that reference for an hour is working from stale information - the agent may have died since. So discovery results should be treated as hints with a short shelf life, re-resolved when they fail rather than cached indefinitely. The pattern that works is discover-then-verify: find a capable agent, attempt the call, and if it fails, re-discover rather than retrying the same possibly-dead endpoint. Treating discovery results as permanent is the quiet bug that makes registries seem unreliable when the registry is fine and the caching is wrong.

⚡ Pro tip: Re-resolve on failure, don't retry the same endpoint. When a discovered agent fails a call, the highest-probability cause is that it died since you discovered it - so the right move is to ask the registry again and get a fresh, live agent, not to hammer the stale reference. Discover-then-verify with re-resolution on failure is what makes agent registry discovery hold up against the constant churn of agents coming and going. That churn is not an edge case in agent systems - it's the normal state of affairs, because agents restart, scale, and crash far more often than traditional services, so a registry that assumes stability will be wrong most of the time.

⚡ Pro tip: Register capabilities, never identities. The entire value of a registry evaporates the moment callers look up "agent-7" instead of "translation," because now they're coupled to a specific agent again. If you catch yourself putting agent names in lookup calls, stop - that's the coupling the registry exists to remove, sneaking back in.

Step-by-Step: Building Agent Registry Discovery

Let's build the real thing, with health checking and capability matching.

Step one, add heartbeats so the registry knows who's alive. Agents check in periodically; the registry prunes anyone who's gone quiet.

[object Object], ,[object Object],(,[object Object],):
    ,[object Object], agent_id ,[object Object], ,[object Object],._agents:
        ,[object Object],._agents[agent_id][,[object Object],] = time.time()

,[object Object], ,[object Object],(,[object Object],):
    now = time.time()
    dead = [aid ,[object Object], aid, a ,[object Object], ,[object Object],._agents.items()
            ,[object Object], now - a[,[object Object],] > ttl]
    ,[object Object], aid ,[object Object], dead:
        ,[object Object], ,[object Object],._agents[aid]   ,[object Object],

What this does: It tracks the last time each agent checked in and removes agents that haven't been heard from within the TTL. A crashed or hung agent stops sending heartbeats and drops out of discovery automatically, so find only ever returns agents that were alive moments ago.

Step two, add capability matching that's richer than exact string equality. Real capabilities have parameters - "translation" to which languages, "code-review" for which language. Match on capability plus constraints so a caller gets an agent that can actually do the specific job.

[object Object], ,[object Object],(,[object Object],):
    matches = []
    ,[object Object], a ,[object Object], ,[object Object],._agents.values():
        ,[object Object], capability ,[object Object], ,[object Object], a[,[object Object],]:
            ,[object Object],
        ,[object Object], constraints ,[object Object], ,[object Object], constraints_met(a, constraints):
            ,[object Object],
        matches.append(a)
    ,[object Object], matches

What this does: It filters registered agents by capability and by specific constraints - so a request for "translation to Japanese" only returns agents that actually handle Japanese. This prevents the common failure where a caller finds a "translator" that can't handle the language it needs and fails at call time instead of discovery time.

Step three, add resolution so callers pick well among matches. The simplest useful strategy is least-loaded: among capable, healthy agents, pick the one with the fewest in-flight requests. This turns discovery into lightweight load balancing for free.

Pro-Level Variations

For distributed systems, back the registry with a real coordination store so it survives restarts and is consistent across nodes. The in-memory version is perfect for a single process; multi-machine deployments need the registry itself to be reliable, since it's now critical infrastructure - if the registry is down, nobody can find anybody.

For systems using MCP, note that the protocol is moving toward automatic discovery through server cards - a standardized way for servers to advertise capabilities. Aligning your agent registry's capability descriptions with that emerging convention means less custom glue later, as tool discovery and agent discovery converge on shared conventions.

⚡ Pro tip: Make the registry itself discoverable through a single well-known address, and nothing else hardcoded. One bootstrap address that everyone knows, from which everything else is discovered, is the pattern that keeps the whole system loosely coupled. If agents hardcode more than that one address, the coupling you removed creeps back through the bootstrap path.

Troubleshooting Common Issues

If callers occasionally hit dead agents, your TTL is too long relative to your heartbeat interval, or pruning isn't running often enough. The registry's view of "alive" lags reality by at most one TTL, so tighten both if stale entries cause real failures.

If discovery returns agents that can't do the specific job, your capabilities are too coarse. "translation" without language constraints will match agents that can't handle the request. Add the constraints that matter to your domain so discovery filters accurately.

If two agents register the same capability with subtly different behavior, callers get inconsistent results depending on which they discover. Version your capabilities - "translation@v2" - so a caller can require a specific behavior version, and you can roll out a new implementation without callers silently getting changed behavior mid-flight. Capability versioning is the discovery equivalent of API versioning, and skipping it produces the maddening bug where a request behaves differently depending on which equivalent agent happened to answer.

⚡ Pro tip: Treat a capability name as a contract, not a label. "code-review" should mean the same thing - same inputs, same output shape, same guarantees - no matter which agent provides it. The moment two agents interpret the same capability name differently, discovery becomes a coin flip. Write down what each capability name promises and hold every provider to it, the way you'd hold implementations of an interface to its signature.

⚠️ Common mistake: Building discovery without health checking, so the registry accumulates ghosts - agents that registered, crashed, and never deregistered. Callers then discover these ghosts and fail on them. A registry without expiry isn't a registry, it's a graveyard that grows over time. Heartbeats and pruning aren't optional polish; they're the difference between a registry that helps and one that actively hands out broken endpoints.

Your Turn

Take a system where you currently hardcode which agents exist, stand up the minimal registry, and convert one hardcoded reference to a find call. Add heartbeats immediately - don't defer health checking, because that's the part that makes discovery trustworthy. A useful sequencing rule: get one capability lookup working end to end - register, heartbeat, prune, find, call, re-resolve on failure - before you convert a second. The full loop on one capability teaches you the edge cases (what happens when the only provider dies mid-call?) while the blast radius is small, and everything after that is repetition.

Keep your capability vocabulary and the agent registration prompts versioned so agents advertise consistently. I store the capability naming conventions in PromptABCD, because a coherent capability vocabulary - the same names meaning the same things across every agent - is what makes agent registry discovery actually usable, and that vocabulary is worth defining once and reusing everywhere rather than letting each agent invent its own capability names.