Q&A: Phase 12.1 AgentRegistry — heartbeat tuning, capability lookup, DID integration, and federation sync

[web3guru888]

Q&A — Phase 12.1 AgentRegistry

Common configuration and integration questions for AgentRegistry.

---

Q1: How do I tune heartbeat_timeout_s for a LAN vs. WAN deployment?

A: Scale timeout to your expected RTT + processing jitter:

Deployment	Recommended heartbeat_timeout_s	evict_interval_s
Localhost / Docker	5 s	2 s
Same datacenter LAN	15 s	5 s
Multi-region WAN	60 s	20 s
Unreliable mobile edge	120 s	30 s

Rule of thumb: heartbeat_timeout_s ≥ 3× your agent's heartbeat call frequency.

---

Q2: Can an OFFLINE agent re-register, or must it use heartbeat()?

A: Either works. Calling heartbeat(agent_id) on an OFFLINE agent resets last_heartbeat and transitions status back to AVAILABLE. register() with the same agent_id does an upsert — it overwrites the existing record (useful if endpoint or capabilities changed).

---

Q3: find_by_capability returns a list — how do I pick the best agent for a task?

A: The default sort is FIFO (registered_at ascending). For smarter selection:

# Least-loaded: sort by estimated queue depth from metadata
peers = await registry.find_by_capability("planning")
best = min(peers, key=lambda r: int(r.metadata.get("queue_depth", "0")))

Phase 12.2 (NegotiationEngine) will implement a full contract-net protocol where peers bid on tasks — find_by_capability is its candidate-enumeration step.

---

Q4: How does AgentRegistry integrate with the FederationGateway from Phase 9?

A: Four-step flow:

1. Remote peer calls FederationGateway.join() → gateway creates an AgentRecord with the peer's DID and endpoint.
2. Gateway calls registry.register(record) → peer is now discoverable.
3. Peer sends periodic heartbeats via gateway → registry.heartbeat(agent_id) keeps it AVAILABLE.
4. GoalDecomposer calls registry.find_by_capability("federation") to enumerate gateway-reachable peers for task delegation.

---

Q5: What does AgentRecord.did look like in practice?

A: A W3C DID string, e.g.:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

The registry stores it verbatim — Phase 12.3 (CollaborationChannel) verifies the DID document's public key against message signatures. You can use None for agents that don't support DID-based auth.

---

Q6: How do I add custom metadata (e.g. region, tier) to an AgentRecord?

A: Use the metadata: Mapping[str, str] field:

record = AgentRecord(
    agent_id="node-eu-west-1",
    display_name="EU West Planning Node",
    endpoint="https://eu-west-1.asi.example/api",
    capabilities=frozenset([AgentCapability(tag="planning", version="2.0.0")]),
    metadata={"region": "eu-west-1", "tier": "premium", "queue_depth": "0"},
)
await registry.register(record)

Update metadata via a fresh register() call (upsert). Phase 12.5 (CoalitionFormation) uses region metadata to prefer geographically co-located agents.

---

Q7: What Grafana panels should I set up for AgentRegistry health?

A:

# Panel 1: Agent availability ratio
expr: asi_registry_available_total / clamp_min(asi_registry_agents_total, 1)
type: stat
thresholds: [warn: 0.7, critical: 0.5]

# Panel 2: Offline eviction rate
expr: rate(asi_registry_offline_total[5m])
type: time_series

# Panel 3: Heartbeat p99 latency
expr: histogram_quantile(0.99, rate(asi_registry_heartbeat_latency_seconds_bucket[5m]))
type: time_series

# Alert: Too many agents offline
expr: (asi_registry_agents_total - asi_registry_available_total) / clamp_min(asi_registry_agents_total, 1) > 0.5
for: 2m
labels: {severity: critical}
annotations: {summary: ">50% of agents offline"}