Skip to content
Ishvana Ishvana Docs

List Agents

GET
/api/agents/

List all available divine agents in the Ishvana ecosystem.

Returns the union of the analysis-agent registry roster and the live backend.agent_models map, deduplicated and sorted alphabetically.

Discovery Sources (merged, not prioritized):

  1. Analysis-agent registry — authoritative static roster from :func:backend.core.services.agent_registry.list_analysis_agents
  2. Backend agent_models — dynamically-registered agents held on the running DivinityEngineService instance

Query Parameters: None

Returns: ListAgentsResponse containing:

  • agents: Sorted, deduplicated list of agent identifiers
  • total: Total number of discovered agents
  • status: Operation status ("success")
  • source: "backend_and_registry_combined"

Raises:

  • HTTPException 503: If the backend service is not initialized

Example Response:

{
    "agents": ["gamemaster", "hawken", "ishvana", "lagan", "lorekeeper"],
    "total": 5,
    "status": "success",
    "source": "backend_and_registry_combined"
}

Usage:

  • Agent discovery for routing decisions
  • Frontend agent selection UI population
  • System monitoring and validation
  • Orchestration planning

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

ListAgentsResponse

Agent listing response model for basic agent discovery.

Returns comprehensive list of all available divine agents with metadata about data source and total count. Used by basic agent listing endpoint with ORCHESTRATOR orchestrator integration and intelligent fallback mechanisms.

Fields: agents: List of agent identifiers total: Total number of agents discovered status: Operation status (always ‘success’ — failures raise HTTPException) source: Data source identifier for transparency

Used By: - GET /api/agents/management/ endpoint - Agent discovery for routing decisions - Frontend agent selection UI

object
agents
required
Agents

List of available divine agent identifiers

Array<string>
total
required
Total

Total number of agents in the system

integer
status
required
Status

Operation status (always ‘success’; failures raise HTTPException)

string
Allowed value: success
source
required
Source

Data source: ‘service_registry’ when served purely from the analysis-agent registry, or ‘backend_and_registry_combined’ when merged with the live backend agent_models map

string
Allowed values: service_registry backend_and_registry_combined