agentrun-sdk 0.1.2__py3-none-any.whl

agentrun_sdk/tools/loader.py

@@ -0,0 +1,152 @@
+"""Tool loading utilities."""
+
+import importlib
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import cast
+
+from ..types.tools import AgentTool
+from .decorator import DecoratedFunctionTool
+from .tools import PythonAgentTool
+
+logger = logging.getLogger(__name__)
+
+
+class ToolLoader:
+    """Handles loading of tools from different sources."""
+
+    @staticmethod
+    def load_python_tool(tool_path: str, tool_name: str) -> AgentTool:
+        """Load a Python tool module.
+
+        Args:
+            tool_path: Path to the Python tool file.
+            tool_name: Name of the tool.
+
+        Returns:
+            Tool instance.
+
+        Raises:
+            AttributeError: If required attributes are missing from the tool module.
+            ImportError: If there are issues importing the tool module.
+            TypeError: If the tool function is not callable.
+            ValueError: If function in module is not a valid tool.
+            Exception: For other errors during tool loading.
+        """
+        try:
+            # Check if tool_path is in the format "package.module:function"; but keep in mind windows whose file path
+            # could have a colon so also ensure that it's not a file
+            if not os.path.exists(tool_path) and ":" in tool_path:
+                module_path, function_name = tool_path.rsplit(":", 1)
+                logger.debug("tool_name=<%s>, module_path=<%s> | importing tool from path", function_name, module_path)
+
+                try:
+                    # Import the module
+                    module = __import__(module_path, fromlist=["*"])
+
+                    # Get the function
+                    if not hasattr(module, function_name):
+                        raise AttributeError(f"Module {module_path} has no function named {function_name}")
+
+                    func = getattr(module, function_name)
+
+                    if isinstance(func, DecoratedFunctionTool):
+                        logger.debug(
+                            "tool_name=<%s>, module_path=<%s> | found function-based tool", function_name, module_path
+                        )
+                        # mypy has problems converting between DecoratedFunctionTool <-> AgentTool
+                        return cast(AgentTool, func)
+                    else:
+                        raise ValueError(
+                            f"Function {function_name} in {module_path} is not a valid tool (missing @tool decorator)"
+                        )
+
+                except ImportError as e:
+                    raise ImportError(f"Failed to import module {module_path}: {str(e)}") from e
+
+            # Normal file-based tool loading
+            abs_path = str(Path(tool_path).resolve())
+
+            logger.debug("tool_path=<%s> | loading python tool from path", abs_path)
+
+            # First load the module to get TOOL_SPEC and check for Lambda deployment
+            spec = importlib.util.spec_from_file_location(tool_name, abs_path)
+            if not spec:
+                raise ImportError(f"Could not create spec for {tool_name}")
+            if not spec.loader:
+                raise ImportError(f"No loader available for {tool_name}")
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[tool_name] = module
+            spec.loader.exec_module(module)
+
+            # First, check for function-based tools with @tool decorator
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if isinstance(attr, DecoratedFunctionTool):
+                    logger.debug(
+                        "tool_name=<%s>, tool_path=<%s> | found function-based tool in path", attr_name, tool_path
+                    )
+                    # mypy has problems converting between DecoratedFunctionTool <-> AgentTool
+                    return cast(AgentTool, attr)
+
+            # If no function-based tools found, fall back to traditional module-level tool
+            tool_spec = getattr(module, "TOOL_SPEC", None)
+            if not tool_spec:
+                raise AttributeError(
+                    f"Tool {tool_name} missing TOOL_SPEC (neither at module level nor as a decorated function)"
+                )
+
+            # Standard local tool loading
+            tool_func_name = tool_name
+            if not hasattr(module, tool_func_name):
+                raise AttributeError(f"Tool {tool_name} missing function {tool_func_name}")
+
+            tool_func = getattr(module, tool_func_name)
+            if not callable(tool_func):
+                raise TypeError(f"Tool {tool_name} function is not callable")
+
+            return PythonAgentTool(tool_name, tool_spec, tool_func)
+
+        except Exception:
+            logger.exception("tool_name=<%s>, sys_path=<%s> | failed to load python tool", tool_name, sys.path)
+            raise
+
+    @classmethod
+    def load_tool(cls, tool_path: str, tool_name: str) -> AgentTool:
+        """Load a tool based on its file extension.
+
+        Args:
+            tool_path: Path to the tool file.
+            tool_name: Name of the tool.
+
+        Returns:
+            Tool instance.
+
+        Raises:
+            FileNotFoundError: If the tool file does not exist.
+            ValueError: If the tool file has an unsupported extension.
+            Exception: For other errors during tool loading.
+        """
+        ext = Path(tool_path).suffix.lower()
+        abs_path = str(Path(tool_path).resolve())
+
+        if not os.path.exists(abs_path):
+            raise FileNotFoundError(f"Tool file not found: {abs_path}")
+
+        try:
+            if ext == ".py":
+                return cls.load_python_tool(abs_path, tool_name)
+            else:
+                raise ValueError(f"Unsupported tool file type: {ext}")
+        except Exception:
+            logger.exception(
+                "tool_name=<%s>, tool_path=<%s>, tool_ext=<%s>, cwd=<%s> | failed to load tool",
+                tool_name,
+                abs_path,
+                ext,
+                os.getcwd(),
+            )
+            raise

