Agent Registry

What it is

The catalogue of agents a system knows about, holding for each one the metadata needed to find it, judge whether it fits, and resolve it to something callable: its name, current revision, owner, declared capabilities, status, and endpoint or handle. It answers lookup questions — what exists, which revision is live, who may invoke it — and executes nothing.

Why it matters

Up to three or four agents, hard-coded references work fine. Past that, the failures are organisational rather than technical: two teams build the same assistant without knowing, an agent nobody owns keeps serving traffic, a planned retirement has no way of reaching its callers, and nothing in the system can answer "what is running in production right now". A catalogue is what makes an agent discoverable, attributable, and retirable, and it is the natural place to enforce which callers are entitled to which agents.

What the catalogue adds to the entries it holds

An individual artefact describes one agent completely and says nothing about the population. The catalogue is what makes the population tractable: it guarantees name uniqueness, resolves a name to a revision, records deprecation state and ownership, tracks who is calling what, and gives every other system one place to ask. An artefact is correct in isolation; an entry is only useful in relation to the others beside it.

Key decisions

• Whether publication is self-service at deploy time or passes through review. Self-service keeps the catalogue current and fills it with near-duplicates; review keeps it clean and makes it lag reality.
• Whether consumers read it once at startup or on every invocation. Per-call lookup is always fresh and puts a network dependency in front of all agent traffic.
• What a resolution request is allowed to ask for: a bare name resolving to whatever is current, an exact revision, or a constraint range — and therefore who absorbs the risk when the current revision changes behaviour.
• Whether entries are written for humans browsing a catalogue or for programs querying it. The two audiences want different fields, and prose intended for people is a poor input to an automated choice.
• Whether entitlement lives here or elsewhere. A catalogue that answers "may this caller invoke this agent" is on the security path and inherits those requirements.

Failure modes

• Lookup becomes a hard dependency on the request path, and an outage in a service that stores descriptions takes down every agent interaction in the product.
• Entries are written at launch and never revised; descriptions describe behaviour the agent no longer has, and anything choosing on those descriptions is choosing on fiction.
• Two groups publish overlapping agents under different names, traffic splits between them, and neither accumulates enough evidence to be judged better than the other.
• An agent is marked deprecated and nothing verifies that callers stopped; it is still taking production traffic a year after its retirement was announced.
• Names are treated as mutable display strings, and a rename breaks every caller that resolved by name.
• No owner or on-call contact is recorded, so when an agent starts misbehaving there is no path from the entry to a person who can act.
• Descriptions are written as promotional copy, and whichever entry claims the broadest competence attracts work it cannot do.
• Staging and production share one namespace, and a test agent is resolved by a live caller.

Related capabilities

• Agent Definition — supplies the artefact and declared facts an entry publishes
• Agent Routing — the principal consumer of entries at request time
• Agent-as-a-Tool — turns an entry into a callable signature for another agent
• Agent Lifecycle — an entry describes availability, not the state of any running instance
• Multi-agent Orchestration — a supervisor assembles its worker set from here

Applies: Production readiness · Design questions