fast-agent-mcp 0.2.16__py3-none-any.whl → 0.2.18__py3-none-any.whl

mcp_agent/agents/workflow/router_agent.py

@@ -5,9 +5,8 @@ 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 typing import TYPE_CHECKING, Callable, List, Optional, Tuple, Type
 
-from mcp.types import TextContent
 from pydantic import BaseModel
 
 from mcp_agent.agents.agent import Agent
@@ -17,10 +16,12 @@ from mcp_agent.core.exceptions import AgentConfigError
 from mcp_agent.core.prompt import Prompt
 from mcp_agent.core.request_params import RequestParams
 from mcp_agent.logging.logger import get_logger
-from mcp_agent.mcp.interfaces import ModelT
+from mcp_agent.mcp.interfaces import AugmentedLLMProtocol, ModelT
 from mcp_agent.mcp.prompt_message_multipart import PromptMessageMultipart
 
 if TYPE_CHECKING:
+    from a2a_types.types import AgentCard
+
     from mcp_agent.context import Context
 
 logger = get_logger(__name__)
@@ -36,47 +37,17 @@ Follow these guidelines:
 - Provide your confidence level (high, medium, low) and brief reasoning for your selection
 """
 
-# Default routing instruction with placeholders for context and request
+# Default routing instruction with placeholders for context (AgentCard JSON)
 DEFAULT_ROUTING_INSTRUCTION = """
-You are a highly accurate request router that directs incoming requests to the most appropriate agent.
-
-<fastagent:data>
+Select from the following agents to handle the request:
 <fastagent:agents>
+[
 {context}
+]
 </fastagent:agents>
 
-<fastagent:request>
-{request}
-</fastagent:request>
-</fastagent:data>
-
-Your task is to analyze the request and determine the most appropriate agent from the options above.
-
-<fastagent:instruction>
-Respond with JSON following the schema below:
-{{
-    "type": "object",
-    "required": ["agent", "confidence", "reasoning"],
-    "properties": {{
-        "agent": {{
-            "type": "string",
-            "description": "The exact name of the selected agent"
-        }},
-        "confidence": {{
-            "type": "string",
-            "enum": ["high", "medium", "low"],
-            "description": "Your confidence level in this selection"
-        }},
-        "reasoning": {{
-            "type": "string",
-            "description": "Brief explanation for your selection"
-        }}
-    }}
-}}
-
-Supply only the JSON with no preamble. Use "reasoning" field to describe actions. NEVER EMIT CODE FENCES. 
-
-</fastagent:instruction>
+You must respond with the 'name' of one of the agents listed above.
+
 """
 
 
@@ -85,18 +56,7 @@ class RoutingResponse(BaseModel):
 
     agent: str
     confidence: str
-    reasoning: Optional[str] = None
-
-
-class RouterResult(BaseModel):
-    """Router result with agent reference and confidence rating."""
-
-    result: BaseAgent
-    confidence: str
-    reasoning: Optional[str] = None
-
-    # Allow Agent objects to be stored without serialization
-    model_config = {"arbitrary_types_allowed": True}
+    reasoning: str | None = None
 
 
 class RouterAgent(BaseAgent):
@@ -142,9 +102,7 @@ class RouterAgent(BaseAgent):
         # Set up base router request parameters
         base_params = {"systemPrompt": ROUTING_SYSTEM_INSTRUCTION, "use_history": False}
 
-        # Merge with provided defaults if any
         if default_request_params:
-            # Start with defaults and override with router-specific settings
             merged_params = default_request_params.model_copy(update=base_params)
         else:
             merged_params = RequestParams(**base_params)
@@ -174,32 +132,16 @@ class RouterAgent(BaseAgent):
             except Exception as e:
                 logger.warning(f"Error shutting down agent: {str(e)}")
 
-    async def _get_routing_result(
+    async def attach_llm(
         self,
-        messages: List[PromptMessageMultipart],
-    ) -> Optional[RouterResult]:
-        """
-        Common method to extract request and get routing result.
-
-        Args:
-            messages: The messages to extract request from
-
-        Returns:
-            RouterResult containing the selected agent, or None if no suitable agent found
-        """
-        if not self.initialized:
-            await self.initialize()
-
-        # Extract the request text from the last message
-        request = messages[-1].all_text() if messages else ""
-
-        # Determine which agent to route to
-        routing_result = await self._route_request(request)
-
-        if not routing_result:
-            logger.warning("Could not determine appropriate agent for this request")
-
-        return routing_result
+        llm_factory: type[AugmentedLLMProtocol] | Callable[..., AugmentedLLMProtocol],
+        model: str | None = None,
+        request_params: RequestParams | None = None,
+        **additional_kwargs,
+    ) -> AugmentedLLMProtocol:
+        return await super().attach_llm(
+            llm_factory, model, request_params, verb="Routing", **additional_kwargs
+        )
 
     async def generate(
         self,
@@ -216,32 +158,21 @@ class RouterAgent(BaseAgent):
         Returns:
             The response from the selected agent
         """
