Discovery API

Endpoints for agent registration and capability discovery.

Capabilities

Register Capability

POST /api/v1/discovery/capabilities

Request:

{
  "agent_id": "document-processor",
  "capability": "document.ocr",
  "metadata": {
    "supported_formats": ["pdf", "png", "jpg"],
    "max_file_size_mb": 50,
    "version": "1.0.0"
  },
  "groups": ["production", "us-east"]
}

Response:

{
  "data": {
    "id": "cap_xxx",
    "agent_id": "document-processor",
    "capability": "document.ocr",
    "metadata": {...},
    "groups": ["production", "us-east"],
    "created_at": "2026-01-01T00:00:00Z"
  }
}

List Capabilities

GET /api/v1/discovery/capabilities?agent_id={agent_id}

Get Capability

GET /api/v1/discovery/capabilities/{capability_id}

Deregister Capability

DELETE /api/v1/discovery/capabilities/{capability_id}

Deregister Agent

Remove all capabilities for an agent:

DELETE /api/v1/discovery/agents/{agent_id}

Agent Discovery

Find Agents by Capability

GET /api/v1/discovery/agents?capability={capability}&strategy={strategy}

Query parameters:

• capability - Capability name to search for
• strategy - Routing strategy (round_robin, least_loaded, random, etc.)
• group - Filter by group
• limit - Max results

Response:

{
  "data": {
    "agents": [
      {
        "agent_id": "document-processor-1",
        "capability": "document.ocr",
        "metadata": {...},
        "load": 0.3,
        "health": "healthy",
        "last_heartbeat": "2026-01-01T12:00:00Z"
      }
    ]
  }
}

Semantic Search

POST /api/v1/discovery/search

Request:

{
  "query": "I need to extract text from PDF documents",
  "top_k": 5,
  "min_score": 0.6
}

Response:

{
  "data": {
    "results": [
      {
        "capability": {
          "id": "cap_xxx",
          "name": "document.ocr",
          "agent_id": "document-processor",
          "metadata": {...}
        },
        "similarity_score": 0.85
      }
    ]
  }
}

Health

Send Heartbeat

POST /api/v1/discovery/heartbeat

Request:

{
  "agent_id": "document-processor",
  "load": 0.3,
  "metadata": {
    "active_tasks": 5,
    "memory_mb": 512
  }
}

Get Agent Health

GET /api/v1/discovery/agents/{agent_id}/health

Response:

{
  "data": {
    "agent_id": "document-processor",
    "status": "healthy",
    "load": 0.3,
    "last_heartbeat": "2026-01-01T12:00:00Z",
    "uptime_seconds": 86400
  }
}

Groups

List Groups

GET /api/v1/discovery/groups

Get Agents in Group

GET /api/v1/discovery/groups/{group_name}/agents

Routing Strategies

Strategy	Description
round_robin	Cycle through agents
least_loaded	Pick lowest load agent
random	Random selection
first_available	First healthy agent
weighted	Weight-based selection
latency	Lowest latency agent
trust	Highest trust score