Skip to content
Ishvana Ishvana Docs

Get Agent Capabilities

GET
/api/agents/capabilities

Retrieve agent capabilities with real load metrics and routing suggestions.

For each registered agent, returns capability details plus liveness (from agent_activity_service), real current_load (derived in metrics_manager.get_agent_metrics from recent request history), a load-based availability label, and a strategy-driven routing_suggestions map.

Returns:

  • agents: list of agent detail records, one per registered agent:
    • agent_id / name — registry name
    • description — one-line role summary from the registry
    • capabilities — declared capability strings
    • status — liveness: "available" when the activity service reports awake, "offline" otherwise. The schema allows "busy" as well, reserved for future use.
    • current_load — 0.0-1.0 if measured, null when unknown (the distinction matters: null means “no signal”, 0.0 means “measured idle”)
    • availability — load-based: "Busy" when current_load >= etherforce.agent_busy_threshold, "Available" otherwise, null when current_load is unknown
    • confidence_score / task_match_score / estimated_completion_time — always null (task-relative signals not computable here)
  • routing_suggestions: map of capability → recommended agent name. Strategy sourced from etherforce.agent_routing_strategy ("first_match" or "least_loaded").
  • load_balancing: map of agent name → measured current_load. Agents with unknown load are omitted — consumers should treat a missing key as “unknown”, never as “idle”.

Raises:

  • HTTPException 503: If the backend service is not initialized (propagated from get_backend_service).

Example Response:

{
  "agents": [
    {
      "agentId": "hawken",
      "name": "hawken",
      "description": "Creative writing specialist — prose generation, style analysis, narrative construction.",
      "capabilities": ["creative_writing", "style_analysis"],
      "status": "available",
      "currentLoad": 0.33,
      "availability": "Available"
    }
  ],
  "routingSuggestions": {"creative_writing": "hawken"},
  "loadBalancing": {"hawken": 0.33}
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

AgentCapabilitiesResponse

Agent capabilities and routing response model with frontend compatibility.

Provides comprehensive information about all available divine agents including their capabilities, specializations, and routing suggestions. Used by boot coordinator orchestrator for intelligent task-agent matching and load balancing.

Fields: agents: List of all divine agents with detailed capabilities routing_suggestions: Recommended agent routing for specific task types load_balancing: Load balancing scores per agent (0.0-1.0)

Used By: - GET /api/agents/capabilities endpoint - boot coordinator orchestrator for agent selection - Task routing and load balancing - Agent discovery and capabilities matching - Multi-agent workflow planning

object
agents
Agents

Array of all divine agents with their details

Array<object>
AgentDetails

Detailed agent information model for capabilities and availability.

Provides comprehensive information about a divine agent’s capabilities, specializations, current workload, and availability status. Used by boot coordinator orchestrator for optimal agent selection and task routing.

Fields: agent_id: Unique agent identifier name: Human-readable agent name description: Agent’s purpose, role, and specialization capabilities: General capabilities (e.g., “code_analysis”, “testing”) specializations: Specialized skills (e.g., “python”, “react”, “performance”) status: Current availability (available, busy, offline) confidence_score: Confidence in handling current task (0.0-1.0) task_match_score: How well agent matches task requirements (0.0-1.0) current_load: Current workload level (0.0 = idle, 1.0 = max capacity) availability: Detailed availability description estimated_completion_time: Estimated task completion time in seconds

Used By: - boot coordinator orchestrator for agent selection - GET /api/agents/capabilities endpoint - Agent routing and load balancing - Task-agent matching algorithms - Multi-agent workflow planning

object
agentId
Agentid

Unique agent identifier

string
""
name
Name

Human-readable agent name

string
""
description
Description

Agent’s purpose and role

string
""
capabilities
Capabilities

List of general capabilities

Array<string>
specializations
Specializations

Specialized skills and domains

Array<string>
status
Status

Liveness status from the activity service (available, busy, offline)

string
default: offline
Allowed values: available busy offline
confidenceScore
Any of:
number
<= 1
taskMatchScore
Any of:
number
<= 1
currentLoad
Any of:
number
<= 1
availability
Any of:
string
Allowed values: Busy Available
estimatedCompletionTime
Any of:
integer
routingSuggestions
Routingsuggestions

Suggested agent routing for tasks

object
key
additional properties
string
loadBalancing
Loadbalancing

Load balancing scores for agents

object
key
additional properties
number