Discovery Hub

Discovery Hub maintains a registry of all agents and their capabilities, enabling dynamic discovery and intelligent routing.

Key Features

• Capability registry - Agents declare what they can do
• Semantic search - Find agents using natural language
• Health monitoring - Track agent availability
• Load balancing - Route to optimal agents
• Agent groups - Logical grouping for routing

Registering Capabilities

Agents register their capabilities on startup:

await client.discovery.register_capability(
    agent_id="document-ocr-001",
    capability="document.ocr",
    metadata={
        "supported_formats": ["pdf", "png", "jpg"],
        "max_file_size_mb": 50,
        "languages": ["en", "es", "fr"],
        "version": "2.1.0"
    }
)

An agent can register multiple capabilities:

capabilities = [
    ("document.ocr", {"formats": ["pdf", "png"]}),
    ("document.translate", {"languages": ["en", "es", "fr"]}),
    ("document.summarize", {"max_length": 5000})
]

for cap, metadata in capabilities:
    await client.discovery.register_capability(
        agent_id="document-processor",
        capability=cap,
        metadata=metadata
    )

Finding Agents

By Capability

Find agents that have a specific capability:

agents = await client.discovery.find_agents(
    capability="document.ocr",
    routing_strategy="least_loaded"
)

if agents:
    target = agents[0]
    print(f"Found: {target.agent_id} (load: {target.load})")

Semantic Search

Use natural language to find agents:

results = await client.discovery.search(
    query="I need an agent that can extract text from PDFs",
    top_k=5,
    min_score=0.6
)

for result in results:
    print(f"{result.capability.name}: {result.similarity_score:.2f}")

Routing Strategies

Choose how to select among matching agents:

Strategy	Description
round_robin	Cycle through agents evenly
least_loaded	Pick agent with lowest load
random	Random selection
first_available	First healthy agent
weighted	Based on agent weights
latency	Lowest response latency
trust	Highest trust score

# Route to the agent with lowest load
agents = await client.discovery.find_agents(
    capability="document.ocr",
    routing_strategy="least_loaded"
)

# Route based on trust score
agents = await client.discovery.find_agents(
    capability="financial.analysis",
    routing_strategy="trust"
)

Health Monitoring

Discovery Hub monitors agent health:

• Heartbeats - Agents send periodic heartbeats
• Health checks - Active probing of agent endpoints
• Automatic removal - Unhealthy agents are excluded from routing

# Send a heartbeat
await client.discovery.heartbeat(
    agent_id="my-agent",
    load=0.3,  # Current load (0-1)
    metadata={"active_tasks": 5}
)

# Check agent health
health = await client.discovery.get_health(agent_id="agent-123")
print(f"Status: {health.status}")  # healthy, degraded, unhealthy

Agent Groups

Organize agents into logical groups:

# Register agent in a group
await client.discovery.register_capability(
    agent_id="ocr-agent-1",
    capability="document.ocr",
    groups=["production", "us-east"]
)

# Find agents in a specific group
agents = await client.discovery.find_agents(
    capability="document.ocr",
    group="us-east"
)

Deregistration

Remove an agent from the registry:

await client.discovery.deregister(agent_id="my-agent")

Or deregister a specific capability:

await client.discovery.deregister_capability(
    agent_id="my-agent",
    capability="document.ocr"
)

Next Steps

• Agent Discovery Guide - Best practices for registration
• API Reference - Complete API documentation