mcp-use 1.3.8__py3-none-any.whl → 1.3.10__py3-none-any.whl

mcp_use/__init__.py

@@ -7,12 +7,16 @@ to MCP tools through existing LangChain adapters.
 
 from importlib.metadata import version
 
-from . import observability
+# Import logging FIRST to ensure it's configured before other modules
+# This MUST happen before importing observability to ensure loggers are configured
+from .logging import MCP_USE_DEBUG, Logger, logger  # isort: skip
+
+# Now import other modules - observability must come after logging
+from . import observability  # noqa: E402
 from .agents.mcpagent import MCPAgent
 from .client import MCPClient
 from .config import load_config_file
 from .connectors import BaseConnector, HttpConnector, StdioConnector, WebSocketConnector
-from .logging import MCP_USE_DEBUG, Logger, logger
 from .session import MCPSession
 
 __version__ = version("mcp-use")
@@ -25,7 +29,6 @@ __all__ = [
     "StdioConnector",
     "WebSocketConnector",
     "HttpConnector",
-    "create_session_from_config",
     "load_config_file",
     "logger",
     "MCP_USE_DEBUG",

mcp_use/adapters/base.py

@@ -91,14 +91,14 @@ class BaseAdapter(ABC):
 
         connector_tools = []
         # Now create tools for each MCP tool
-        for tool in connector.tools:
+        for tool in await connector.list_tools():
             # Convert the tool and add it to the list if conversion was successful
             converted_tool = self._convert_tool(tool, connector)
             if converted_tool:
                 connector_tools.append(converted_tool)
 
         # Convert resources to tools so that agents can access resource content directly
-        resources_list = connector.resources or []
+        resources_list = await connector.list_resources() or []
         if resources_list:
             for resource in resources_list:
                 converted_resource = self._convert_resource(resource, connector)
@@ -106,7 +106,7 @@ class BaseAdapter(ABC):
                     connector_tools.append(converted_resource)
 
         # Convert prompts to tools so that agents can retrieve prompt content
-        prompts_list = connector.prompts or []
+        prompts_list = await connector.list_prompts() or []
         if prompts_list:
             for prompt in prompts_list:
                 converted_prompt = self._convert_prompt(prompt, connector)

mcp_use/adapters/langchain_adapter.py

@@ -21,6 +21,7 @@ from mcp.types import (
 from pydantic import BaseModel, Field, create_model
 
 from ..connectors.base import BaseConnector
+from ..errors.error_formatting import format_error
 from ..logging import logger
 from .base import BaseAdapter
 
@@ -159,11 +160,11 @@ class LangChainAdapter(BaseAdapter):
                     except Exception as e:
                         # Log the exception for debugging
                         logger.error(f"Error parsing tool result: {e}")
-                        return f"Error parsing result: {e!s}; Raw content: {tool_result.content!r}"
+                        return format_error(e, tool=self.name, tool_content=tool_result.content)
 
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error executing MCP tool: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return McpToLangChainAdapter()
@@ -204,7 +205,7 @@ class LangChainAdapter(BaseAdapter):
                     return content_decoded
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error reading resource: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return ResourceTool()
@@ -261,7 +262,7 @@ class LangChainAdapter(BaseAdapter):
                     return result.messages
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error fetching prompt: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return PromptTool()

mcp_use/agents/mcpagent.py

@@ -30,7 +30,11 @@ from mcp_use.telemetry.utils import extract_model_info
 
 from ..adapters.langchain_adapter import LangChainAdapter
 from ..logging import logger
+from ..managers.base import BaseServerManager
 from ..managers.server_manager import ServerManager
+
+# Import observability manager
+from ..observability import ObservabilityManager
 from .prompts.system_prompt_builder import create_system_message
 from .prompts.templates import DEFAULT_SYSTEM_PROMPT_TEMPLATE, SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE
 from .remote import RemoteAgent
@@ -62,10 +66,15 @@ class MCPAgent:
         disallowed_tools: list[str] | None = None,
         tools_used_names: list[str] | None = None,
         use_server_manager: bool = False,
+        server_manager: BaseServerManager | None = None,
         verbose: bool = False,
         agent_id: str | None = None,
         api_key: str | None = None,
         base_url: str = "https://cloud.mcp-use.com",
+        callbacks: list | None = None,
+        chat_id: str | None = None,
+        retry_on_error: bool = True,
+        max_retries_per_step: int = 2,
     ):
         """Initialize a new MCPAgent instance.
 
@@ -84,10 +93,13 @@ class MCPAgent:
             agent_id: Remote agent ID for remote execution. If provided, creates a remote agent.
             api_key: API key for remote execution. If None, checks MCP_USE_API_KEY env var.
             base_url: Base URL for remote API calls.
+            callbacks: List of LangChain callbacks to use. If None and Langfuse is configured, uses langfuse_handler.
+            retry_on_error: Whether to retry tool calls that fail due to validation errors.
+            max_retries_per_step: Maximum number of retries for validation errors per step.
         """
         # Handle remote execution
         if agent_id is not None:
-            self._remote_agent = RemoteAgent(agent_id=agent_id, api_key=api_key, base_url=base_url)
+            self._remote_agent = RemoteAgent(agent_id=agent_id, api_key=api_key, base_url=base_url, chat_id=chat_id)
             self._is_remote = True
             return
 
@@ -109,13 +121,20 @@ class MCPAgent:
         self.disallowed_tools = disallowed_tools or []
         self.tools_used_names = tools_used_names or []
         self.use_server_manager = use_server_manager
+        self.server_manager = server_manager
         self.verbose = verbose
+        self.retry_on_error = retry_on_error
+        self.max_retries_per_step = max_retries_per_step
         # System prompt configuration
         self.system_prompt = system_prompt  # User-provided full prompt override
         # User can provide a template override, otherwise use the imported default
         self.system_prompt_template_override = system_prompt_template
         self.additional_instructions = additional_instructions
 
+        # Set up observability callbacks using the ObservabilityManager
+        self.observability_manager = ObservabilityManager(custom_callbacks=callbacks)
+        self.callbacks = self.observability_manager.get_callbacks()
+
         # Either client or connector must be provided
         if not client and len(self.connectors) == 0:
             raise ValueError("Either client or connector must be provided")
@@ -126,9 +145,7 @@ class MCPAgent:
         # Initialize telemetry
         self.telemetry = Telemetry()
 
-        # Initialize server manager if requested
-        self.server_manager = None
-        if self.use_server_manager:
+        if self.use_server_manager and self.server_manager is None:
             if not self.client:
                 raise ValueError("Client must be provided when using server manager")
             self.server_manager = ServerManager(self.client, self.adapter)
@@ -246,9 +263,15 @@ class MCPAgent:
         # Use the standard create_tool_calling_agent
         agent = create_tool_calling_agent(llm=self.llm, tools=self._tools, prompt=prompt)
 
-        # Use the standard AgentExecutor
-        executor = AgentExecutor(agent=agent, tools=self._tools, max_iterations=self.max_steps, verbose=self.verbose)
-        logger.debug(f"Created agent executor with max_iterations={self.max_steps}")
+        # Use the standard AgentExecutor with callbacks
+        executor = AgentExecutor(
+            agent=agent,
+            tools=self._tools,
+            max_iterations=self.max_steps,
+            verbose=self.verbose,
+            callbacks=self.callbacks,
+        )
+        logger.debug(f"Created agent executor with max_iterations={self.max_steps} and {len(self.callbacks)} callbacks")
         return executor
 
     def get_conversation_history(self) -> list[BaseMessage]:
@@ -469,6 +492,22 @@ class MCPAgent:
 
             logger.info(f"🏁 Starting agent execution with max_steps={steps}")
 
+            # Create a run manager with our callbacks if we have any - ONCE for the entire execution
+            run_manager = None
+            if self.callbacks:
+                # Create an async callback manager with our callbacks
+                from langchain_core.callbacks.manager import AsyncCallbackManager
+
+                callback_manager = AsyncCallbackManager.configure(
+                    inheritable_callbacks=self.callbacks,
+                    local_callbacks=self.callbacks,
+                )
+                # Create a run manager for this chain execution
+                run_manager = await callback_manager.on_chain_start(
+                    {"name": "MCPAgent (mcp-use)"},
+                    inputs,
+                )
+
             for step_num in range(steps):
                 steps_taken = step_num + 1
                 # --- Check for tool updates if using server manager ---
@@ -498,20 +537,51 @@ class MCPAgent:
 
                 # --- Plan and execute the next step ---
                 try:
-                    # Use the internal _atake_next_step which handles planning and execution
-                    # This requires providing the necessary context like maps and intermediate steps
-                    next_step_output = await self._agent_executor._atake_next_step(
-                        name_to_tool_map=name_to_tool_map,
-                        color_mapping=color_mapping,
-                        inputs=inputs,
-                        intermediate_steps=intermediate_steps,
-                        run_manager=None,
-                    )
+                    retry_count = 0
+                    next_step_output = None
+
+                    while retry_count <= self.max_retries_per_step:
+                        try:
+                            # Use the internal _atake_next_step which handles planning and execution
+                            # This requires providing the necessary context like maps and intermediate steps
+                            next_step_output = await self._agent_executor._atake_next_step(
+                                name_to_tool_map=name_to_tool_map,
+                                color_mapping=color_mapping,
+                                inputs=inputs,
+                                intermediate_steps=intermediate_steps,
+                                run_manager=run_manager,
+                            )
+
+                            # If we get here, the step succeeded, break out of retry loop
+                            break
+
+                        except Exception as e:
+                            if not self.retry_on_error or retry_count >= self.max_retries_per_step:
+                                logger.error(f"❌ Validation error during step {step_num + 1}: {e}")
+                                result = f"Agent stopped due to a validation error: {str(e)}"
+                                success = False
+                                yield result
+                                return
+
+                            retry_count += 1
+                            logger.warning(
+                                f"⚠️ Validation error, retrying ({retry_count}/{self.max_retries_per_step}): {e}"
+                            )
+
+                            # Create concise feedback for the LLM about the validation error
+                            error_message = f"Error: {str(e)}"
+                            inputs["input"] = error_message
+
+                            # Continue to next iteration of retry loop
+                            continue
 
                     # Process the output
                     if isinstance(next_step_output, AgentFinish):
                         logger.info(f"✅ Agent finished at step {step_num + 1}")
                         result = next_step_output.return_values.get("output", "No output generated")
+                        # End the chain if we have a run manager
+                        if run_manager:
+                            await run_manager.on_chain_end({"output": result})
 
                         # If structured output is requested, attempt to create it
                         if output_schema and structured_llm:
@@ -563,6 +633,12 @@ class MCPAgent:
                     for agent_step in next_step_output:
                         yield agent_step
                         action, observation = agent_step
+                        reasoning = getattr(action, "log", "")
+                        if reasoning:
+                            reasoning_str = reasoning.replace("\n", " ")
+                            if len(reasoning_str) > 300:
+                                reasoning_str = reasoning_str[:297] + "..."
+                            logger.info(f"💭 Reasoning: {reasoning_str}")
                         tool_name = action.tool
                         self.tools_used_names.append(tool_name)
                         tool_input_str = str(action.tool_input)
@@ -589,12 +665,17 @@ class MCPAgent:
                 except OutputParserException as e:
                     logger.error(f"❌ Output parsing error during step {step_num + 1}: {e}")
                     result = f"Agent stopped due to a parsing error: {str(e)}"
+                    if run_manager:
+                        await run_manager.on_chain_error(e)
                     break
                 except Exception as e:
                     logger.error(f"❌ Error during agent execution step {step_num + 1}: {e}")
                     import traceback
 
                     traceback.print_exc()
+                    # End the chain with error if we have a run manager
+                    if run_manager:
+                        await run_manager.on_chain_error(e)
                     result = f"Agent stopped due to an error: {str(e)}"
                     break
 
@@ -602,6 +683,8 @@ class MCPAgent:
             if not result:
                 logger.warning(f"⚠️ Agent stopped after reaching max iterations ({steps})")
                 result = f"Agent stopped after reaching the maximum number of steps ({steps})."
+                if run_manager:
+                    await run_manager.on_chain_end({"output": result})
 
             # If structured output was requested but not achieved, attempt one final time
             if output_schema and structured_llm and not success:
@@ -738,7 +821,8 @@ class MCPAgent:
         """
         # Delegate to remote agent if in remote mode
         if self._is_remote and self._remote_agent:
-            return await self._remote_agent.run(query, max_steps, manage_connector, external_history, output_schema)
+            result = await self._remote_agent.run(query, max_steps, external_history, output_schema)
+            return result
 
         success = True
         start_time = time.time()

mcp_use/agents/remote.py

@@ -5,6 +5,7 @@ Remote agent implementation for executing agents via API.
 import json
 import os
 from typing import Any, TypeVar
+from uuid import UUID
 
 import httpx
 from langchain.schema import BaseMessage
@@ -14,19 +15,52 @@ from ..logging import logger
 
 T = TypeVar("T", bound=BaseModel)
 
+# API endpoint constants
+API_CHATS_ENDPOINT = "/api/v1/chats/get-or-create"
+API_CHAT_EXECUTE_ENDPOINT = "/api/v1/chats/{chat_id}/execute"
+API_CHAT_DELETE_ENDPOINT = "/api/v1/chats/{chat_id}"
+
+UUID_ERROR_MESSAGE = """A UUID is a 36 character string of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n
+Example: 123e4567-e89b-12d3-a456-426614174000
+To generate a UUID, you can use the following command:
+import uuid
+
+# Generate a random UUID
+my_uuid = uuid.uuid4()
+print(my_uuid)
+"""
+
 
 class RemoteAgent:
     """Agent that executes remotely via API."""
 
-    def __init__(self, agent_id: str, api_key: str | None = None, base_url: str = "https://cloud.mcp-use.com"):
+    def __init__(
+        self,
+        agent_id: str,
+        chat_id: str | None = None,
+        api_key: str | None = None,
+        base_url: str = "https://cloud.mcp-use.com",
+    ):
         """Initialize remote agent.
 
         Args:
             agent_id: The ID of the remote agent to execute
+            chat_id: The ID of the chat session to use. If None, a new chat session will be created.
             api_key: API key for authentication. If None, will check MCP_USE_API_KEY env var
             base_url: Base URL for the remote API
         """
+
+        if chat_id is not None:
+            try:
+                chat_id = str(UUID(chat_id))
+            except ValueError as e:
+                raise ValueError(
+                    f"Invalid chat ID: {chat_id}, make sure to provide a valid UUID.\n{UUID_ERROR_MESSAGE}"
+                ) from e
+
         self.agent_id = agent_id
+        self.chat_id = chat_id
+        self._session_established = False
         self.base_url = base_url
 
         # Handle API key validation
@@ -103,11 +137,55 @@ class RemoteAgent:
                 return output_schema.model_validate({"content": str(result_data)})
             raise
 
+    async def _upsert_chat_session(self) -> str:
+        """Create or resume a persistent chat session for the agent via upsert.
+
+        Returns:
+            The chat session ID
+        """
+        chat_payload = {
+            "id": self.chat_id,  # Include chat_id for resuming or None for creating
+            "title": f"Remote Agent Session - {self.agent_id}",
+            "agent_id": self.agent_id,
+            "type": "agent_execution",
+        }
+
+        headers = {"Content-Type": "application/json", "x-api-key": self.api_key}
+        chat_url = f"{self.base_url}{API_CHATS_ENDPOINT}"
+
+        logger.info(f"📝 Upserting chat session for agent {self.agent_id}")
+
+        try:
+            chat_response = await self._client.post(chat_url, json=chat_payload, headers=headers)
+            chat_response.raise_for_status()
+
+            chat_data = chat_response.json()
+            chat_id = chat_data["id"]
+            if chat_response.status_code == 201:
+                logger.info(f"✅ New chat session created: {chat_id}")
+            else:
+                logger.info(f"✅ Resumed chat session: {chat_id}")
+
+            return chat_id
+
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            response_text = e.response.text
+
+            if status_code == 404:
+                raise RuntimeError(
+                    f"Agent not found: Agent '{self.agent_id}' does not exist or you don't have access to it. "
+                    "Please verify the agent ID and ensure it exists in your account."
+                ) from e
+            else:
+                raise RuntimeError(f"Failed to create chat session: {status_code} - {response_text}") from e
+        except Exception as e:
+            raise RuntimeError(f"Failed to create chat session: {str(e)}") from e
+
     async def run(
         self,
         query: str,
         max_steps: int | None = None,
-        manage_connector: bool = True,
         external_history: list[BaseMessage] | None = None,
         output_schema: type[T] | None = None,
     ) -> str | T:
@@ -116,8 +194,7 @@ class RemoteAgent:
         Args:
             query: The query to execute
             max_steps: Maximum number of steps (default: 10)
-            manage_connector: Ignored for remote execution
-            external_history: Ignored for remote execution (not supported yet)
+            external_history: External history (not supported yet for remote execution)
             output_schema: Optional Pydantic model for structured output
 
         Returns:
@@ -126,20 +203,31 @@ class RemoteAgent:
         if external_history is not None:
             logger.warning("External history is not yet supported for remote execution")
 
-        payload = {"query": query, "max_steps": max_steps or 10}
+        try:
+            logger.info(f"🌐 Executing query on remote agent {self.agent_id}")
 
-        # Add structured output schema if provided
-        if output_schema is not None:
-            payload["output_schema"] = self._pydantic_to_json_schema(output_schema)
-            logger.info(f"🔧 Using structured output with schema: {output_schema.__name__}")
+            # Step 1: Ensure chat session exists on the backend by upserting.
+            # This happens once per agent instance.
+            if not self._session_established:
+                logger.info(f"🔧 Establishing chat session for agent {self.agent_id}")
+                self.chat_id = await self._upsert_chat_session()
+                self._session_established = True
 
-        headers = {"Content-Type": "application/json", "x-api-key": self.api_key}
+            chat_id = self.chat_id
 
-        url = f"{self.base_url}/api/v1/agents/{self.agent_id}/run"
+            # Step 2: Execute the agent within the chat context
+            execution_payload = {"query": query, "max_steps": max_steps or 10}
 
-        try:
-            logger.info(f"🌐 Executing query on remote agent {self.agent_id}")
-            response = await self._client.post(url, json=payload, headers=headers)
+            # Add structured output schema if provided
+            if output_schema is not None:
+                execution_payload["output_schema"] = self._pydantic_to_json_schema(output_schema)
+                logger.info(f"🔧 Using structured output with schema: {output_schema.__name__}")
+
+            headers = {"Content-Type": "application/json", "x-api-key": self.api_key}
+            execution_url = f"{self.base_url}{API_CHAT_EXECUTE_ENDPOINT.format(chat_id=chat_id)}"
+            logger.info(f"🚀 Executing agent in chat {chat_id}")
+
+            response = await self._client.post(execution_url, json=execution_payload, headers=headers)
             response.raise_for_status()
 
             result = response.json()