Show & Tell: AgentRegistry — Distributed Agent Identity and Capability Registry (Phase 12.1)

[web3guru888]

Phase 12.1 — AgentRegistry Architecture

With Phase 11 (Alignment & Safety) complete, Phase 12 begins: Distributed Coordination & Multi-Agent Collaboration. The AgentRegistry is the directory service at the foundation of all multi-agent interaction.

---

Component Map

┌────────────────────────────────────────────────────────────┐
│                    AgentRegistry                           │
│  register() ──► _records{agent_id: AgentRecord}           │
│  heartbeat() ──► refresh last_heartbeat                   │
│  _evict_loop ──► OFFLINE if heartbeat > timeout           │
│  find_by_capability(tag) ──► [AgentRecord, ...]           │
└───────────────────────┬────────────────────────────────────┘
                        │
        ┌───────────────┼────────────────────┐
        ▼               ▼                    ▼
 NegotiationEngine  CollaborationChannel  CoalitionFormation
  (Phase 12.2)        (Phase 12.3)         (Phase 12.5)

---

AgentStatus FSM

AVAILABLE ──► BUSY ──► DRAINING ──► OFFLINE
    ▲                                  │
    └──────────── heartbeat ───────────┘

The eviction loop transitions any agent that misses heartbeat_timeout_s (default 30 s) into OFFLINE. A fresh heartbeat call recovers it back to AVAILABLE.

---

AgentCapability Design

@dataclass(frozen=True)
class AgentCapability:
    tag: str            # semantic label: "planning", "nlp", "vision"
    version: str        # semver: "1.0.0"
    max_concurrency: int  # max parallel tasks for this capability

Capabilities are additive — an agent can declare multiple tags. find_by_capability("planning") returns all AVAILABLE agents whose capability set contains any AgentCapability with tag == "planning".

---

Concurrent Safety

All mutations go through a single asyncio.Lock. The eviction loop acquires the lock only briefly per iteration — O(n) scan with replace() (frozen dataclass copy-on-write).

async with self._lock:
    for aid, rec in list(self._records.items()):  # snapshot keys
        if now - rec.last_heartbeat > timeout and rec.status != OFFLINE:
            self._records[aid] = replace(rec, status=AgentStatus.OFFLINE)
            _REGISTRY_OFFLINE_TOTAL.inc()

---

Prometheus Metrics

Metric	Type	Sample PromQL
asi_registry_agents_total	Gauge	asi_registry_agents_total
asi_registry_available_total	Gauge	asi_registry_available_total / asi_registry_agents_total
asi_registry_offline_total	Counter	rate(asi_registry_offline_total[5m])
asi_registry_heartbeat_latency_seconds	Histogram	histogram_quantile(0.99, ...)
asi_registry_lookup_duration_seconds	Histogram	histogram_quantile(0.95, ...)

---

Open Questions

1. Persistence: In-memory implementation loses registrations on restart. Should AgentRegistry support pluggable backends (Redis, etcd, Postgres)?
2. DID verification: AgentRecord.did is stored but not verified. Should register() reject records with invalid DIDs, or defer verification to Phase 12.3 (CollaborationChannel)?
3. Cross-registry federation: If two ASI-Build clusters run their own AgentRegistry, how do they sync entries — pull gossip or push replication?

Thoughts welcome! 👇