Agent Registry — Patterns

Resolve at startup, refresh in the background

Problem. Fresh data and high availability pull in opposite directions. Looking up on every invocation guarantees correctness and makes the catalogue a hard dependency of every interaction; loading once at boot removes the dependency and makes a deprecation take days to land.

Approach. Resolve the full set at startup into a local snapshot, serve every lookup from it, and refresh asynchronously on a short interval. Keep serving the last good snapshot when a refresh fails, and emit the snapshot's age as a metric so staleness is visible rather than assumed.

Trade-off. Every consumer can be running a different snapshot, so an entry change takes effect at different moments across the fleet. Anything requiring an immediate fleet-wide stop needs a separate, deliberately simple mechanism rather than this one.

Two-audience entries

Problem. One description field cannot serve both a person deciding whether to adopt an agent and a program deciding whether to send it a task. Prose written for the first makes the second unpredictable, and attribute lists written for the second tell a person nothing.

Approach. Split each entry: a structured block of declared attributes that programs may read, and a documentation block that only people see. Forbid automated consumers from reading the prose, and hold the structured block to a validated schema.

Trade-off. Two fields drift apart, and the prose is usually the one that is right. A periodic reconciliation — ideally a test that exercises the agent against its declared attributes — is the only thing that keeps them honest.

Deprecation gated on observed callers

Problem. Marking an entry deprecated communicates intent and changes nothing. The announcement reaches a mailing list; the callers are in services whose owners did not read it.

Approach. Record every resolution against the entry with the calling service's identity, and make retirement a function of observed traffic rather than elapsed notice period. Expose the current caller list on the entry so its owner can see exactly who still has to move, and let the entry refuse to transition to retired while the list is non-empty.

Trade-off. Call attribution requires every consumer to identify itself honestly, and one unattributed caller blocks retirement indefinitely. There has to be an override, and the override has to be rare enough to stay meaningful.

Namespaced environments with explicit promotion

Problem. A single flat namespace invites a development agent to be resolved by production traffic, and makes "the same agent" in two environments an assertion rather than a fact.

Approach. Scope every entry by environment, resolve only within the caller's own scope, and make promotion an explicit operation that copies a specific revision forward. Never let a name resolve across a scope boundary, even when the target scope has no match.

Trade-off. Promotion is another step that can be forgotten, and environments drift when someone fixes production directly. The failure becomes visible and attributable, which is the improvement; it does not become impossible.