-        routing_result = await self._get_routing_result(multipart_messages)
-
-        if not routing_result:
-            return PromptMessageMultipart(
-                role="assistant",
-                content=[
-                    TextContent(
-                        type="text", text="Could not determine appropriate agent for this request."
-                    )
-                ],
-            )
 
-        # Get the selected agent
-        selected_agent = routing_result.result
+        route, warn = await self._route_request(multipart_messages[-1])
 
-        # Log the routing decision
-        logger.info(
-            f"Routing request to agent: {selected_agent.name} (confidence: {routing_result.confidence})"
-        )
+        if not route:
+            return Prompt.assistant(warn or "No routing result or warning received")
+
+        # Get the selected agent
+        agent: Agent = self.agent_map[route.agent]
 
         # Dispatch the request to the selected agent
-        return await selected_agent.generate(multipart_messages, request_params)
+        return await agent.generate(multipart_messages, request_params)
 
     async def structured(
         self,
-        prompt: List[PromptMessageMultipart],
+        multipart_messages: List[PromptMessageMultipart],
         model: Type[ModelT],
         request_params: Optional[RequestParams] = None,
     ) -> Tuple[ModelT | None, PromptMessageMultipart]:
@@ -256,23 +187,22 @@ class RouterAgent(BaseAgent):
         Returns:
             The parsed response from the selected agent, or None if parsing fails
         """
-        routing_result = await self._get_routing_result(prompt)
+        route, warn = await self._route_request(multipart_messages[-1])
 
-        if not routing_result:
-            return None, Prompt.assistant("No routing result")
+        if not route:
+            return None, Prompt.assistant(
+                warn or "No routing result or warning received (structured)"
+            )
 
         # Get the selected agent
-        selected_agent = routing_result.result
-
-        # Log the routing decision
-        logger.info(
-            f"Routing structured request to agent: {selected_agent.name} (confidence: {routing_result.confidence})"
-        )
+        agent: Agent = self.agent_map[route.agent]
 
         # Dispatch the request to the selected agent
-        return await selected_agent.structured(prompt, model, request_params)
+        return await agent.structured(multipart_messages, model, request_params)
 
-    async def _route_request(self, request: str) -> Optional[RouterResult]:
+    async def _route_request(
+        self, message: PromptMessageMultipart
+    ) -> Tuple[RoutingResponse | None, str | None]:
         """
         Determine which agent to route the request to.
 
