Skip to content

06 - Agent Registry

Goal: Demonstrate Agent Discovery & Metadata Management - maintaining a centralized registry of active agents with their capability contracts, priorities, and runtime metadata for multi-agent coordination and orchestration.

DIR Alignment: DIR Architectural Pattern §2.3 (Agent Discovery & Registry), ROA Manifesto §3.1 (Responsibility Contracts)

Concepts Demonstrated

Concept DIR Section Implementation
Agent Registry §2.3 Central catalog of all active agents in the system
Capability Contract ROA §3.1 Role, capabilities, supported operations
Priority Management §2.3 Numerical priority for conflict resolution and scheduling
Agent Discovery §2.3 list_agents() returns all active agent IDs
Metadata Retrieval §2.3 get_agent_contract() fetches full capability contract
Version Tracking Implementation Each agent contract includes version for evolution tracking
Status Management Implementation Agents marked ACTIVE/INACTIVE for lifecycle management

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Agent Registry                              │
│  "Central catalog of agents, capabilities, and coordination data"   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  register_agent(agent_id, contract, priority)               │    │
│  │  • Stores agent capability contract                         │    │
│  │  • Assigns priority for orchestration                       │    │
│  │  • Marks agent as ACTIVE                                    │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Capability Contract                                        │    │
│  │  {                                                          │    │
│  │    "role": "MONITOR|EXECUTOR|STRATEGIST",                   │    │
│  │    "capabilities": ["action1", "action2", ...],             │    │
│  │    "supported_instruments": [...],                          │    │
│  │    "version": "1.0.0"                                       │    │
│  │  }                                                          │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  list_agents() → [agent_id1, agent_id2, ...]                │    │
│  │  Discovery: Find all ACTIVE agents                          │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  get_agent_contract(agent_id) → contract                    │    │
│  │  Inspection: Retrieve full capability contract              │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  get_agent_priority(agent_id) → priority_int                │    │
│  │  Coordination: Higher priority = higher precedence          │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  SQLite Backend:                                                    │
│  • agent_id (PK), contract (JSON), priority, status                 │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

How to run

From repo root:

pip install -e .
python samples/06_agent_registry/run.py

Scenario Demonstrated

Agent Registration and Discovery

  1. Initialize Registry: Create SQLite-backed AgentRegistry
  2. Register High-Priority Monitor:
  3. agent_id: "agent_supervisor"
  4. role: "MONITOR"
  5. capabilities: ["halt_system", "audit_log"]
  6. priority: 100 (highest in system)
  7. version: "1.0.0"
  8. Register Standard Executor:
  9. agent_id: "agent_trader_btc"
  10. role: "EXECUTOR"
  11. capabilities: ["place_order", "cancel_order"]
  12. supported_instruments: ["BTC-USD"]
  13. priority: 10 (standard priority)
  14. version: "2.1.0"
  15. Discovery: List all active agents
  16. Inspection: Retrieve contract and priority for specific agent
  17. Verification: Confirm data persistence and retrieval

Key Classes and Methods

from dir_core.agent_registry import AgentRegistry

# Initialize
registry = AgentRegistry(db_path)

# Register Agent with Capability Contract
registry.register_agent(
    agent_id="agent_trader_btc",
    contract={
        "role": "EXECUTOR",
        "capabilities": ["place_order", "cancel_order"],
        "supported_instruments": ["BTC-USD"],
        "version": "2.1.0"
    },
    priority=10
)

# Discovery: List all active agents
agents = registry.list_agents()
# Returns: ["agent_supervisor", "agent_trader_btc", ...]

# Inspection: Get agent capability contract
contract = registry.get_agent_contract("agent_trader_btc")
# Returns: {"role": "EXECUTOR", "capabilities": [...], ...}

# Coordination: Get agent priority
priority = registry.get_agent_priority("agent_trader_btc")
# Returns: 10

Database Schema

