dataflow.api.routes.agent_discovery_routes_enhanced¶

Fixed Agent Discovery Routes using Haive Core’s unified discovery system.

This module provides FastAPI routes for discovering and managing agents using the unified discovery system from haive-core. It replaces the previous implementation that had duplicated discovery logic.

Key Features:

Uses HaiveComponentDiscovery for consistent agent discovery
Supports both v1 (config-based) and v2 (class-based) agents
Provides caching for improved performance
Rich metadata extraction including schemas and documentation
Categorization and filtering capabilities

Examples

from fastapi import FastAPI from haive.dataflow.api.routes.agent_discovery_routes_fixed import router

app = FastAPI() app.include_router(router, prefix=”/api/v1”)

# Endpoints available: # GET /api/v1/agents - List all agents # GET /api/v1/agents/search - Search agents # GET /api/v1/agents/{agent_name} - Get specific agent # GET /api/v1/agents/stats - Get agent statistics

Note

This implementation fixes the circular import issue between component_registry and haive_discovery by using the lazy import pattern implemented in haive-core.

Classes¶

`AgentDetailResponse`	Detailed response for a specific agent.
`AgentInfo`	Information about a discovered agent.
`AgentListResponse`	Response for agent list endpoints.

Functions¶

`categorize_agents`(agents)	Categorize agents by their type/category.
`component_to_agent_info`(component)	Convert a ComponentInfo to AgentInfo.
`discover_all_agents`([force_refresh])	Discover all agents using the unified discovery system.
`extract_agent_metadata`(agent)	Extract rich metadata from an agent component.
`get_agent_details`(agent_name)	Get detailed information about a specific agent.
`get_agent_stats`()	Get statistics about discovered agents.
`get_discovery_instance`()	Get or create a cached discovery instance.
`list_agents`([agent_type, category, force_refresh])	List all available agents with optional filtering.
`search_agents`([query, agent_type])	Search agents by name or description.

Module Contents¶

class dataflow.api.routes.agent_discovery_routes_enhanced.AgentDetailResponse(/, **data)¶

Bases: pydantic.BaseModel

Detailed response for a specific agent.

Includes all AgentInfo fields plus additional details about the component discovery and file location.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class dataflow.api.routes.agent_discovery_routes_enhanced.AgentInfo(/, **data)¶

Bases: pydantic.BaseModel

Information about a discovered agent.

Parameters:: data (Any)

name¶: Agent identifier name (lowercase, without suffix).

description¶: Human-readable description of the agent.

module¶: Full module path to the agent.

agent_type¶: Type of agent (‘v1’ for config-based, ‘v2’ for class-based).

version¶: Agent version string.

config_class¶: Name of config class for v1 agents.

category¶: Agent category for grouping.

metadata¶: Additional metadata from discovery.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class dataflow.api.routes.agent_discovery_routes_enhanced.AgentListResponse(/, **data)¶

Bases: pydantic.BaseModel

Response for agent list endpoints.

Parameters:: data (Any)

agents¶: List of discovered agents.

count¶: Total number of agents.

v1_count¶: Number of v1 (config-based) agents.

v2_count¶: Number of v2 (class-based) agents.

discovery_method¶: Method used for discovery.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

dataflow.api.routes.agent_discovery_routes_enhanced.categorize_agents(agents)¶

Categorize agents by their type/category.

Parameters:: agents (list[haive.dataflow.api.routes.utils.haive_discovery.ComponentInfo]) – List of agent components to categorize.
Returns:: Dictionary mapping category names to lists of agents in that category.
Return type:: Dict[str, List[ComponentInfo]]

Note

Categories are inferred from: - Metadata ‘category’ field - Module path components - Agent type (v1 vs v2)

dataflow.api.routes.agent_discovery_routes_enhanced.component_to_agent_info(component)¶

Convert a ComponentInfo to AgentInfo.

Parameters:: component (haive.dataflow.api.routes.utils.haive_discovery.ComponentInfo) – ComponentInfo object from discovery.
Returns:: Structured agent information for API response.
Return type:: AgentInfo

