fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/agents/workflow/router_agent.py

@@ -0,0 +1,353 @@
+"""
+Router agent implementation using the BaseAgent adapter pattern.
+
+This provides a simplified implementation that routes messages to agents
+by determining the best agent for a request and dispatching to it.
+"""
+
+from typing import TYPE_CHECKING, List, Optional, Tuple, Type
+
+from mcp import Tool
+from opentelemetry import trace
+from pydantic import BaseModel
+
+from fast_agent.agents.agent_types import AgentConfig, AgentType
+from fast_agent.agents.llm_agent import LlmAgent
+from fast_agent.core.exceptions import AgentConfigError
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.core.prompt import Prompt
+from fast_agent.interfaces import FastAgentLLMProtocol, LLMFactoryProtocol, ModelT
+from fast_agent.types import PromptMessageExtended, RequestParams
+
+if TYPE_CHECKING:
+    from a2a.types import AgentCard
+
+    from fast_agent.context import Context
+
+logger = get_logger(__name__)
+
+# Simple system instruction for the router
+ROUTING_SYSTEM_INSTRUCTION = """
+You are a highly accurate request router that directs incoming requests to the most appropriate agent.
+Analyze each request and determine which specialized agent would be best suited to handle it based on their capabilities.
+
+Follow these guidelines:
+- Carefully match the request's needs with each agent's capabilities and description
+- Select the single most appropriate agent for the request
+- Provide your confidence level (high, medium, low) and brief reasoning for your selection
+"""
+
+# Default routing instruction with placeholders for context (AgentCard JSON)
+ROUTING_AGENT_INSTRUCTION = """
+Select from the following agents to handle the request:
+<fastagent:agents>
+[
+{context}
+]
+</fastagent:agents>
+
+You must respond with the 'name' of one of the agents listed above.
+
+"""
+
+
+class RoutingResponse(BaseModel):
+    """Model for the structured routing response from the LLM."""
+
+    agent: str
+    confidence: str
+    reasoning: str | None = None
+
+
+class RouterAgent(LlmAgent):
+    """
+    A simplified router that uses an LLM to determine the best agent for a request,
+    then dispatches the request to that agent and returns the response.
+    """
+
+    @property
+    def agent_type(self) -> AgentType:
+        """Return the type of this agent."""
+        return AgentType.ROUTER
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        agents: List[LlmAgent],
+        routing_instruction: str | None = None,
+        context: "Context | None" = None,
+        default_request_params: RequestParams | None = None,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize a RouterAgent.
+
+        Args:
+            config: Agent configuration or name
+            agents: List of agents to route between
+            routing_instruction: Optional custom routing instruction
+            context: Optional application context
+            default_request_params: Optional default request parameters
+            **kwargs: Additional keyword arguments to pass to BaseAgent
+        """
+        super().__init__(config=config, context=context, **kwargs)
+
+        if not agents:
+            raise AgentConfigError("At least one agent must be provided")
+
+        self.agents = agents
+        self.routing_instruction = routing_instruction
+        self.agent_map = {agent.name: agent for agent in agents}
+
+        # Set up base router request parameters with just the base instruction for now
+        base_params = {"systemPrompt": ROUTING_SYSTEM_INSTRUCTION, "use_history": False}
+
+        if default_request_params:
+            merged_params = default_request_params.model_copy(update=base_params)
+        else:
+            merged_params = RequestParams(**base_params)
+
+        self._default_request_params = merged_params
+
+    async def initialize(self) -> None:
+        """Initialize the router and all agents."""
+        if not self.initialized:
+            await super().initialize()
+
+            # Initialize all agents if not already initialized
+            for agent in self.agents:
+                if not agent.initialized:
+                    await agent.initialize()
+
+            complete_routing_instruction = await self._generate_routing_instruction(
+                self.agents, self.routing_instruction
+            )
+
+            # Update the system prompt to include the routing instruction with agent cards
+            combined_system_prompt = (
+                ROUTING_SYSTEM_INSTRUCTION + "\n\n" + complete_routing_instruction
+            )
+            self._default_request_params.systemPrompt = combined_system_prompt
+            self.instruction = combined_system_prompt
+
+    async def shutdown(self) -> None:
+        """Shutdown the router and all agents."""
+        await super().shutdown()
+
+        # Shutdown all agents
+        for agent in self.agents:
+            try:
+                await agent.shutdown()
+            except Exception as e:
+                logger.warning(f"Error shutting down agent: {str(e)}")
+
+    @staticmethod
+    async def _generate_routing_instruction(
+        agents: List[LlmAgent], routing_instruction: Optional[str] = None
+    ) -> str:
+        """
+        Generate the complete routing instruction with agent cards.
+
+        Args:
+            agents: List of agents to include in routing instruction
+            routing_instruction: Optional custom routing instruction template
+
+        Returns:
+            Complete routing instruction with agent cards formatted
+        """
+        # Generate agent descriptions
+        agent_descriptions = []
+        for agent in agents:
+            agent_card: AgentCard = await agent.agent_card()
+            agent_descriptions.append(
+                agent_card.model_dump_json(
+                    include={"name", "description", "skills"}, exclude_none=True
+                )
+            )
+
+        context = ",\n".join(agent_descriptions)
+
+        # Format the routing instruction
+        instruction_template = routing_instruction or ROUTING_AGENT_INSTRUCTION
+        return instruction_template.format(context=context)
+
+    async def attach_llm(
+        self,
+        llm_factory: LLMFactoryProtocol,
+        model: str | None = None,
+        request_params: RequestParams | None = None,
+        **additional_kwargs,
+    ) -> FastAgentLLMProtocol:
+        return await super().attach_llm(
+            llm_factory, model, request_params, verb="Routing", **additional_kwargs
+        )
+
+    async def generate_impl(
+        self,
+        messages: List[PromptMessageExtended],
+        request_params: Optional[RequestParams] = None,
+        tools: List[Tool] | None = None,
+    ) -> PromptMessageExtended:
+        """
+        Route the request to the most appropriate agent and return its response.
+
+        Args:
+            normalized_messages: Already normalized list of PromptMessageExtended
+            request_params: Optional request parameters
+
+        Returns:
+            The response from the selected agent
+        """
+
+        # implementation note. the duplication between generated and structured
+        # is probably the most readable. alt could be a _get_route_agent or
+        # some form of dynamic dispatch.. but only if this gets more complex
+        tracer = trace.get_tracer(__name__)
+        with tracer.start_as_current_span(f"Routing: '{self.name}' generate"):
+            route, warn = await self._route_request(messages[-1])
+
+            if not route:
+                return Prompt.assistant(warn or "No routing result or warning received")
+
+            # Get the selected agent
+            agent: LlmAgent = self.agent_map[route.agent]
+
+            # Dispatch the request to the selected agent
+            # discarded request_params: use llm defaults for subagents
+            telemetry_arguments = {
+                "agent": route.agent,
+                "confidence": route.confidence,
+                "reasoning": route.reasoning,
+            }
+            async with self.workflow_telemetry.start_step(
+                "router.delegate",
+                server_name=self.name,
+                arguments=telemetry_arguments,
+            ) as step:
+                if route.reasoning:
+                    await step.update(message=route.reasoning)
+                result = await agent.generate_impl(messages)
+                await step.finish(
+                    True,
+                    text=f"Delegated to {agent.name}",
+                )
+                return result
+
+    async def structured_impl(
+        self,
+        messages: List[PromptMessageExtended],
+        model: Type[ModelT],
+        request_params: Optional[RequestParams] = None,
+    ) -> Tuple[ModelT | None, PromptMessageExtended]:
+        """
+        Route the request to the most appropriate agent and parse its response.
+
+        Args:
+            messages: Messages to route
+            model: Pydantic model to parse the response into
+            request_params: Optional request parameters
+
+        Returns:
+            The parsed response from the selected agent, or None if parsing fails
+        """
+
+        tracer = trace.get_tracer(__name__)
+        with tracer.start_as_current_span(f"Routing: '{self.name}' structured"):
+            route, warn = await self._route_request(messages[-1])
+
+            if not route:
+                return None, Prompt.assistant(
+                    warn or "No routing result or warning received (structured)"
+                )
+
+            # Get the selected agent
+            agent: LlmAgent = self.agent_map[route.agent]
+
+            # Dispatch the request to the selected agent
+            telemetry_arguments = {
+                "agent": route.agent,
+                "confidence": route.confidence,
+                "reasoning": route.reasoning,
+            }
+            async with self.workflow_telemetry.start_step(
+                "router.delegate_structured",
+                server_name=self.name,
+                arguments=telemetry_arguments,
+            ) as step:
+                if route.reasoning:
+                    await step.update(message=route.reasoning)
+                structured_response = await agent.structured_impl(messages, model, request_params)
+                await step.finish(
+                    True,
+                    text=f"{agent.name} produced structured output",
+                )
+                return structured_response
+
+    async def _route_request(
+        self, message: PromptMessageExtended
+    ) -> Tuple[RoutingResponse | None, str | None]:
+        """
+        Determine which agent to route the request to.
+
+        Args:
+            request: The request to route
+
+        Returns:
+            RouterResult containing the selected agent, or None if no suitable agent was found
+        """
+        if not self.agents:
+            logger.error("No agents available for routing")
+            raise AgentConfigError("No agents available for routing - fatal error")
+
+        # go straight to agent if only one available
+        if len(self.agents) == 1:
+            return RoutingResponse(
+                agent=self.agents[0].name, confidence="high", reasoning="Only one agent available"
+            ), None
+
+        assert self._llm
+        # Display the user's routing request
+        self.display.show_user_message(message.first_text(), name=self.name)
+
+        # No need to add routing instruction here - it's already in the system prompt
+        response, _ = await self._llm.structured(
+            [message],
+            RoutingResponse,
+            self._default_request_params,
+        )
+
+        warn: str | None = None
+        if not response:
+            warn = "No routing response received from LLM"
+        elif response.agent not in self.agent_map:
+            warn = f"A response was received, but the agent {response.agent} was not known to the Router"
+
+        if warn:
+            logger.warning(warn)
+            return None, warn
+        else:
+            assert response
+            logger.info(
+                f"Routing structured request to agent: {response.agent or 'error'} (confidence: {response.confidence or ''})"
+            )
+
+            routing_message = f"Routing to: {response.agent}"
+            if response.reasoning:
+                routing_message += f" ({response.reasoning})"
+
+            # Convert highlight_items to highlight_index
+            agent_keys = list(self.agent_map.keys())
+            highlight_index = None
+            try:
+                highlight_index = agent_keys.index(response.agent)
+            except ValueError:
+                pass
+
+            await self.display.show_assistant_message(
+                routing_message,
+                bottom_items=agent_keys,
+                highlight_index=highlight_index,
+                name=self.name,
+            )
+
+            return response, None

fast_agent/cli/__main__.py

@@ -0,0 +1,73 @@
+import asyncio
+import json
+import sys
+
+from fast_agent.cli.constants import GO_SPECIFIC_OPTIONS, KNOWN_SUBCOMMANDS
+from fast_agent.cli.main import app
+
+# if the arguments would work with "go" we'll just route to it
+
+
+def main():
+    """Main entry point that handles auto-routing to 'go' command."""
+    try:
+        loop = asyncio.get_event_loop()
+
+        def _log_asyncio_exception(loop: asyncio.AbstractEventLoop, context: dict) -> None:
+            import logging
+
+            logger = logging.getLogger("fast_agent.asyncio")
+
+            message = context.get("message", "(no message)")
+            task = context.get("task")
+            future = context.get("future")
+            handle = context.get("handle")
+            source_traceback = context.get("source_traceback")
+            exception = context.get("exception")
+
+            details = {
+                "message": message,
+                "task": repr(task) if task else None,
+                "future": repr(future) if future else None,
+                "handle": repr(handle) if handle else None,
+                "source_traceback": [str(frame) for frame in source_traceback] if source_traceback else None,
+            }
+
+            logger.error("Unhandled asyncio error: %s", message)
+            logger.error("Asyncio context: %s", json.dumps(details, indent=2))
+
+            if exception:
+                logger.exception("Asyncio exception", exc_info=exception)
+
+        loop.set_exception_handler(_log_asyncio_exception)
+    except RuntimeError:
+        # No running loop yet (rare for sync entry), safe to ignore
+        pass
+    # Check if we should auto-route to 'go'
+    if len(sys.argv) > 1:
+        # Check if first arg is not already a subcommand
+        first_arg = sys.argv[1]
+
+        # Only auto-route if any known go-specific options are present
+        has_go_options = any(
+            (arg in GO_SPECIFIC_OPTIONS) or any(arg.startswith(opt + "=") for opt in GO_SPECIFIC_OPTIONS)
+            for arg in sys.argv[1:]
+        )
+
+        if first_arg not in KNOWN_SUBCOMMANDS and has_go_options:
+            # Find where to insert 'go' - before the first go-specific option
+            insert_pos = 1
+            for i, arg in enumerate(sys.argv[1:], 1):
+                if (arg in GO_SPECIFIC_OPTIONS) or any(
+                    arg.startswith(opt + "=") for opt in GO_SPECIFIC_OPTIONS
+                ):
+                    insert_pos = i
+                    break
+            # Auto-route to go command
+            sys.argv.insert(insert_pos, "go")
+
+    app()
+
+
+if __name__ == "__main__":
+    main()

fast_agent/cli/commands/acp.py

@@ -0,0 +1,159 @@
+"""Dedicated entry point for running FastAgent in ACP mode."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from fast_agent.cli.commands import serve
+from fast_agent.cli.commands.go import (
+    collect_stdio_commands,
+    resolve_instruction_option,
+    run_async_agent,
+)
+
+app = typer.Typer(
+    help="Run FastAgent as an ACP stdio server without specifying --transport=acp explicitly.",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+
+ROOT_SUBCOMMANDS = {
+    "go",
+    "serve",
+    "setup",
+    "check",
+    "auth",
+    "bootstrap",
+    "quickstart",
+}
+
+
+@app.callback(invoke_without_command=True, no_args_is_help=False)
+def run_acp(
+    ctx: typer.Context,
+    name: str = typer.Option("fast-agent-acp", "--name", help="Name for the ACP server"),
+    instruction: str | None = typer.Option(
+        None, "--instruction", "-i", help="Path to file or URL containing instruction for the agent"
+    ),
+    config_path: str | None = typer.Option(None, "--config-path", "-c", help="Path to config file"),
+    servers: str | None = typer.Option(
+        None, "--servers", help="Comma-separated list of server names to enable from config"
+    ),
+    urls: str | None = typer.Option(
+        None, "--url", help="Comma-separated list of HTTP/SSE URLs to connect to"
+    ),
+    auth: str | None = typer.Option(
+        None, "--auth", help="Bearer token for authorization with URL-based servers"
+    ),
+    model: str | None = typer.Option(
+        None, "--model", "--models", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
+    ),
+    skills_dir: Path | None = typer.Option(
+        None,
+        "--skills-dir",
+        "--skills",
+        help="Override the default skills directory",
+    ),
+    npx: str | None = typer.Option(
+        None, "--npx", help="NPX package and args to run as MCP server (quoted)"
+    ),
+    uvx: str | None = typer.Option(
+        None, "--uvx", help="UVX package and args to run as MCP server (quoted)"
+    ),
+    stdio: str | None = typer.Option(
+        None, "--stdio", help="Command to run as STDIO MCP server (quoted)"
+    ),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        "-d",
+        help="Description used for the exposed send tool (use {agent} to reference the agent name)",
+    ),
+    host: str = typer.Option(
+        "0.0.0.0",
+        "--host",
+        help="Host address to bind when using HTTP or SSE transport",
+    ),
+    port: int = typer.Option(
+        8000,
+        "--port",
+        help="Port to use when running as a server with HTTP or SSE transport",
+    ),
+    shell: bool = typer.Option(
+        False,
+        "--shell",
+        "-x",
+        help="Enable a local shell runtime and expose the execute tool (bash or pwsh).",
+    ),
+    instance_scope: serve.InstanceScope = typer.Option(
+        serve.InstanceScope.SHARED,
+        "--instance-scope",
+        help="Control how ACP clients receive isolated agent instances (shared, connection, request)",
+    ),
+    no_permissions: bool = typer.Option(
+        False,
+        "--no-permissions",
+        help="Disable tool permission requests (allow all tool executions without asking)",
+    ),
+) -> None:
+    """
+    Run FastAgent with ACP transport defaults.
+
+    This mirrors `fast-agent serve --transport acp` but provides a shorter command and
+    a distinct default name so ACP-specific tooling can integrate more easily.
+    """
+    stdio_commands = collect_stdio_commands(npx, uvx, stdio)
+    shell_enabled = shell
+
+    resolved_instruction, agent_name = resolve_instruction_option(instruction)
+
+    run_async_agent(
+        name=name,
+        instruction=resolved_instruction,
+        config_path=config_path,
+        servers=servers,
+        urls=urls,
+        auth=auth,
+        model=model,
+        message=None,
+        prompt_file=None,
+        stdio_commands=stdio_commands,
+        agent_name=agent_name,
+        skills_directory=skills_dir,
+        shell_enabled=shell_enabled,
+        mode="serve",
+        transport=serve.ServeTransport.ACP.value,
+        host=host,
+        port=port,
+        tool_description=description,
+        instance_scope=instance_scope.value,
+        permissions_enabled=not no_permissions,
+    )
+
+
+def main() -> None:
+    """Console script entrypoint for `fast-agent-acp`."""
+    # Override Click's UsageError exit code from 2 to 1 for consistency
+    import click
+
+    click.exceptions.UsageError.exit_code = 1
+
+    args = sys.argv[1:]
+    if args and args[0] in ROOT_SUBCOMMANDS:
+        from fast_agent.cli.__main__ import main as root_cli_main
+
+        root_cli_main()
+        return
+    try:
+        # Run the Typer app without triggering automatic sys.exit so we can
+        # guarantee error output goes to stderr with a non-zero exit code.
+        app(standalone_mode=False)
+    except click.ClickException as exc:
+        # Preserve Typer's rich formatting when available, otherwise fall back to plain text.
+        try:
+            import typer.rich_utils as rich_utils
+
+            rich_utils.rich_format_error(exc)
+        except Exception:
+            exc.show(file=sys.stderr)
+        sys.exit(getattr(exc, "exit_code", 1))