Skip to content
Ishvana Ishvana Docs

Get Optimal Agent

GET
/api/agents/metrics/optimal

Get optimal agent recommendation for a given task.

Analyzes available agents and recommends the best one for the specified task based on capabilities matching, current load, and performance history.

Query Parameters:

  • task_type: Type of task (e.g., “code_review”, “testing”, “creative_writing”)
  • task_description: Optional detailed task description for better matching

Returns:

  • recommended_agent: ID of the optimal agent
  • confidence_score: Confidence in recommendation (0.0-1.0)
  • reasoning: Explanation for the recommendation
  • alternatives: List of alternative agents with scores

Raises:

  • HTTPException 503: If backend service unavailable
  • HTTPException 500: For unexpected errors

Example Response:

{
    "recommended_agent": "HAWKEN",
    "confidence_score": 0.92,
    "reasoning": "HAWKEN has lowest load and specializes in creative writing",
    "alternatives": [
        {"agent_id": "HAWKEN", "confidence_score": 0.75, "reasoning": "Secondary option"}
    ]
}

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
task_type
Task Type
string
default: general
task_description
Any of:
string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

AgentOptimalResponse

Optimal agent recommendation response model.

Provides the best agent recommendation for a given task along with confidence score, reasoning, and alternative options. Generated by boot coordinator’s agent selection algorithm based on capabilities matching and current load.

Fields: recommended_agent: ID of the optimal agent for the task confidence_score: Confidence in recommendation (0.0-1.0) reasoning: Explanation for why this agent was selected alternatives: List of alternative agents with their scores

Used By: - GET /api/agents/optimal endpoint - boot coordinator agent selection algorithm - Task routing decision making - Agent recommendation UI

object
recommendedAgent
required
Recommendedagent
string
confidenceScore
required
Confidencescore
number
reasoning
required
Reasoning
string
alternatives
required
Alternatives
Array<object>
AgentAlternativeInfo

Alternative agent recommendation information.

Provides details about alternative agents that could handle a task with their confidence scores and reasoning for agent selection.

Fields: agent_id: Alternative agent identifier confidence_score: Confidence in this alternative (0.0-1.0) reasoning: Explanation for why this agent is an alternative capabilities: List of relevant capabilities current_load: Current workload of alternative agent

Used By: - AgentOptimalResponse.alternatives - Agent selection UI - Load balancing decisions

object
agentId
required
Agentid

Alternative agent ID

string
confidenceScore
required
Confidencescore

Confidence score (0.0-1.0)

number
<= 1
reasoning
Any of:
string
capabilities
Any of:
Array<string>
currentLoad
Any of:
number
<= 1

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object