@@ -283,49 +213,53 @@ class RouterAgent(BaseAgent):
             RouterResult containing the selected agent, or None if no suitable agent was found
         """
         if not self.agents:
-            logger.warning("No agents available for routing")
-            return None
+            logger.error("No agents available for routing")
+            raise AgentConfigError("No agents available for routing - fatal error")
 
         # If only one agent is available, use it directly
         if len(self.agents) == 1:
-            return RouterResult(
-                result=self.agents[0], confidence="high", reasoning="Only one agent available"
-            )
+            return RoutingResponse(
+                agent=self.agents[0].name, confidence="high", reasoning="Only one agent available"
+            ), None
 
         # Generate agent descriptions for the context
         agent_descriptions = []
-        for i, agent in enumerate(self.agents, 1):
-            description = agent.instruction if isinstance(agent.instruction, str) else ""
-            agent_descriptions.append(f"{i}. Name: {agent.name} - {description}")
+        for agent in self.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\n".join(agent_descriptions)
+        context = ",\n".join(agent_descriptions)
 
         # Format the routing prompt
         routing_instruction = self.routing_instruction or DEFAULT_ROUTING_INSTRUCTION
-        prompt_text = routing_instruction.format(context=context, request=request)
-
-        # Create multipart message for the router
-        prompt = PromptMessageMultipart(
-            role="user", content=[TextContent(type="text", text=prompt_text)]
-        )
+        routing_instruction = routing_instruction.format(context=context)
 
-        # Get structured response from LLM
         assert self._llm
+        mutated = message.model_copy(deep=True)
+        mutated.add_text(routing_instruction)
         response, _ = await self._llm.structured(
-            [prompt], RoutingResponse, self._default_request_params
+            [mutated],
+            RoutingResponse,
+            self._default_request_params,
         )
 
+        warn: str | None = None
         if not response:
-            logger.warning("No routing response received from LLM")
-            return None
+            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"
 
-        # Look up the agent by name
-        selected_agent = self.agent_map.get(response.agent)
-
-        if not selected_agent:
-            logger.warning(f"Agent '{response.agent}' not found in available agents")
-            return None
+        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 ''})"
+            )
 
-        return RouterResult(
-            result=selected_agent, confidence=response.confidence, reasoning=response.reasoning
-        )
+            return response, None

mcp_agent/app.py

@@ -1,7 +1,6 @@
 import asyncio
 from contextlib import asynccontextmanager
-from datetime import timedelta
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Type, TypeVar
+from typing import TYPE_CHECKING, Dict, Optional, Type, TypeVar
 
 from mcp_agent.config import Settings
 from mcp_agent.context import Context, cleanup_context, initialize_context
@@ -174,125 +173,3 @@ class MCPApp:
             yield self
         finally:
             await self.cleanup()
-
-    def workflow(self, cls: Type, *args, workflow_id: str | None = None, **kwargs) -> Type:
-        """
-        Decorator for a workflow class. By default it's a no-op,
-        but different executors can use this to customize behavior
-        for workflow registration.
-
-        Example:
-            If Temporal is available & we use a TemporalExecutor,
-            this decorator will wrap with temporal_workflow.defn.
-        """
-        decorator_registry = self.context.decorator_registry
-        execution_engine = self.engine
-        workflow_defn_decorator = decorator_registry.get_workflow_defn_decorator(execution_engine)
-
-        if workflow_defn_decorator:
-            return workflow_defn_decorator(cls, *args, **kwargs)
-
-        cls._app = self
-        self._workflows[workflow_id or cls.__name__] = cls
-
-        # Default no-op
-        return cls
-
-    def workflow_run(self, fn: Callable[..., R]) -> Callable[..., R]:
-        """
-        Decorator for a workflow's main 'run' method.
-        Different executors can use this to customize behavior for workflow execution.
-
-        Example:
-            If Temporal is in use, this gets converted to @workflow.run.
-        """
-
-        decorator_registry = self.context.decorator_registry
-        execution_engine = self.engine
-        workflow_run_decorator = decorator_registry.get_workflow_run_decorator(execution_engine)
-
-        if workflow_run_decorator:
-            return workflow_run_decorator(fn)
-
-        # Default no-op
-        def wrapper(*args, **kwargs):
-            # no-op wrapper
-            return fn(*args, **kwargs)
-
-        return wrapper
-
-    def workflow_task(
-        self,
-        name: str | None = None,
-        schedule_to_close_timeout: timedelta | None = None,
-        retry_policy: Dict[str, Any] | None = None,
-        **kwargs: Any,
-    ) -> Callable[[Callable[..., R]], Callable[..., R]]:
-        """
-        Decorator to mark a function as a workflow task,
-        automatically registering it in the global activity registry.
-
-        Args:
-            name: Optional custom name for the activity
-            schedule_to_close_timeout: Maximum time the task can take to complete
-            retry_policy: Retry policy configuration
-            **kwargs: Additional metadata passed to the activity registration
-
-        Returns:
-            Decorated function that preserves async and typing information
-
-        Raises:
-            TypeError: If the decorated function is not async
-            ValueError: If the retry policy or timeout is invalid
-        """
-
-        def decorator(func: Callable[..., R]) -> Callable[..., R]:
-            if not asyncio.iscoroutinefunction(func):
-                raise TypeError(f"Function {func.__name__} must be async.")
-
-            actual_name = name or f"{func.__module__}.{func.__qualname__}"
-            timeout = schedule_to_close_timeout or timedelta(minutes=10)
-            metadata = {
-                "activity_name": actual_name,
-                "schedule_to_close_timeout": timeout,
-                "retry_policy": retry_policy or {},
-                **kwargs,
-            }
-            activity_registry = self.context.task_registry
-            activity_registry.register(actual_name, func, metadata)
-
-            setattr(func, "is_workflow_task", True)
-            setattr(func, "execution_metadata", metadata)
-
-            # TODO: saqadri - determine if we need this
-            # Preserve metadata through partial application
-            # @functools.wraps(func)
-            # async def wrapper(*args: Any, **kwargs: Any) -> R:
-            #     result = await func(*args, **kwargs)
-            #     return cast(R, result)  # Ensure type checking works
-
-            # # Add metadata that survives partial application
-            # wrapper.is_workflow_task = True  # type: ignore
-            # wrapper.execution_metadata = metadata  # type: ignore
-
-            # # Make metadata accessible through partial
-            # def __getattr__(name: str) -> Any:
-            #     if name == "is_workflow_task":
-            #         return True
-            #     if name == "execution_metadata":
-            #         return metadata
-            #     raise AttributeError(f"'{func.__name__}' has no attribute '{name}'")
-
-            # wrapper.__getattr__ = __getattr__  # type: ignore
-
-            # return wrapper
-
-            return func
-
-        return decorator
-
-    def is_workflow_task(self, func: Callable[..., Any]) -> bool:
-        """
-        Check if a function is marked as a workflow task.
-        This gets set for functions that are decorated with @workflow_task."""
-        return bool(getattr(func, "is_workflow_task", False))

mcp_agent/cli/commands/go.py

@@ -0,0 +1,133 @@
+"""Run an interactive agent directly from the command line."""
+
+import asyncio
+import sys
+from typing import List, Optional
+
+import typer
+
+from mcp_agent.core.fastagent import FastAgent
+
+app = typer.Typer(
+    help="Run an interactive agent directly from the command line without creating an agent.py file"
+)
+
+async def _run_agent(
+    name: str = "FastAgent CLI",
+    instruction: str = "You are a helpful AI Agent.",
+    config_path: Optional[str] = None,
+    server_list: Optional[List[str]] = None,
+    model: Optional[str] = None,
+) -> None:
+    """Async implementation to run an interactive agent."""
+
+    # Create the FastAgent instance with CLI arg parsing enabled
+    # It will automatically parse args like --model, --quiet, etc.
+    fast_kwargs = {
+        "name": name,
+        "config_path": config_path,
+        "ignore_unknown_args": True,
+    }
+    
+    fast = FastAgent(**fast_kwargs)
+
+    # Define the agent with specified parameters
+    agent_kwargs = {"instruction": instruction}
+    if server_list:
+        agent_kwargs["servers"] = server_list
+    if model:
+        agent_kwargs["model"] = model
+    
+    @fast.agent(**agent_kwargs)
+    async def cli_agent():
+        async with fast.run() as agent:
+            await agent.interactive()
+
+    # Run the agent
+    await cli_agent()
+
+def run_async_agent(
+    name: str, 
+    instruction: str, 
+    config_path: Optional[str] = None, 
+    servers: Optional[str] = None,
+    model: Optional[str] = None
+):
+    """Run the async agent function with proper loop handling."""
+    server_list = servers.split(',') if servers else None
+    
+    # Check if we're already in an event loop
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # We're inside a running event loop, so we can't use asyncio.run
+            # Instead, create a new loop
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+    except RuntimeError:
+        # No event loop exists, so we'll create one
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    
+    try:
+        loop.run_until_complete(_run_agent(
+            name=name, 
+            instruction=instruction, 
+            config_path=config_path, 
+            server_list=server_list,
+            model=model
+        ))
+    finally:
+        try:
+            # Clean up the loop
+            tasks = asyncio.all_tasks(loop)
+            for task in tasks:
+                task.cancel()
+            
+            # Run the event loop until all tasks are done
+            if sys.version_info >= (3, 7):
+                loop.run_until_complete(asyncio.gather(*tasks, return_exceptions=True))
+            loop.run_until_complete(loop.shutdown_asyncgens())
+            loop.close()
+        except Exception:
+            pass
+
+@app.callback(invoke_without_command=True)
+def go(
+    ctx: typer.Context,
+    name: str = typer.Option("FastAgent CLI", "--name", help="Name for the agent"),
+    instruction: str = typer.Option(
+        "You are a helpful AI Agent.", "--instruction", "-i", help="Instruction for the agent"
+    ),
+    config_path: Optional[str] = typer.Option(
+        None, "--config-path", "-c", help="Path to config file"
+    ),
+    servers: Optional[str] = typer.Option(
+        None, "--servers", help="Comma-separated list of server names to enable from config"
+    ),
+    model: Optional[str] = typer.Option(
+        None, "--model", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
+    ),
+) -> None:
+    """
+    Run an interactive agent directly from the command line.
+
+    Example:
+        fast-agent go --model=haiku --instruction="You are a coding assistant" --servers=fetch,filesystem
+
+    This will start an interactive session with the agent, using the specified model
+    and instruction. It will use the default configuration from fastagent.config.yaml
+    unless --config-path is specified.
+
+    Common options:
+        --model: Override the default model (e.g., --model=haiku)
+        --quiet: Disable progress display and logging
+        --servers: Comma-separated list of server names to enable from config
+    """
+    run_async_agent(
+        name=name, 
+        instruction=instruction, 
+        config_path=config_path, 
+        servers=servers,
+        model=model
+    )

mcp_agent/cli/commands/setup.py

@@ -15,7 +15,7 @@ FASTAGENT_CONFIG_TEMPLATE = """
 # Takes format:
 #   <provider>.<model_string>.<reasoning_effort?> (e.g. anthropic.claude-3-5-sonnet-20241022 or openai.o3-mini.low)
 # Accepts aliases for Anthropic Models: haiku, haiku3, sonnet, sonnet35, opus, opus3
