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

fast_agent/cli/commands/setup.py

@@ -26,9 +26,7 @@ def load_template_text(filename: str) -> str:
         res_name = "pyproject.toml.tmpl"
     else:
         res_name = filename
-    resource_path = (
-        files("fast_agent").joinpath("resources").joinpath("setup").joinpath(res_name)
-    )
+    resource_path = files("fast_agent").joinpath("resources").joinpath("setup").joinpath(res_name)
     if resource_path.is_file():
         return resource_path.read_text()
 
@@ -137,9 +135,8 @@ def init(
         # Always use latest fast-agent-mcp (no version pin)
         fast_agent_dep = '"fast-agent-mcp"'
 
-        return (
-            template_text.replace("{{python_requires}}", py_req)
-            .replace("{{fast_agent_dep}}", fast_agent_dep)
+        return template_text.replace("{{python_requires}}", py_req).replace(
+            "{{fast_agent_dep}}", fast_agent_dep
         )
 
     pyproject_template = load_template_text("pyproject.toml")
@@ -169,7 +166,7 @@ def init(
                 "2. Keep fastagent.secrets.yaml secure and never commit it to version control"
             )
             console.print(
-                "3. Update fastagent.config.yaml to set a default model (currently system default is 'haiku')"
+                "3. Update fastagent.config.yaml to set a default model (currently system default is 'gpt-5-mini.low')"
             )
         console.print("\nTo get started, run:")
         console.print("  uv run agent.py")

fast_agent/config.py

@@ -37,7 +37,7 @@ class MCPServerAuthSettings(BaseModel):
 
 
 class MCPSamplingSettings(BaseModel):
-    model: str = "haiku"
+    model: str = "gpt-5-mini.low"
 
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
 
@@ -122,6 +122,9 @@ class MCPServerSettings(BaseModel):
     cwd: str | None = None
     """Working directory for the executed server command."""
 
+    include_instructions: bool = True
+    """Whether to include this server's instructions in the system prompt (default: True)."""
+
     implementation: Implementation | None = None
 
     @model_validator(mode="before")

fast_agent/constants.py

@@ -6,3 +6,5 @@ Global constants for fast_agent with minimal dependencies to avoid circular impo
 HUMAN_INPUT_TOOL_NAME = "__human_input"
 MCP_UI = "mcp-ui"
 REASONING = "reasoning"
+FAST_AGENT_ERROR_CHANNEL = "fast-agent-error"
+FAST_AGENT_REMOVED_METADATA_CHANNEL = "fast-agent-removed-meta"

fast_agent/core/agent_app.py

@@ -34,6 +34,8 @@ class AgentApp:
         Args:
             agents: Dictionary of agent instances keyed by name
         """
+        if len(agents) == 0:
+            raise ValueError("No agents provided!")
         self._agents = agents
 
     def __getitem__(self, key: str) -> AgentProtocol:

fast_agent/core/direct_factory.py

@@ -3,7 +3,8 @@ Direct factory functions for creating agent and workflow instances without proxi
 Implements type-safe factories with improved error handling.
 """
 
-from typing import Any, Dict, Optional, Protocol, TypeVar
+from functools import partial
+from typing import Any, Dict, List, Optional, Protocol, TypeVar
 
 from fast_agent.agents import McpAgent
 from fast_agent.agents.agent_types import AgentConfig, AgentType
@@ -379,6 +380,35 @@ async def create_agents_by_type(
     return result_agents
 
 
+async def active_agents_in_dependency_group(
+    app_instance: Core,
+    agents_dict: AgentConfigDict,
+    model_factory_func: ModelFactoryFunctionProtocol,
+    group: List[str],
+    active_agents: AgentDict,
+):
+    """
+    For each of the possible agent types, create agents and update the active agents dictionary.
+
+    Notice: This function modifies the active_agents dictionary in-place which is a feature (no copies).
+    """
+    type_of_agents = list(map(lambda c: (c, c.value), AgentType))
+    for agent_type, agent_type_value in type_of_agents:
+        agents_dict_local = {
+            name: agents_dict[name]
+            for name in group
+            if agents_dict[name]["type"] == agent_type_value
+        }
+        agents = await create_agents_by_type(
+            app_instance,
+            agents_dict_local,
+            agent_type,
+            model_factory_func,
+            active_agents,
+        )
+        active_agents.update(agents)
+
+
 async def create_agents_in_dependency_order(
     app_instance: Core,
     agents_dict: AgentConfigDict,
@@ -403,127 +433,16 @@ async def create_agents_in_dependency_order(
     # Create a dictionary to store all active agents/workflows
     active_agents: AgentDict = {}
 
+    active_agents_in_dependency_group_partial = partial(
+        active_agents_in_dependency_group,
+        app_instance,
+        agents_dict,
+        model_factory_func,
+    )
+
     # Create agent proxies for each group in dependency order
     for group in dependencies:
-        # Create basic agents first
-        # Note: We compare string values from config with the Enum's string value
-        if AgentType.BASIC.value in [agents_dict[name]["type"] for name in group]:
-            basic_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.BASIC.value
-                },
-                AgentType.BASIC,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(basic_agents)
-
-        # Create custom agents first
-        if AgentType.CUSTOM.value in [agents_dict[name]["type"] for name in group]:
-            basic_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.CUSTOM.value
-                },
-                AgentType.CUSTOM,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(basic_agents)
-
-        # Create parallel agents
-        if AgentType.PARALLEL.value in [agents_dict[name]["type"] for name in group]:
-            parallel_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.PARALLEL.value
-                },
-                AgentType.PARALLEL,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(parallel_agents)
-
-        # Create router agents
-        if AgentType.ROUTER.value in [agents_dict[name]["type"] for name in group]:
-            router_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.ROUTER.value
-                },
-                AgentType.ROUTER,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(router_agents)
-
-        # Create chain agents
-        if AgentType.CHAIN.value in [agents_dict[name]["type"] for name in group]:
-            chain_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.CHAIN.value
-                },
-                AgentType.CHAIN,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(chain_agents)
-
-        # Create evaluator-optimizer agents
-        if AgentType.EVALUATOR_OPTIMIZER.value in [agents_dict[name]["type"] for name in group]:
-            evaluator_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.EVALUATOR_OPTIMIZER.value
-                },
-                AgentType.EVALUATOR_OPTIMIZER,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(evaluator_agents)
-
-        if AgentType.ORCHESTRATOR.value in [agents_dict[name]["type"] for name in group]:
-            orchestrator_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.ORCHESTRATOR.value
-                },
-                AgentType.ORCHESTRATOR,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(orchestrator_agents)
-
-        # Create orchestrator2 agents last since they might depend on other agents
-        if AgentType.ITERATIVE_PLANNER.value in [agents_dict[name]["type"] for name in group]:
-            orchestrator2_agents = await create_agents_by_type(
-                app_instance,
-                {
-                    name: agents_dict[name]
-                    for name in group
-                    if agents_dict[name]["type"] == AgentType.ITERATIVE_PLANNER.value
-                },
-                AgentType.ITERATIVE_PLANNER,
-                model_factory_func,
-                active_agents,
-            )
-            active_agents.update(orchestrator2_agents)
+        await active_agents_in_dependency_group_partial(group, active_agents)
 
     return active_agents
 