CREATE TABLE agent_registry (
    agent_id TEXT PRIMARY KEY,
    contract JSON,
    priority INTEGER DEFAULT 0,
    status TEXT DEFAULT 'ACTIVE',
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

Expected Output

======================================================================
Agent Registry Demonstration
======================================================================
Database: D:\...\samples\06_agent_registry\data\registry.db

[Registration] Registering agents...
INFO Registered agent: agent_supervisor (priority=100)
INFO Registered agent: agent_trader_btc (priority=10)

[Discovery] Active Agents: ['agent_supervisor', 'agent_trader_btc']
   ✅ Listing successful

[Inspection] Checking 'agent_trader_btc'...
   Priority: 10
   Contract:
   {
     'role': 'EXECUTOR',
     'capabilities': ['place_order', 'cancel_order'],
     'supported_instruments': ['BTC-USD'],
     'version': '2.1.0'
   }

SUCCESS: Agent registry persisted and retrieved data correctly.

Why Agent Registry Matters

from dir_core Architectural Pattern §2.3 and ROA Manifesto §3.1:

"In a multi-agent system, agents must discover each other's capabilities without tight coupling. The Agent Registry provides a central catalog where agents declare their Capability Contracts during initialization. This enables dynamic orchestration, capability-based routing, and runtime introspection without hardcoded dependencies."

Key Insights:

  1. Capability Contracts:
  2. Declaration of what an agent can do, not how it does it
  3. Includes role (MONITOR, EXECUTOR, STRATEGIST), capabilities, supported operations
  4. Version tracking for safe evolution and compatibility checking

  5. Similar to interface definitions in OOP or API contracts in microservices

  6. Dynamic Discovery:

  7. No hardcoded agent dependencies
  8. Runtime queries: "Which agents can handle BTC-USD trades?"
  9. Enables hot-swapping: replace agent without system restart

  10. Supports A/B testing: run multiple agent versions simultaneously

  11. Priority-Based Coordination:

  12. Numerical priority for conflict resolution
  13. Higher priority agents override lower priority in disputes
  14. Supervisor agents (priority 100) can halt executor agents (priority 10)

  15. Enables hierarchical decision-making (escalation chains)

  16. Status Management:

  17. Agents marked ACTIVE or INACTIVE
  18. Lifecycle tracking: when agent registered, last update
  19. Graceful shutdown: deactivate agent without deleting contract

  20. Debugging: inspect inactive agents to understand past system states

  21. Centralized vs. Distributed:

  22. Current implementation: centralized SQLite registry
  23. Production: could use distributed registry (etcd, Consul, ZooKeeper)
  24. Tradeoff: simplicity vs. high availability

Real-World Use Cases:

Financial Trading Platform: 

# Register specialized agents
registry.register_agent("agent_risk_monitor", {
    "role": "MONITOR",
    "capabilities": ["halt_trading", "adjust_limits"],
    "monitored_metrics": ["var", "drawdown", "leverage"]
}, priority=100)

registry.register_agent("agent_btc_trader", {
    "role": "EXECUTOR",
    "capabilities": ["place_order", "cancel_order"],
    "instruments": ["BTC-USD", "BTC-EUR"]
}, priority=10)

# Orchestration logic
if market_volatility > 0.8:
    # Find all executors and pause them
    for agent_id in registry.list_agents():
        contract = registry.get_agent_contract(agent_id)
        if contract.get("role") == "EXECUTOR":
            send_command(agent_id, "PAUSE")

Cloud Infrastructure Orchestration: 

registry.register_agent("agent_autoscaler", {
    "role": "STRATEGIST",
    "capabilities": ["scale_up", "scale_down"],
    "managed_services": ["api-gateway", "worker-pool"]
}, priority=50)

registry.register_agent("agent_cost_optimizer", {
    "role": "MONITOR",
    "capabilities": ["recommend_downsize", "flag_waste"],
    "optimization_targets": ["cost", "performance"]
}, priority=30)

Insurance Claims Processing: 

registry.register_agent("agent_fraud_detector", {
    "role": "MONITOR",
    "capabilities": ["flag_suspicious", "request_review"],
    "detection_methods": ["pattern", "anomaly", "network"]
}, priority=80)

registry.register_agent("agent_auto_approver", {
    "role": "EXECUTOR",
    "capabilities": ["approve_claim", "calculate_payout"],
    "claim_types": ["auto", "property"],
    "max_amount": 5000.0
}, priority=20)

Orchestration Patterns Enabled:

  1. Capability-Based Routing: 

    # Find agent that can handle specific instrument
for agent_id in registry.list_agents():
    contract = registry.get_agent_contract(agent_id)
    instruments = contract.get("supported_instruments", [])
    if "BTC-USD" in instruments:
        route_decision_to(agent_id)

  2. Priority-Based Override: 

    # Higher priority agent can override lower priority decisions
proposals = get_all_proposals(dfid)
proposals.sort(key=lambda p: registry.get_agent_priority(p.agent_id), reverse=True)
final_decision = proposals[0]  # Highest priority wins

  3. Role-Based Filtering: 

    # Only consult MONITORs for escalation decisions
monitors = [
    agent_id for agent_id in registry.list_agents()
    if registry.get_agent_contract(agent_id).get("role") == "MONITOR"
]

  4. Version-Based Routing (A/B Testing): 

    # Route 10% of traffic to new agent version
contract = registry.get_agent_contract("agent_trader_btc_v2")
if contract.get("version") == "2.1.0" and random.random() < 0.1:
    use_agent("agent_trader_btc_v2")
else:
    use_agent("agent_trader_btc")

Integration with DIR Pattern:

System Startup:
  → Agents initialize
  → Each agent calls registry.register_agent() with contract
  → Registry persists contracts in SQLite

Runtime Decision Flow:
  → Context arrives requiring decision
  → Orchestrator queries registry.list_agents()
  → Filters agents by capability/role
  → Routes context to matching agents
  → Agents emit proposals
  → Orchestrator uses priority for conflict resolution

Agent Shutdown:
  → Agent calls registry.deactivate(agent_id)
  → Registry marks status = INACTIVE
  → Future queries exclude this agent

Comparison to Alternatives:

❌ Hardcoded dependencies: Brittle, can't add agents without code changes
❌ Service discovery only (e.g., DNS): No capability metadata, just endpoints
❌ Message passing without registry: Agents broadcast capabilities, inefficient
✅ Centralized Registry: Fast lookups, metadata-rich, auditable registration history

The Agent Registry is the phonebook of the multi-agent system - it answers "Who can do what?" enabling dynamic, loosely-coupled orchestration.