-# and OpenAI Models: gpt-4o-mini, gpt-4o, o1, o1-mini, o3-mini
+# and OpenAI Models: gpt-4.1, gpt-4.1-mini, o1, o1-mini, o3-mini
 #
 # If not specified, defaults to "haiku". 
 # Can be overriden with a command line switch --model=<model>, or within the Agent constructor.
@@ -221,7 +221,7 @@ def init(
         if "fastagent.secrets.yaml" in created:
             console.print("\n[yellow]Important:[/yellow] Remember to:")
             console.print(
-                "1. Add your API keys to fastagent.secrets.yaml or set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables"
+                "1. Add your API keys to fastagent.secrets.yaml, or set environment variables. Use [cyan]fast-agent check[/cyan] to verify."
             )
             console.print(
                 "2. Keep fastagent.secrets.yaml secure and never commit it to version control"

mcp_agent/cli/main.py

@@ -4,7 +4,7 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
-from mcp_agent.cli.commands import check_config, quickstart, setup
+from mcp_agent.cli.commands import check_config, go, quickstart, setup
 from mcp_agent.cli.terminal import Application
 
 app = typer.Typer(
@@ -13,6 +13,7 @@ app = typer.Typer(
 )
 
 # Subcommands
+app.add_typer(go.app, name="go", help="Run an interactive agent directly from the command line")
 app.add_typer(setup.app, name="setup", help="Set up a new agent project")
 app.add_typer(check_config.app, name="check", help="Show or diagnose fast-agent configuration")
 app.add_typer(quickstart.app, name="bootstrap", help="Create example applications")
@@ -39,14 +40,15 @@ def show_welcome() -> None:
     table.add_column("Command", style="green")
     table.add_column("Description")
 
-    table.add_row("setup", "Create a new agent and configuration files")
+    table.add_row("[bold]go[/bold]", "Start an interactive session with an agent")
+    table.add_row("setup", "Create a new agent template and configuration files")
     table.add_row("check", "Show or diagnose fast-agent configuration")
     table.add_row("quickstart", "Create example applications (workflow, researcher, etc.)")
 
     console.print(table)
 
     console.print(
-        "\n[italic]get started with:[/italic] [cyan]fast-agent[/cyan] [green]setup[/green]"
+        "\n[italic]get started with:[/italic] [bold][cyan]fast-agent[/cyan][/bold] [green]setup[/green]"
     )