fast_agent/core/fastagent.py

@@ -75,7 +75,7 @@ from fast_agent.core.validation import (
     validate_server_references,
     validate_workflow_references,
 )
-from fast_agent.mcp.prompts.prompt_load import load_prompt_multipart
+from fast_agent.mcp.prompts.prompt_load import load_prompt
 from fast_agent.ui.usage_display import display_usage_report
 
 if TYPE_CHECKING:
@@ -543,7 +543,7 @@ class FastAgent:
 
                     if hasattr(self.args, "prompt_file") and self.args.prompt_file:
                         agent_name = self.args.agent
-                        prompt: List[PromptMessageExtended] = load_prompt_multipart(
+                        prompt: List[PromptMessageExtended] = load_prompt(
                             Path(self.args.prompt_file)
                         )
                         if agent_name not in active_agents:

fast_agent/history/history_exporter.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Optional
 
-from fast_agent.mcp.prompt_serialization import save_messages_to_file
+from fast_agent.mcp.prompt_serialization import save_messages
 
 if TYPE_CHECKING:
     from fast_agent.interfaces import AgentProtocol
@@ -35,10 +35,10 @@ class HistoryExporter:
             The path that was written to.
         """
         # Determine a default filename when not provided
-        target = filename or f"{getattr(agent, 'name', 'assistant')}_prompts.txt"
+        target = filename or f"{getattr(agent, 'name', 'assistant')}.json"
 
         messages = agent.message_history
-        save_messages_to_file(messages, target)
+        save_messages(messages, target)
 
         # Return and optionally print a small confirmation
         return target

fast_agent/llm/fastagent_llm.py

@@ -198,7 +198,7 @@ class FastAgentLLM(ContextDependent, FastAgentLLMProtocol, Generic[MessageParamT
         if messages[-1].first_text().startswith("***SAVE_HISTORY"):
             parts: list[str] = messages[-1].first_text().split(" ", 1)
             filename: str = (
-                parts[1].strip() if len(parts) > 1 else f"{self.name or 'assistant'}_prompts.txt"
+                parts[1].strip() if len(parts) > 1 else f"{self.name or 'assistant'}.json"
             )
             await self._save_history(filename)
             return Prompt.assistant(f"History saved to {filename}")
@@ -589,10 +589,10 @@ class FastAgentLLM(ContextDependent, FastAgentLLMProtocol, Generic[MessageParamT
         Uses JSON format for .json files (MCP SDK compatible format) and
         delimited text format for other extensions.
         """
-        from fast_agent.mcp.prompt_serialization import save_messages_to_file
+        from fast_agent.mcp.prompt_serialization import save_messages
 
         # Save messages using the unified save function that auto-detects format
-        save_messages_to_file(self._message_history, filename)
+        save_messages(self._message_history, filename)
 
     @property
     def message_history(self) -> List[PromptMessageExtended]:

fast_agent/llm/provider/openai/llm_openai.py

@@ -7,7 +7,7 @@ from mcp.types import (
     ContentBlock,
     TextContent,
 )
-from openai import AsyncOpenAI, AuthenticationError
+from openai import APIError, AsyncOpenAI, AuthenticationError
 from openai.lib.streaming.chat import ChatCompletionStreamState
 
 # from openai.types.beta.chat import
@@ -19,19 +19,17 @@ from openai.types.chat import (
 )
 from pydantic_core import from_json
 
+from fast_agent.constants import FAST_AGENT_ERROR_CHANNEL
 from fast_agent.core.exceptions import ProviderKeyError
 from fast_agent.core.logging.logger import get_logger
 from fast_agent.core.prompt import Prompt
 from fast_agent.event_progress import ProgressAction
-from fast_agent.llm.fastagent_llm import (
-    FastAgentLLM,
-    RequestParams,
-)
+from fast_agent.llm.fastagent_llm import FastAgentLLM, RequestParams
 from fast_agent.llm.provider.openai.multipart_converter_openai import OpenAIConverter, OpenAIMessage
 from fast_agent.llm.provider_types import Provider
 from fast_agent.llm.usage_tracking import TurnUsage
-from fast_agent.types import PromptMessageExtended
-from fast_agent.types.llm_stop_reason import LlmStopReason
+from fast_agent.mcp.helpers.content_helpers import text_content
+from fast_agent.types import LlmStopReason, PromptMessageExtended
 
 _logger = get_logger(__name__)
 
@@ -348,7 +346,11 @@ class OpenAILLM(FastAgentLLM[ChatCompletionMessageParam, ChatCompletionMessage])
         # Use basic streaming API
         stream = await self._openai_client().chat.completions.create(**arguments)
         # Process the stream
-        response = await self._process_stream(stream, model_name)
+        try:
+            response = await self._process_stream(stream, model_name)
+        except APIError as error:
+            self.logger.error("Streaming APIError during OpenAI completion", exc_info=error)
+            return self._stream_failure_response(error, model_name)
         # Track usage if response is valid and has usage data
         if (
             hasattr(response, "usage")
@@ -438,6 +440,53 @@ class OpenAILLM(FastAgentLLM[ChatCompletionMessageParam, ChatCompletionMessage])
             *response_content_blocks, stop_reason=stop_reason, tool_calls=requested_tool_calls
         )
 
+    def _stream_failure_response(self, error: APIError, model_name: str) -> PromptMessageExtended:
+        """Convert streaming API errors into a graceful assistant reply."""
+
+        provider_label = (
+            self.provider.value if isinstance(self.provider, Provider) else str(self.provider)
+        )
+        detail = getattr(error, "message", None) or str(error)
+        detail = detail.strip() if isinstance(detail, str) else ""
+
+        parts: list[str] = [f"{provider_label} request failed"]
+        if model_name:
+            parts.append(f"for model '{model_name}'")
+        code = getattr(error, "code", None)
+        if code:
+            parts.append(f"(code: {code})")
+        status = getattr(error, "status_code", None)
+        if status:
+            parts.append(f"(status={status})")
+
+        message = " ".join(parts)
+        if detail:
+            message = f"{message}: {detail}"
+
+        user_summary = " ".join(message.split()) if message else ""
+        if user_summary and len(user_summary) > 280:
+            user_summary = user_summary[:277].rstrip() + "..."
+
+        if user_summary:
+            assistant_text = f"I hit an internal error while calling the model: {user_summary}"
+            if not assistant_text.endswith((".", "!", "?")):
+                assistant_text += "."
+            assistant_text += " See fast-agent-error for additional details."
+        else:
+            assistant_text = (
+                "I hit an internal error while calling the model; see fast-agent-error for details."
+            )
+
+        assistant_block = text_content(assistant_text)
+        error_block = text_content(message)
+
+        return PromptMessageExtended(
+            role="assistant",
+            content=[assistant_block],
+            channels={FAST_AGENT_ERROR_CHANNEL: [error_block]},
+            stop_reason=LlmStopReason.ERROR,
+        )
+
     async def _is_tool_stop_reason(self, finish_reason: str) -> bool:
         return True
 

fast_agent/mcp/__init__.py

@@ -24,11 +24,9 @@ from .helpers import (
     split_thinking_content,
     text_content,
 )
-from .prompt_message_extended import PromptMessageExtended
 
 __all__ = [
     "Prompt",
-    "PromptMessageExtended",
     # Helpers
     "get_text",
     "get_image_data",
@@ -51,4 +49,5 @@ def __getattr__(name: str):
         from .prompt import Prompt  # local import
 
         return Prompt
+
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

fast_agent/mcp/mcp_aggregator.py

@@ -461,6 +461,37 @@ class MCPAggregator(ContextDependent):
         for server_name in self.server_names:
             await self._refresh_server_tools(server_name)
 
+    async def get_server_instructions(self) -> Dict[str, tuple[str, List[str]]]:
+        """
+        Get instructions from all connected servers along with their tool names.
+
+        Returns:
+            Dict mapping server name to tuple of (instructions, list of tool names)
+        """
+        instructions = {}
+
+        if self.connection_persistence and hasattr(self, "_persistent_connection_manager"):
+            # Get instructions from persistent connections
+            for server_name in self.server_names:
+                try:
+                    server_conn = await self._persistent_connection_manager.get_server(
+                        server_name,
+                        client_session_factory=self._create_session_factory(server_name),
+                    )
+                    # Always include server, even if no instructions
+                    # Get tool names for this server
+                    tool_names = [
+                        namespaced_tool.tool.name
+                        for namespaced_tool_name, namespaced_tool in self._namespaced_tool_map.items()
+                        if namespaced_tool.server_name == server_name
+                    ]
+                    # Include server even if instructions is None
+                    instructions[server_name] = (server_conn.server_instructions, tool_names)
+                except Exception as e:
+                    logger.debug(f"Failed to get instructions from server {server_name}: {e}")
+
+        return instructions
+
     async def _execute_on_server(
         self,
         server_name: str,
@@ -1044,7 +1075,9 @@ class MCPAggregator(ContextDependent):
             logger.debug(f"Server '{server_name}' does not support tools")
             return
 
-        await self.display.show_tool_update(aggregator=self, updated_server=server_name)
+        await self.display.show_tool_update(
+            updated_server=server_name, agent_name="Tool List Change Notification"
+        )
 
         async with self._refresh_lock:
             try:

fast_agent/mcp/mcp_connection_manager.py

@@ -105,6 +105,9 @@ class ServerConnection:
         self._error_occurred = False
         self._error_message = None
 
+        # Server instructions from initialization
+        self.server_instructions: str | None = None
+
     def is_healthy(self) -> bool:
         """Check if the server connection is healthy and ready to use."""
         return self.session is not None and not self._error_occurred
@@ -131,10 +134,20 @@ class ServerConnection:
         Initializes the server connection and session.
         Must be called within an async context.
         """
-
+        assert self.session, "Session must be created before initialization"
         result = await self.session.initialize()
 
         self.server_capabilities = result.capabilities
+
+        # Store instructions if provided by the server and enabled in config
+        if self.server_config.include_instructions:
+            self.server_instructions = getattr(result, 'instructions', None)
+            if self.server_instructions:
+                logger.debug(f"{self.server_name}: Received server instructions", data={"instructions": self.server_instructions})
+        else:
+            self.server_instructions = None
+            logger.debug(f"{self.server_name}: Server instructions disabled by configuration")
+
         # If there's an init hook, run it
 
         # Now the session is ready for use
@@ -343,7 +356,9 @@ class MCPConnectionManager(ContextDependent):
         def transport_context_factory():
             if config.transport == "stdio":
                 if not config.command:
-                    raise ValueError(f"Server '{server_name}' uses stdio transport but no command is specified")
+                    raise ValueError(
+                        f"Server '{server_name}' uses stdio transport but no command is specified"
+                    )
                 server_params = StdioServerParameters(
                     command=config.command,
                     args=config.args if config.args is not None else [],
@@ -357,7 +372,9 @@ class MCPConnectionManager(ContextDependent):
                 return _add_none_to_context(stdio_client(server_params, errlog=error_handler))
             elif config.transport == "sse":
                 if not config.url:
-                    raise ValueError(f"Server '{server_name}' uses sse transport but no url is specified")
+                    raise ValueError(
+                        f"Server '{server_name}' uses sse transport but no url is specified"
+                    )
                 # Suppress MCP library error spam
                 self._suppress_mcp_sse_errors()
                 oauth_auth = build_oauth_provider(config)
@@ -376,7 +393,9 @@ class MCPConnectionManager(ContextDependent):
                 )
             elif config.transport == "http":
                 if not config.url:
-                    raise ValueError(f"Server '{server_name}' uses http transport but no url is specified")
+                    raise ValueError(
+                        f"Server '{server_name}' uses http transport but no url is specified"
+                    )
                 oauth_auth = build_oauth_provider(config)
                 headers = dict(config.headers or {})
                 if oauth_auth is not None:

fast_agent/mcp/oauth_client.py

@@ -109,7 +109,7 @@ class _CallbackHandler(BaseHTTPRequestHandler):
             self.send_response(404)
             self.end_headers()
 
-    def log_message(self, fmt: str, *args: Any) -> None:  # silence default logging
+    def log_message(self, format: str, *args: Any) -> None:  # silence default logging
         return
 
 
@@ -218,10 +218,33 @@ def keyring_has_token(server_config: MCPServerSettings) -> bool:
         return False
 
 
-async def _print_authorization_link(auth_url: str) -> None:
-    """Emit a clickable authorization link using rich console markup."""
+async def _print_authorization_link(auth_url: str, warn_if_no_keyring: bool = False) -> None:
+    """Emit a clickable authorization link using rich console markup.
+
+    If warn_if_no_keyring is True and the OS keyring backend is unavailable,
+    print a warning to indicate tokens won't be persisted.
+    """
     console.console.print("[bold]Open this link to authorize:[/bold]", markup=True)
     console.console.print(f"[link={auth_url}]{auth_url}[/link]")
+    if warn_if_no_keyring:
+        try:
+            import keyring  # type: ignore
+
+            backend = keyring.get_keyring()
+            try:
+                from keyring.backends.fail import Keyring as FailKeyring  # type: ignore
+
+                if isinstance(backend, FailKeyring):
+                    console.console.print(
+                        "[yellow]Warning:[/yellow] Keyring backend not available — tokens will not be persisted."
+                    )
+            except Exception:
+                # If we cannot detect the fail backend, do nothing
+                pass
+        except Exception:
+            console.console.print(
+                "[yellow]Warning:[/yellow] Keyring backend not available — tokens will not be persisted."
+            )
     logger.info("OAuth authorization URL emitted to console")
 
 
@@ -283,6 +306,7 @@ class KeyringTokenStorage(TokenStorage):
 
 # --- Keyring index helpers (to enable cross-platform token enumeration) ---
 
+
 def _index_username() -> str:
     return "oauth:index"
 
@@ -431,7 +455,11 @@ def build_oauth_provider(server_config: MCPServerSettings) -> OAuthClientProvide
 
     # Local callback server handler
     async def _redirect_handler(authorization_url: str) -> None:
-        await _print_authorization_link(authorization_url)
+        # Warn if persisting to keyring but no backend is available
+        await _print_authorization_link(
+            authorization_url,
+            warn_if_no_keyring=(persist_mode == "keyring"),
+        )
 
     async def _callback_handler() -> tuple[str, str | None]:
         # Try local HTTP capture first

fast_agent/mcp/prompt_message_extended.py

@@ -12,6 +12,8 @@ from mcp.types import (
 from pydantic import BaseModel
 
 from fast_agent.mcp.helpers.content_helpers import get_text
+
+# Import directly to avoid circular dependency with types/__init__.py
 from fast_agent.types.llm_stop_reason import LlmStopReason