dataflow.api.routes.agent_discovery_routes_enhanced.discover_all_agents(force_refresh=False)¶

Discover all agents using the unified discovery system.

Parameters:: force_refresh (bool) – If True, bypasses cache and rediscovers all agents.
Returns:: List of discovered agent components from both haive-agents and haive-core engine directories.
Return type:: List[ComponentInfo]

Note

This function discovers agents from multiple locations: - haive-agents package (v2 agents) - haive-core engine configs (v1 agents)

dataflow.api.routes.agent_discovery_routes_enhanced.extract_agent_metadata(agent)¶

Extract rich metadata from an agent component.

Parameters:

agent (haive.dataflow.api.routes.utils.haive_discovery.ComponentInfo) – ComponentInfo object representing an agent.

Returns:

Enhanced metadata including:

version: Agent version
category: Agent category
capabilities: List of agent capabilities
required_tools: Tools required by the agent
is_v1_agent: Whether this is a v1 (config) agent
is_v2_agent: Whether this is a v2 (class) agent
schema: Input/output schema if available

Return type:

Dict[str, Any]

Note

Attempts to extract schema information from both v1 configs and v2 agent classes using inspection and attribute access.

async dataflow.api.routes.agent_discovery_routes_enhanced.get_agent_details(agent_name)¶

Get detailed information about a specific agent.

Parameters:

agent_name (str) – Name of the agent to retrieve details for. Case-insensitive matching is used.

Returns:

Detailed agent information including:

Full metadata and capabilities
Module and file paths
Schema information
Version and category details

Return type:

AgentDetailResponse

Raises:

HTTPException – 404 if agent is not found.

Examples

GET /api/v1/agents/SimpleAgent

async dataflow.api.routes.agent_discovery_routes_enhanced.get_agent_stats()¶

Get statistics about discovered agents.

Returns:

Statistics including:

total_agents: Total number of discovered agents
v1_agents: Number of config-based agents
v2_agents: Number of class-based agents
categories: Dictionary of category counts
discovery_sources: List of discovery source paths
discovery_method: Method used for discovery
last_updated: Timestamp of last discovery

Return type:

Dict[str, Any]

Examples

GET /api/v1/agents/stats

Response: {

“total_agents”: 25, “v1_agents”: 10, “v2_agents”: 15, “categories”: {

“research”: 5, “chat”: 8, “task”: 12

}

}

dataflow.api.routes.agent_discovery_routes_enhanced.get_discovery_instance()¶

Get or create a cached discovery instance.

Returns:: Cached discovery instance for the haive root.
Return type:: HaiveComponentDiscovery

Note

Uses a global singleton pattern to avoid repeated initialization of the discovery system which can be expensive.

async dataflow.api.routes.agent_discovery_routes_enhanced.list_agents(agent_type=Query(None, description='Filter by agent type (v1, v2)'), category=Query(None, description='Filter by category'), force_refresh=Query(False, description='Force refresh discovery cache'))¶

List all available agents with optional filtering.

Parameters:

agent_type (str | None) – Optional filter for agent type (‘v1’ for config-based, ‘v2’ for class-based agents).
category (str | None) – Optional category filter (e.g., ‘research’, ‘chat’).
force_refresh (bool) – If True, forces rediscovery of all agents.

Returns:

Response containing:

List of discovered agents with metadata
Count statistics (total, v1, v2)
Discovery method information

Return type:

AgentListResponse

Examples

GET /api/v1/agents?agent_type=v2&category=research

async dataflow.api.routes.agent_discovery_routes_enhanced.search_agents(query=Query(..., description='Search query'), agent_type=Query(None, description='Filter by agent type'))¶

Search agents by name or description.

Parameters:

query (str) – Search string to match against agent names and descriptions. Case-insensitive partial matching is used.
agent_type (str | None) – Optional filter for agent type (‘v1’ or ‘v2’).

Returns:

Filtered list of agents matching the search criteria.

Return type:

AgentListResponse

Examples

GET /api/v1/agents/search?query=chat&agent_type=v2