agentrun_sdk/tools/mcp/__init__.py

@@ -0,0 +1,13 @@
+"""Model Context Protocol (MCP) integration.
+
+This package provides integration with the Model Context Protocol (MCP), allowing agents to use tools provided by MCP
+servers.
+
+- Docs: https://www.anthropic.com/news/model-context-protocol
+"""
+
+from .mcp_agent_tool import MCPAgentTool
+from .mcp_client import MCPClient
+from .mcp_types import MCPTransport
+
+__all__ = ["MCPAgentTool", "MCPClient", "MCPTransport"]

agentrun_sdk/tools/mcp/mcp_agent_tool.py

@@ -0,0 +1,99 @@
+"""MCP Agent Tool module for adapting Model Context Protocol tools to the agent framework.
+
+This module provides the MCPAgentTool class which serves as an adapter between
+MCP (Model Context Protocol) tools and the agent framework's tool interface.
+It allows MCP tools to be seamlessly integrated and used within the agent ecosystem.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import Tool as MCPTool
+from typing_extensions import override
+
+from ...types.tools import AgentTool, ToolGenerator, ToolSpec, ToolUse
+
+if TYPE_CHECKING:
+    from .mcp_client import MCPClient
+
+logger = logging.getLogger(__name__)
+
+
+class MCPAgentTool(AgentTool):
+    """Adapter class that wraps an MCP tool and exposes it as an AgentTool.
+
+    This class bridges the gap between the MCP protocol's tool representation
+    and the agent framework's tool interface, allowing MCP tools to be used
+    seamlessly within the agent framework.
+    """
+
+    def __init__(self, mcp_tool: MCPTool, mcp_client: "MCPClient") -> None:
+        """Initialize a new MCPAgentTool instance.
+
+        Args:
+            mcp_tool: The MCP tool to adapt
+            mcp_client: The MCP server connection to use for tool invocation
+        """
+        super().__init__()
+        logger.debug("tool_name=<%s> | creating mcp agent tool", mcp_tool.name)
+        self.mcp_tool = mcp_tool
+        self.mcp_client = mcp_client
+
+    @property
+    def tool_name(self) -> str:
+        """Get the name of the tool.
+
+        Returns:
+            str: The name of the MCP tool
+        """
+        return self.mcp_tool.name
+
+    @property
+    def tool_spec(self) -> ToolSpec:
+        """Get the specification of the tool.
+
+        This method converts the MCP tool specification to the agent framework's
+        ToolSpec format, including the input schema and description.
+
+        Returns:
+            ToolSpec: The tool specification in the agent framework format
+        """
+        description: str = self.mcp_tool.description or f"Tool which performs {self.mcp_tool.name}"
+        return {
+            "inputSchema": {"json": self.mcp_tool.inputSchema},
+            "name": self.mcp_tool.name,
+            "description": description,
+        }
+
+    @property
+    def tool_type(self) -> str:
+        """Get the type of the tool.
+
+        Returns:
+            str: The type of the tool, always "python" for MCP tools
+        """
+        return "python"
+
+    @override
+    async def stream(self, tool_use: ToolUse, invocation_state: dict[str, Any], **kwargs: Any) -> ToolGenerator:
+        """Stream the MCP tool.
+
+        This method delegates the tool stream to the MCP server connection, passing the tool use ID, tool name, and
+        input arguments.
+
+        Args:
+            tool_use: The tool use request containing tool ID and parameters.
+            invocation_state: Context for the tool invocation, including agent state.
+            **kwargs: Additional keyword arguments for future extensibility.
+
+        Yields:
+            Tool events with the last being the tool result.
+        """
+        logger.debug("tool_name=<%s>, tool_use_id=<%s> | streaming", self.tool_name, tool_use["toolUseId"])
+
+        result = await self.mcp_client.call_tool_async(
+            tool_use_id=tool_use["toolUseId"],
+            name=self.tool_name,
+            arguments=tool_use["input"],
+        )
+        yield result

agentrun_sdk/tools/mcp/mcp_client.py

@@ -0,0 +1,423 @@
+"""Model Context Protocol (MCP) server connection management module.
+
+This module provides the MCPClient class which handles connections to MCP servers.
+It manages the lifecycle of MCP connections, including initialization, tool discovery,
+tool invocation, and proper cleanup of resources. The connection runs in a background
+thread to avoid blocking the main application thread while maintaining communication
+with the MCP service.
+"""
+
+import asyncio
+import base64
+import logging
+import threading
+import uuid
+from asyncio import AbstractEventLoop
+from concurrent import futures
+from datetime import timedelta
+from types import TracebackType
+from typing import Any, Callable, Coroutine, Dict, Optional, TypeVar, Union
+
+from mcp import ClientSession, ListToolsResult
+from mcp.types import CallToolResult as MCPCallToolResult
+from mcp.types import GetPromptResult, ListPromptsResult
+from mcp.types import ImageContent as MCPImageContent
+from mcp.types import TextContent as MCPTextContent
+
+from ...types import PaginatedList
+from ...types.exceptions import MCPClientInitializationError
+from ...types.media import ImageFormat
+from ...types.tools import ToolResultContent, ToolResultStatus
+from .mcp_agent_tool import MCPAgentTool
+from .mcp_instrumentation import mcp_instrumentation
+from .mcp_types import MCPToolResult, MCPTransport
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+MIME_TO_FORMAT: Dict[str, ImageFormat] = {
+    "image/jpeg": "jpeg",
+    "image/jpg": "jpeg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+}
+
+CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE = (
+    "the client session is not running. Ensure the agent is used within "
+    "the MCP client context manager. For more information see: "
+    "https://strandsagents.com/latest/user-guide/concepts/tools/mcp-tools/#mcpclientinitializationerror"
+)
+
+
+class MCPClient:
+    """Represents a connection to a Model Context Protocol (MCP) server.
+
+    This class implements a context manager pattern for efficient connection management,
+    allowing reuse of the same connection for multiple tool calls to reduce latency.
+    It handles the creation, initialization, and cleanup of MCP connections.
+
+    The connection runs in a background thread to avoid blocking the main application thread
+    while maintaining communication with the MCP service. When structured content is available
+    from MCP tools, it will be returned as the last item in the content array of the ToolResult.
+    """
+
+    def __init__(self, transport_callable: Callable[[], MCPTransport]):
+        """Initialize a new MCP Server connection.
+
+        Args:
+            transport_callable: A callable that returns an MCPTransport (read_stream, write_stream) tuple
+        """
+        mcp_instrumentation()
+        self._session_id = uuid.uuid4()
+        self._log_debug_with_thread("initializing MCPClient connection")
+        self._init_future: futures.Future[None] = futures.Future()  # Main thread blocks until future completes
+        self._close_event = asyncio.Event()  # Do not want to block other threads while close event is false
+        self._transport_callable = transport_callable
+
+        self._background_thread: threading.Thread | None = None
+        self._background_thread_session: ClientSession
+        self._background_thread_event_loop: AbstractEventLoop
+
+    def __enter__(self) -> "MCPClient":
+        """Context manager entry point which initializes the MCP server connection."""
+        return self.start()
+
+    def __exit__(self, exc_type: BaseException, exc_val: BaseException, exc_tb: TracebackType) -> None:
+        """Context manager exit point that cleans up resources."""
+        self.stop(exc_type, exc_val, exc_tb)
+
+    def start(self) -> "MCPClient":
+        """Starts the background thread and waits for initialization.
+
+        This method starts the background thread that manages the MCP connection
+        and blocks until the connection is ready or times out.
+
+        Returns:
+            self: The MCPClient instance
+
+        Raises:
+            Exception: If the MCP connection fails to initialize within the timeout period
+        """
+        if self._is_session_active():
+            raise MCPClientInitializationError("the client session is currently running")
+
+        self._log_debug_with_thread("entering MCPClient context")
+        self._background_thread = threading.Thread(target=self._background_task, args=[], daemon=True)
+        self._background_thread.start()
+        self._log_debug_with_thread("background thread started, waiting for ready event")
+        try:
+            # Blocking main thread until session is initialized in other thread or if the thread stops
+            self._init_future.result(timeout=30)
+            self._log_debug_with_thread("the client initialization was successful")
+        except futures.TimeoutError as e:
+            raise MCPClientInitializationError("background thread did not start in 30 seconds") from e
+        except Exception as e:
+            logger.exception("client failed to initialize")
+            raise MCPClientInitializationError("the client initialization failed") from e
+        return self
+
+    def stop(
+        self, exc_type: Optional[BaseException], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]
+    ) -> None:
+        """Signals the background thread to stop and waits for it to complete, ensuring proper cleanup of all resources.
+
+        Args:
+            exc_type: Exception type if an exception was raised in the context
+            exc_val: Exception value if an exception was raised in the context
+            exc_tb: Exception traceback if an exception was raised in the context
+        """
+        self._log_debug_with_thread("exiting MCPClient context")
+
+        async def _set_close_event() -> None:
+            self._close_event.set()
+
+        self._invoke_on_background_thread(_set_close_event()).result()
+        self._log_debug_with_thread("waiting for background thread to join")
+        if self._background_thread is not None:
+            self._background_thread.join()
+        self._log_debug_with_thread("background thread joined, MCPClient context exited")
+
+        # Reset fields to allow instance reuse
+        self._init_future = futures.Future()
+        self._close_event = asyncio.Event()
+        self._background_thread = None
+        self._session_id = uuid.uuid4()
+
+    def list_tools_sync(self, pagination_token: Optional[str] = None) -> PaginatedList[MCPAgentTool]:
+        """Synchronously retrieves the list of available tools from the MCP server.
+
+        This method calls the asynchronous list_tools method on the MCP session
+        and adapts the returned tools to the AgentTool interface.
+
+        Returns:
+            List[AgentTool]: A list of available tools adapted to the AgentTool interface
+        """
+        self._log_debug_with_thread("listing MCP tools synchronously")
+        if not self._is_session_active():
+            raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE)
+
+        async def _list_tools_async() -> ListToolsResult:
+            return await self._background_thread_session.list_tools(cursor=pagination_token)
+
+        list_tools_response: ListToolsResult = self._invoke_on_background_thread(_list_tools_async()).result()
+        self._log_debug_with_thread("received %d tools from MCP server", len(list_tools_response.tools))
+
+        mcp_tools = [MCPAgentTool(tool, self) for tool in list_tools_response.tools]
+        self._log_debug_with_thread("successfully adapted %d MCP tools", len(mcp_tools))
+        return PaginatedList[MCPAgentTool](mcp_tools, token=list_tools_response.nextCursor)
+
+    def list_prompts_sync(self, pagination_token: Optional[str] = None) -> ListPromptsResult:
+        """Synchronously retrieves the list of available prompts from the MCP server.
+
+        This method calls the asynchronous list_prompts method on the MCP session
+        and returns the raw ListPromptsResult with pagination support.
+
+        Args:
+            pagination_token: Optional token for pagination
+
+        Returns:
+            ListPromptsResult: The raw MCP response containing prompts and pagination info
+        """
+        self._log_debug_with_thread("listing MCP prompts synchronously")
+        if not self._is_session_active():
+            raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE)
+
+        async def _list_prompts_async() -> ListPromptsResult:
+            return await self._background_thread_session.list_prompts(cursor=pagination_token)
+
+        list_prompts_result: ListPromptsResult = self._invoke_on_background_thread(_list_prompts_async()).result()
+        self._log_debug_with_thread("received %d prompts from MCP server", len(list_prompts_result.prompts))
+        for prompt in list_prompts_result.prompts:
+            self._log_debug_with_thread(prompt.name)
+
+        return list_prompts_result
+
+    def get_prompt_sync(self, prompt_id: str, args: dict[str, Any]) -> GetPromptResult:
+        """Synchronously retrieves a prompt from the MCP server.
+
+        Args:
+            prompt_id: The ID of the prompt to retrieve
+            args: Optional arguments to pass to the prompt
+
+        Returns:
+            GetPromptResult: The prompt response from the MCP server
+        """
+        self._log_debug_with_thread("getting MCP prompt synchronously")
+        if not self._is_session_active():
+            raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE)
+
+        async def _get_prompt_async() -> GetPromptResult:
+            return await self._background_thread_session.get_prompt(prompt_id, arguments=args)
+
+        get_prompt_result: GetPromptResult = self._invoke_on_background_thread(_get_prompt_async()).result()
+        self._log_debug_with_thread("received prompt from MCP server")
+
+        return get_prompt_result
+
+    def call_tool_sync(
+        self,
+        tool_use_id: str,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: timedelta | None = None,
+    ) -> MCPToolResult:
+        """Synchronously calls a tool on the MCP server.
+
+        This method calls the asynchronous call_tool method on the MCP session
+        and converts the result to the ToolResult format. If the MCP tool returns
+        structured content, it will be included as the last item in the content array
+        of the returned ToolResult.
+
+        Args:
+            tool_use_id: Unique identifier for this tool use
+            name: Name of the tool to call
+            arguments: Optional arguments to pass to the tool
+            read_timeout_seconds: Optional timeout for the tool call
+
+        Returns:
+            MCPToolResult: The result of the tool call
+        """
+        self._log_debug_with_thread("calling MCP tool '%s' synchronously with tool_use_id=%s", name, tool_use_id)
+        if not self._is_session_active():
+            raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE)
+
+        async def _call_tool_async() -> MCPCallToolResult:
+            return await self._background_thread_session.call_tool(name, arguments, read_timeout_seconds)
+
+        try:
+            call_tool_result: MCPCallToolResult = self._invoke_on_background_thread(_call_tool_async()).result()
+            return self._handle_tool_result(tool_use_id, call_tool_result)
+        except Exception as e:
+            logger.exception("tool execution failed")
+            return self._handle_tool_execution_error(tool_use_id, e)
+
+    async def call_tool_async(
+        self,
+        tool_use_id: str,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: timedelta | None = None,
+    ) -> MCPToolResult:
+        """Asynchronously calls a tool on the MCP server.
+
+        This method calls the asynchronous call_tool method on the MCP session
+        and converts the result to the MCPToolResult format.
+
+        Args:
+            tool_use_id: Unique identifier for this tool use
+            name: Name of the tool to call
+            arguments: Optional arguments to pass to the tool
+            read_timeout_seconds: Optional timeout for the tool call
+
+        Returns:
+            MCPToolResult: The result of the tool call
+        """
+        self._log_debug_with_thread("calling MCP tool '%s' asynchronously with tool_use_id=%s", name, tool_use_id)
+        if not self._is_session_active():
+            raise MCPClientInitializationError(CLIENT_SESSION_NOT_RUNNING_ERROR_MESSAGE)
+
+        async def _call_tool_async() -> MCPCallToolResult:
+            return await self._background_thread_session.call_tool(name, arguments, read_timeout_seconds)
+
+        try:
+            future = self._invoke_on_background_thread(_call_tool_async())
+            call_tool_result: MCPCallToolResult = await asyncio.wrap_future(future)
+            return self._handle_tool_result(tool_use_id, call_tool_result)
+        except Exception as e:
+            logger.exception("tool execution failed")
+            return self._handle_tool_execution_error(tool_use_id, e)
+
+    def _handle_tool_execution_error(self, tool_use_id: str, exception: Exception) -> MCPToolResult:
+        """Create error ToolResult with consistent logging."""
+        return MCPToolResult(
+            status="error",
+            toolUseId=tool_use_id,
+            content=[{"text": f"Tool execution failed: {str(exception)}"}],
+        )
+
+    def _handle_tool_result(self, tool_use_id: str, call_tool_result: MCPCallToolResult) -> MCPToolResult:
+        """Maps MCP tool result to the agent's MCPToolResult format.
+
+        This method processes the content from the MCP tool call result and converts it to the format
+        expected by the framework.
+
+        Args:
+            tool_use_id: Unique identifier for this tool use
+            call_tool_result: The result from the MCP tool call
+
+        Returns:
+            MCPToolResult: The converted tool result
+        """
+        self._log_debug_with_thread("received tool result with %d content items", len(call_tool_result.content))
+
+        mapped_content = [
+            mapped_content
+            for content in call_tool_result.content
+            if (mapped_content := self._map_mcp_content_to_tool_result_content(content)) is not None
+        ]
+
+        status: ToolResultStatus = "error" if call_tool_result.isError else "success"
+        self._log_debug_with_thread("tool execution completed with status: %s", status)
+        result = MCPToolResult(
+            status=status,
+            toolUseId=tool_use_id,
+            content=mapped_content,
+        )
+        if call_tool_result.structuredContent:
+            result["structuredContent"] = call_tool_result.structuredContent
+
+        return result
+
+    async def _async_background_thread(self) -> None:
+        """Asynchronous method that runs in the background thread to manage the MCP connection.
+
+        This method establishes the transport connection, creates and initializes the MCP session,
+        signals readiness to the main thread, and waits for a close signal.
+        """
+        self._log_debug_with_thread("starting async background thread for MCP connection")
+        try:
+            async with self._transport_callable() as (read_stream, write_stream, *_):
+                self._log_debug_with_thread("transport connection established")
+                async with ClientSession(read_stream, write_stream) as session:
+                    self._log_debug_with_thread("initializing MCP session")
+                    await session.initialize()
+
+                    self._log_debug_with_thread("session initialized successfully")
+                    # Store the session for use while we await the close event
+                    self._background_thread_session = session
+                    self._init_future.set_result(None)  # Signal that the session has been created and is ready for use
+
+                    self._log_debug_with_thread("waiting for close signal")
+                    # Keep background thread running until signaled to close.
+                    # Thread is not blocked as this is an asyncio.Event not a threading.Event
+                    await self._close_event.wait()
+                    self._log_debug_with_thread("close signal received")
+        except Exception as e:
+            # If we encounter an exception and the future is still running,
+            # it means it was encountered during the initialization phase.
+            if not self._init_future.done():
+                self._init_future.set_exception(e)
+            else:
+                self._log_debug_with_thread(
+                    "encountered exception on background thread after initialization %s", str(e)
+                )
+
+    def _background_task(self) -> None:
+        """Sets up and runs the event loop in the background thread.
+
+        This method creates a new event loop for the background thread,
+        sets it as the current event loop, and runs the async_background_thread
+        coroutine until completion. In this case "until completion" means until the _close_event is set.
+        This allows for a long-running event loop.
+        """
+        self._log_debug_with_thread("setting up background task event loop")
+        self._background_thread_event_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._background_thread_event_loop)
+        self._background_thread_event_loop.run_until_complete(self._async_background_thread())
+
+    def _map_mcp_content_to_tool_result_content(
+        self,
+        content: MCPTextContent | MCPImageContent | Any,
+    ) -> Union[ToolResultContent, None]:
+        """Maps MCP content types to tool result content types.
+
+        This method converts MCP-specific content types to the generic
+        ToolResultContent format used by the agent framework.
+
+        Args:
+            content: The MCP content to convert
+
+        Returns:
+            ToolResultContent or None: The converted content, or None if the content type is not supported
+        """
+        if isinstance(content, MCPTextContent):
+            self._log_debug_with_thread("mapping MCP text content")
+            return {"text": content.text}
+        elif isinstance(content, MCPImageContent):
+            self._log_debug_with_thread("mapping MCP image content with mime type: %s", content.mimeType)
+            return {
+                "image": {
+                    "format": MIME_TO_FORMAT[content.mimeType],
+                    "source": {"bytes": base64.b64decode(content.data)},
+                }
+            }
+        else:
+            self._log_debug_with_thread("unhandled content type: %s - dropping content", content.__class__.__name__)
+            return None
+
+    def _log_debug_with_thread(self, msg: str, *args: Any, **kwargs: Any) -> None:
+        """Logger helper to help differentiate logs coming from MCPClient background thread."""
+        formatted_msg = msg % args if args else msg
+        logger.debug(
+            "[Thread: %s, Session: %s] %s", threading.current_thread().name, self._session_id, formatted_msg, **kwargs
+        )
+
+    def _invoke_on_background_thread(self, coro: Coroutine[Any, Any, T]) -> futures.Future[T]:
+        if self._background_thread_session is None or self._background_thread_event_loop is None:
+            raise MCPClientInitializationError("the client session was not initialized")
+        return asyncio.run_coroutine_threadsafe(coro=coro, loop=self._background_thread_event_loop)
+
+    def _is_session_active(self) -> bool:
+        return self._background_thread is not None and self._background_thread.is_alive()