fast-agent-mcp 0.3.5__py3-none-any.whl → 0.3.7__py3-none-any.whl

fast_agent/agents/mcp_agent.py

@@ -16,8 +16,6 @@ from typing import (
     Mapping,
     Optional,
     Sequence,
-    Tuple,
-    Type,
     TypeVar,
     Union,
 )
@@ -156,6 +154,9 @@ class McpAgent(ABC, ToolAgent):
         """
         await self.__aenter__()
 
+        # Apply template substitution to the instruction with server instructions
+        await self._apply_instruction_templates()
+
     async def shutdown(self) -> None:
         """
         Shutdown the agent and close all MCP server connections.
@@ -174,18 +175,71 @@ class McpAgent(ABC, ToolAgent):
         self._initialized = value
         self._aggregator.initialized = value
 
-    async def __call__(
-        self,
-        message: Union[
-            str,
-            PromptMessage,
-            PromptMessageExtended,
-            Sequence[Union[str, PromptMessage, PromptMessageExtended]],
-        ],
+    async def _apply_instruction_templates(self) -> None:
+        """
+        Apply template substitution to the instruction, including server instructions.
+        This is called during initialization after servers are connected.
+        """
+        if not self.instruction:
+            return
+
+        # Gather server instructions if the template includes {{serverInstructions}}
+        if "{{serverInstructions}}" in self.instruction:
+            try:
+                instructions_data = await self._aggregator.get_server_instructions()
+                server_instructions = self._format_server_instructions(instructions_data)
+            except Exception as e:
+                self.logger.warning(f"Failed to get server instructions: {e}")
+                server_instructions = ""
+
+            # Replace the template variable
+            self.instruction = self.instruction.replace(
+                "{{serverInstructions}}", server_instructions
+            )
+
+        # Update default request params to match
+        if self._default_request_params:
+            self._default_request_params.systemPrompt = self.instruction
+
+        self.logger.debug(f"Applied instruction templates for agent {self._name}")
+
+    def _format_server_instructions(
+        self, instructions_data: Dict[str, tuple[str | None, List[str]]]
     ) -> str:
-        return await self.send(message)
+        """
+        Format server instructions with XML tags and tool lists.
+
+        Args:
+            instructions_data: Dict mapping server name to (instructions, tool_names)
+
+        Returns:
+            Formatted string with server instructions
+        """
+        if not instructions_data:
+            return ""
+
+        formatted_parts = []
+        for server_name, (instructions, tool_names) in instructions_data.items():
+            # Skip servers with no instructions
+            if instructions is None:
+                continue
+
+            # Format tool names with server prefix
+            prefixed_tools = [f"{server_name}-{tool}" for tool in tool_names]
+            tools_list = ", ".join(prefixed_tools) if prefixed_tools else "No tools available"
+
+            formatted_parts.append(
+                f'<mcp-server name="{server_name}">\n'
+                f"<tools>{tools_list}</tools>\n"
+                f"<instructions>\n{instructions}\n</instructions>\n"
+                f"</mcp-server>"
+            )
 
-    async def send(
+        if formatted_parts:
+            return "\n\n".join(formatted_parts)
+        return ""
+
+    async def __call__(
         self,
         message: Union[
             str,
@@ -193,23 +247,34 @@ class McpAgent(ABC, ToolAgent):
             PromptMessageExtended,
             Sequence[Union[str, PromptMessage, PromptMessageExtended]],
         ],
-        request_params: RequestParams | None = None,
     ) -> str:
-        """
-        Send a message to the agent and get a response.
-
-        Args:
-            message: Message content in various formats:
-                - String: Converted to a user PromptMessageExtended
-                - PromptMessage: Converted to PromptMessageExtended
-                - PromptMessageExtended: Used directly
-                - request_params: Optional request parameters
+        return await self.send(message)
 
-        Returns:
-            The agent's response as a string
-        """
-        response = await self.generate(message, request_params)
-        return response.last_text() or ""
+    # async def send(
+    #     self,
+    #     message: Union[
+    #         str,
+    #         PromptMessage,
+    #         PromptMessageExtended,
+    #         Sequence[Union[str, PromptMessage, PromptMessageExtended]],
+    #     ],
+    #     request_params: RequestParams | None = None,
+    # ) -> str:
+    #     """
+    #     Send a message to the agent and get a response.
+
+    #     Args:
+    #         message: Message content in various formats:
+    #             - String: Converted to a user PromptMessageExtended
+    #             - PromptMessage: Converted to PromptMessageExtended
+    #             - PromptMessageExtended: Used directly
+    #             - request_params: Optional request parameters
+
+    #     Returns:
+    #         The agent's response as a string
+    #     """
+    #     response = await self.generate(message, request_params)
+    #     return response.last_text() or ""
 
     def _matches_pattern(self, name: str, pattern: str, server_name: str) -> bool:
         """
@@ -533,6 +598,7 @@ class McpAgent(ABC, ToolAgent):
             return PromptMessageExtended(role="user", tool_results={})
 
         tool_results: dict[str, CallToolResult] = {}
+        self._tool_loop_error = None
 
         # Cache available tool names (original, not namespaced) for display
         available_tools = [
@@ -549,12 +615,41 @@ class McpAgent(ABC, ToolAgent):
             namespaced_tool = self._aggregator._namespaced_tool_map.get(tool_name)
             display_tool_name = namespaced_tool.tool.name if namespaced_tool else tool_name
 
+            tool_available = False
+            if tool_name == HUMAN_INPUT_TOOL_NAME:
+                tool_available = True
+            elif namespaced_tool:
+                tool_available = True
+            else:
+                tool_available = any(
+                    candidate.tool.name == tool_name
+                    for candidate in self._aggregator._namespaced_tool_map.values()
+                )
+
+            if not tool_available:
+                error_message = f"Tool '{display_tool_name}' is not available"
+                self.logger.error(error_message)
+                self._mark_tool_loop_error(
+                    correlation_id=correlation_id,
+                    error_message=error_message,
+                    tool_results=tool_results,
+                )
+                break
+
+            # Find the index of the current tool in available_tools for highlighting
+            highlight_index = None
+            try:
+                highlight_index = available_tools.index(display_tool_name)
+            except ValueError:
+                # Tool not found in list, no highlighting
+                pass
+
             self.display.show_tool_call(
                 name=self._name,
                 tool_args=tool_args,
                 bottom_items=available_tools,
                 tool_name=display_tool_name,
-                highlight_items=tool_name,
+                highlight_index=highlight_index,
                 max_item_length=12,
             )
 
@@ -578,7 +673,7 @@ class McpAgent(ABC, ToolAgent):
                 # Show error result too
                 self.display.show_tool_result(name=self._name, result=error_result)
 
-        return PromptMessageExtended(role="user", tool_results=tool_results)
+        return self._finalize_tool_results(tool_results)
 
     async def apply_prompt_template(self, prompt_result: GetPromptResult, prompt_name: str) -> str:
         """
@@ -596,36 +691,36 @@ class McpAgent(ABC, ToolAgent):
         with self._tracer.start_as_current_span(f"Agent: '{self._name}' apply_prompt_template"):
             return await self._llm.apply_prompt_template(prompt_result, prompt_name)
 
-    async def structured(
-        self,
-        messages: Union[
-            str,
-            PromptMessage,
-            PromptMessageExtended,
-            List[Union[str, PromptMessage, PromptMessageExtended]],
-        ],
-        model: Type[ModelT],
-        request_params: RequestParams | None = None,
-    ) -> Tuple[ModelT | None, PromptMessageExtended]:
-        """
-        Apply the prompt and return the result as a Pydantic model.
-        Normalizes input messages and delegates to the attached LLM.
-
-        Args:
-            messages: Message(s) in various formats:
-                - String: Converted to a user PromptMessageExtended
-                - PromptMessage: Converted to PromptMessageExtended
-                - PromptMessageExtended: Used directly
-                - List of any combination of the above
-            model: The Pydantic model class to parse the result into
-            request_params: Optional parameters to configure the LLM request
-
-        Returns:
-            An instance of the specified model, or None if coercion fails
-        """
-
-        with self._tracer.start_as_current_span(f"Agent: '{self._name}' structured"):
-            return await super().structured(messages, model, request_params)
+    # async def structured(
+    #     self,
+    #     messages: Union[
+    #         str,
+    #         PromptMessage,
+    #         PromptMessageExtended,
+    #         Sequence[Union[str, PromptMessage, PromptMessageExtended]],
+    #     ],
+    #     model: Type[ModelT],
+    #     request_params: RequestParams | None = None,
+    # ) -> Tuple[ModelT | None, PromptMessageExtended]:
+    #     """
+    #     Apply the prompt and return the result as a Pydantic model.
+    #     Normalizes input messages and delegates to the attached LLM.
+
+    #     Args:
+    #         messages: Message(s) in various formats:
+    #             - String: Converted to a user PromptMessageExtended
+    #             - PromptMessage: Converted to PromptMessageExtended
+    #             - PromptMessageExtended: Used directly
+    #             - List of any combination of the above
+    #         model: The Pydantic model class to parse the result into
+    #         request_params: Optional parameters to configure the LLM request
+
+    #     Returns:
+    #         An instance of the specified model, or None if coercion fails
+    #     """
+
+    #     with self._tracer.start_as_current_span(f"Agent: '{self._name}' structured"):
+    #         return await super().structured(messages, model, request_params)
 
     async def apply_prompt_messages(
         self, prompts: List[PromptMessageExtended], request_params: RequestParams | None = None

fast_agent/agents/tool_agent.py

@@ -5,7 +5,7 @@ from mcp.types import CallToolResult, ListToolsResult, Tool
 
 from fast_agent.agents.agent_types import AgentConfig
 from fast_agent.agents.llm_agent import LlmAgent
-from fast_agent.constants import HUMAN_INPUT_TOOL_NAME
+from fast_agent.constants import FAST_AGENT_ERROR_CHANNEL, HUMAN_INPUT_TOOL_NAME
 from fast_agent.context import Context
 from fast_agent.core.logging.logger import get_logger
 from fast_agent.mcp.helpers.content_helpers import text_content
@@ -42,6 +42,7 @@ class ToolAgent(LlmAgent):
 
         self._execution_tools: dict[str, FastMCPTool] = {}
         self._tool_schemas: list[Tool] = []
+        self._tool_loop_error: str | None = None
 
         # Build a working list of tools and auto-inject human-input tool if missing
         working_tools: list[FastMCPTool | Callable] = list(tools) if tools else []
@@ -97,10 +98,19 @@ class ToolAgent(LlmAgent):
             )
 
             if LlmStopReason.TOOL_USE == result.stop_reason:
+                self._tool_loop_error = None
                 if self.config.use_history:
-                    messages = [await self.run_tools(result)]
+                    tool_message = await self.run_tools(result)
+                    if self._tool_loop_error:
+                        result.stop_reason = LlmStopReason.ERROR
+                        break
+                    messages = [tool_message]
                 else:
-                    messages.extend([result, await self.run_tools(result)])
+                    tool_message = await self.run_tools(result)
+                    if self._tool_loop_error:
+                        result.stop_reason = LlmStopReason.ERROR
+                        break
+                    messages.extend([result, tool_message])
             else:
                 break
 
@@ -123,16 +133,37 @@ class ToolAgent(LlmAgent):
             return PromptMessageExtended(role="user", tool_results={})
 
         tool_results: dict[str, CallToolResult] = {}
+        self._tool_loop_error = None
         # TODO -- use gather() for parallel results, update display
         available_tools = [t.name for t in (await self.list_tools()).tools]
         for correlation_id, tool_request in request.tool_calls.items():
             tool_name = tool_request.params.name
             tool_args = tool_request.params.arguments or {}
+
+            if tool_name not in self._execution_tools:
+                error_message = f"Tool '{tool_name}' is not available"
+                logger.error(error_message)
+                self._mark_tool_loop_error(
+                    correlation_id=correlation_id,
+                    error_message=error_message,
+                    tool_results=tool_results,
+                )
+                break
+
+            # Find the index of the current tool in available_tools for highlighting
+            highlight_index = None
+            try:
+                highlight_index = available_tools.index(tool_name)
+            except ValueError:
+                # Tool not found in list, no highlighting
+                pass
+
             self.display.show_tool_call(
                 name=self.name,
                 tool_args=tool_args,
                 bottom_items=available_tools,
                 tool_name=tool_name,
+                highlight_index=highlight_index,
                 max_item_length=12,
             )
 
@@ -141,7 +172,32 @@ class ToolAgent(LlmAgent):
             tool_results[correlation_id] = result
             self.display.show_tool_result(name=self.name, result=result)
 
-        return PromptMessageExtended(role="user", tool_results=tool_results)
+        return self._finalize_tool_results(tool_results)
+
+    def _mark_tool_loop_error(
+        self,
+        *,
+        correlation_id: str,
+        error_message: str,
+        tool_results: dict[str, CallToolResult],
+    ) -> None:
+        error_result = CallToolResult(
+            content=[text_content(error_message)],
+            isError=True,
+        )
+        tool_results[correlation_id] = error_result
+        self.display.show_tool_result(name=self.name, result=error_result)
+        self._tool_loop_error = error_message
+
+    def _finalize_tool_results(
+        self, tool_results: dict[str, CallToolResult]
+    ) -> PromptMessageExtended:
+        channels = None
+        if self._tool_loop_error:
+            channels = {
+                FAST_AGENT_ERROR_CHANNEL: [text_content(self._tool_loop_error)],
+            }
+        return PromptMessageExtended(role="user", tool_results=tool_results, channels=channels)
 
     async def list_tools(self) -> ListToolsResult:
         """Return available tools for this agent. Overridable by subclasses."""

fast_agent/agents/workflow/router_agent.py

@@ -300,10 +300,18 @@ class RouterAgent(LlmAgent):
             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=list(self.agent_map.keys()),
-                highlight_items=[response.agent],
+                bottom_items=agent_keys,
+                highlight_index=highlight_index,
                 name=self.name,
             )
 

fast_agent/cli/commands/auth.py

@@ -22,14 +22,28 @@ from fast_agent.ui.console import console
 app = typer.Typer(help="Manage OAuth authentication state for MCP servers")
 
 
-def _get_keyring_backend_name() -> str:
+def _get_keyring_status() -> tuple[str, bool]:
+    """Return (backend_name, usable) where usable=False for the fail backend or missing keyring."""
     try:
         import keyring
 
         kr = keyring.get_keyring()
-        return getattr(kr, "name", kr.__class__.__name__)
+        name = getattr(kr, "name", kr.__class__.__name__)
+        try:
+            from keyring.backends.fail import Keyring as FailKeyring  # type: ignore
+
+            return name, not isinstance(kr, FailKeyring)
+        except Exception:
+            # If fail backend marker cannot be imported, assume usable
+            return name, True
     except Exception:
-        return "unavailable"
+        return "unavailable", False
+
+
+def _get_keyring_backend_name() -> str:
+    # Backwards-compat helper; prefer _get_keyring_status in new code
+    name, _ = _get_keyring_status()
+    return name
 
 
 def _keyring_get_password(service: str, username: str) -> str | None:
@@ -106,7 +120,7 @@ def status(
 ) -> None:
     """Show keyring backend and token status for configured MCP servers."""
     settings = get_settings(config_path)
-    backend = _get_keyring_backend_name()
+    backend, backend_usable = _get_keyring_status()
 
     # Single-target view if target provided
     if target:
@@ -123,12 +137,15 @@ def status(
 
         # Direct presence check
         present = False
-        try:
-            import keyring
+        if backend_usable:
+            try:
+                import keyring
 
-            present = keyring.get_password("fast-agent-mcp", f"oauth:tokens:{identity}") is not None
-        except Exception:
-            present = False
+                present = (
+                    keyring.get_password("fast-agent-mcp", f"oauth:tokens:{identity}") is not None
+                )
+            except Exception:
+                present = False
 
         table = Table(show_header=True, box=None)
         table.add_column("Identity", header_style="bold")
@@ -139,7 +156,10 @@ def status(
         token_disp = "[bold green]✓[/bold green]" if present else "[dim]✗[/dim]"
         table.add_row(identity, token_disp, servers_for_id)
 
-        console.print(f"Keyring backend: [green]{backend}[/green]")
+        if backend_usable and backend != "unavailable":
+            console.print(f"Keyring backend: [green]{backend}[/green]")
+        else:
+            console.print("Keyring backend: [red]not available[/red]")
         console.print(table)
         console.print(
             "\n[dim]Run 'fast-agent auth clear --identity "
@@ -148,7 +168,10 @@ def status(
         return
 
     # Full status view
-    console.print(f"Keyring backend: [green]{backend}[/green]")
+    if backend_usable and backend != "unavailable":
+        console.print(f"Keyring backend: [green]{backend}[/green]")
+    else:
+        console.print("Keyring backend: [red]not available[/red]")
 
     tokens = list_keyring_tokens()
     token_table = Table(show_header=True, box=None)
@@ -181,25 +204,25 @@ def status(
             )
             # Direct presence check for each identity so status works even without index
             has_token = False
+            token_disp = "[dim]✗[/dim]"
             if persist == "keyring" and row["oauth"]:
-                try:
-                    import keyring
-
-                    has_token = (
-                        keyring.get_password("fast-agent-mcp", f"oauth:tokens:{row['identity']}")
-                        is not None
-                    )
-                except Exception:
-                    has_token = False
-            token_disp = (
-                "[bold green]✓[/bold green]"
-                if has_token
-                else (
-                    "[yellow]memory[/yellow]"
-                    if persist == "memory" and row["oauth"]
-                    else "[dim]✗[/dim]"
-                )
-            )
+                if backend_usable:
+                    try:
+                        import keyring
+
+                        has_token = (
+                            keyring.get_password(
+                                "fast-agent-mcp", f"oauth:tokens:{row['identity']}"
+                            )
+                            is not None
+                        )
+                    except Exception:
+                        has_token = False
+                    token_disp = "[bold green]✓[/bold green]" if has_token else "[dim]✗[/dim]"
+                else:
+                    token_disp = "[red]not available[/red]"
+            elif persist == "memory" and row["oauth"]:
+                token_disp = "[yellow]memory[/yellow]"
             map_table.add_row(
                 row["name"],
                 row["transport"].upper(),

fast_agent/cli/commands/check_config.py

@@ -305,14 +305,25 @@ def show_check_summary() -> None:
     env_table.add_column("Value")
 
     # Determine keyring backend early so it can appear in the top section
+    # Also detect whether the backend is actually usable (not the fail backend)
+    keyring_usable = False
     try:
         import keyring  # type: ignore
 
         keyring_backend = keyring.get_keyring()
         keyring_name = getattr(keyring_backend, "name", keyring_backend.__class__.__name__)
+        try:
+            # Detect the "fail" backend explicitly; it's present but unusable
+            from keyring.backends.fail import Keyring as FailKeyring  # type: ignore
+
+            keyring_usable = not isinstance(keyring_backend, FailKeyring)
+        except Exception:
+            # If we can't import the fail backend marker, assume usable
+            keyring_usable = True
     except Exception:
         keyring = None  # type: ignore
         keyring_name = "unavailable"
+        keyring_usable = False
 
     # Python info (highlight version and path in green)
     env_table.add_row(
@@ -345,11 +356,14 @@ def show_check_summary() -> None:
         )
     else:  # parsed successfully
         env_table.add_row("Config File", f"[green]Found[/green] ({config_path})")
-        default_model_value = config_summary.get("default_model", "haiku (system default)")
+        default_model_value = config_summary.get("default_model", "gpt-5-mini.low (system default)")
         env_table.add_row("Default Model", f"[green]{default_model_value}[/green]")
 
     # Keyring backend (always shown in application-level settings)
-    env_table.add_row("Keyring Backend", f"[green]{keyring_name}[/green]")
+    if keyring_usable and keyring_name != "unavailable":
+        env_table.add_row("Keyring Backend", f"[green]{keyring_name}[/green]")
+    else:
+        env_table.add_row("Keyring Backend", "[red]not available[/red]")
 
     console.print(env_table)
 
@@ -514,7 +528,9 @@ def show_check_summary() -> None:
                 try:
                     cfg = MCPServerSettings(
                         name=name,
-                        transport="sse" if transport == "SSE" else ("stdio" if transport == "STDIO" else "http"),
+                        transport="sse"
+                        if transport == "SSE"
+                        else ("stdio" if transport == "STDIO" else "http"),
                         url=(server.get("url") or None),
                         auth=server.get("auth") if isinstance(server.get("auth"), dict) else None,
                     )
@@ -532,11 +548,16 @@ def show_check_summary() -> None:
                     persist = "keyring"
                     if cfg.auth is not None and hasattr(cfg.auth, "persist"):
                         persist = getattr(cfg.auth, "persist") or "keyring"
-                    if keyring and persist == "keyring" and oauth_enabled:
+                    if keyring and keyring_usable and persist == "keyring" and oauth_enabled:
                         identity = compute_server_identity(cfg)
                         tkey = f"oauth:tokens:{identity}"
-                        has = keyring.get_password("fast-agent-mcp", tkey) is not None
+                        try:
+                            has = keyring.get_password("fast-agent-mcp", tkey) is not None
+                        except Exception:
+                            has = False
                         token_status = "[bold green]✓[/bold green]" if has else "[dim]✗[/dim]"
+                    elif persist == "keyring" and not keyring_usable and oauth_enabled:
+                        token_status = "[red]not available[/red]"
                     elif persist == "memory" and oauth_enabled:
                         token_status = "[yellow]memory[/yellow]"
 

fast_agent/cli/commands/go.py

@@ -18,10 +18,16 @@ app = typer.Typer(
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
 )
 
+default_instruction = """You are a helpful AI Agent.
+
+{{serverInstructions}}
+
+The current date is {{currentDate}}."""
+
 
 async def _run_agent(
     name: str = "fast-agent cli",
-    instruction: str = "You are a helpful AI Agent.",
+    instruction: str = default_instruction,
     config_path: Optional[str] = None,
     server_list: Optional[List[str]] = None,
     model: Optional[str] = None,
@@ -34,7 +40,7 @@ async def _run_agent(
     """Async implementation to run an interactive agent."""
     from pathlib import Path
 
-    from fast_agent.mcp.prompts.prompt_load import load_prompt_multipart
+    from fast_agent.mcp.prompts.prompt_load import load_prompt
 
     # Create the FastAgent instance
 
@@ -104,7 +110,7 @@ async def _run_agent(
                     display = ConsoleDisplay(config=None)
                     display.show_parallel_results(agent.parallel)
                 elif prompt_file:
-                    prompt = load_prompt_multipart(Path(prompt_file))
+                    prompt = load_prompt(Path(prompt_file))
                     await agent.parallel.generate(prompt)
                     display = ConsoleDisplay(config=None)
                     display.show_parallel_results(agent.parallel)
@@ -129,7 +135,7 @@ async def _run_agent(
                     # Print the response and exit
                     print(response)
                 elif prompt_file:
-                    prompt = load_prompt_multipart(Path(prompt_file))
+                    prompt = load_prompt(Path(prompt_file))
                     response = await agent.agent.generate(prompt)
                     print(f"\nLoaded {len(prompt)} messages from prompt file '{prompt_file}'")
                     await agent.interactive()
@@ -352,7 +358,7 @@ def go(
         stdio_commands.append(stdio)
 
     # Resolve instruction from file/URL or use default
-    resolved_instruction = "You are a helpful AI Agent."  # Default
+    resolved_instruction = default_instruction  # Default
     agent_name = "agent"
 
     if instruction: