RoutingAgent

class RoutingAgent:
    """
    Routes user requests to appropriate agents with intelligent disambiguation.

    Currently handles Code agent routing. Future: Jira, Docker, etc.

    Flow:
    1. Analyze query with LLM to detect agent and parameters
    2. If parameters unknown, ask user for clarification
    3. Recursively re-analyze with user's response as added context
    4. Once resolved, return configured agent ready to execute
    """

    def __init__(
        self,
        api_mode: bool = False,
        output_handler=None,
        **agent_kwargs,
    ):
        """
        Initialize routing agent with LLM client.

        Args:
            api_mode: If True, skip interactive questions and use defaults/best-guess
            output_handler: Optional OutputHandler for streaming events
            **agent_kwargs: Additional kwargs to pass to created agents
        """
        ...

    def process_query(
        self,
        query: str,
        conversation_history: Optional[List[Dict[str, str]]] = None,
        execute: bool = None,
        workspace_root: Optional[str] = None,
        **kwargs,
    ):
        """
        Process query with optional conversation history from disambiguation rounds.

        Args:
            query: Original user query
            conversation_history: List of conversation turns
            execute: If True, execute agent and return result
                    If False, return agent instance (CLI behavior)
                    If None, uses api_mode (True for API, False for CLI)
            workspace_root: Optional workspace directory
            **kwargs: Additional kwargs passed to agent.process_query()

        Returns:
            If execute=False: Configured agent instance ready to execute
            If execute=True: Execution result from agent.process_query()
        """
        ...

    def _analyze_with_llm(
        self, conversation_history: List[Dict[str, str]]
    ) -> Dict[str, Any]:
        """
        Analyze query with LLM to determine agent and parameters.

        Returns:
            Analysis dict with agent, parameters, confidence, reasoning
        """
        ...

    def _has_unknowns(self, analysis: Dict[str, Any]) -> bool:
        """Check if analysis has unknown parameters that need disambiguation."""
        ...

    def _generate_clarification_question(self, analysis: Dict[str, Any]) -> str:
        """Generate natural language clarification question based on unknowns."""
        ...

    def _create_agent(self, analysis: Dict[str, Any]) -> Agent:
        """Create configured agent based on analysis."""
        ...

from gaia.agents.routing.agent import RoutingAgent

router = RoutingAgent()

# First call - needs clarification
agent = router.process_query("Create a web app")

# Router asks: "What language/framework would you like to use?"
# User responds: "Next.js"
# Recursive call resolves parameters

# Returns configured CodeAgent
result = agent.process_query("Create a web app")

router = RoutingAgent(api_mode=True, output_handler=sse_handler)

# Auto-executes with defaults, no interactive questions
result = router.process_query("Create Express API")

# Returns execution result directly
print(result.status)

# Clear request, no disambiguation needed
agent = router.process_query("Create a Next.js blog with TypeScript")

# Router detects: language=typescript, project_type=fullstack

def test_routing_agent_creation():
    """Test router initialization."""
    router = RoutingAgent()
    assert router is not None

def test_language_detection():
    """Test LLM-based language detection."""
    router = RoutingAgent(api_mode=True)
    agent = router.process_query("Create a Python calculator", execute=False)

    assert isinstance(agent, CodeAgent)
    assert agent.language == "python"

def test_api_mode_defaults():
    """Test API mode uses defaults without questions."""
    router = RoutingAgent(api_mode=True)
    result = router.process_query("Create an app")

    # Should complete without user input
    assert result is not None

[project]
dependencies = [
    "gaia.llm.llm_client",
    "gaia.agents.code.agent",
]