fix: recursively extract HTTP errors from nested ExceptionGroups (#3556)

Author: mshsheikh

src/agents/mcp/server.py

@@ -721,13 +721,12 @@ def _extract_http_error_from_exception(self, e: BaseException) -> Exception | No
         if isinstance(e, httpx.HTTPStatusError | httpx.ConnectError | httpx.TimeoutException):
             return e
 
-        # Check if it's an ExceptionGroup containing HTTP errors
+        # Recursively check ExceptionGroups for HTTP errors
         if isinstance(e, BaseExceptionGroup):
             for exc in e.exceptions:
-                if isinstance(
-                    exc, httpx.HTTPStatusError | httpx.ConnectError | httpx.TimeoutException
-                ):
-                    return exc
+                result = self._extract_http_error_from_exception(exc)
+                if result is not None:
+                    return result
 
         return None
 

tests/mcp/test_server_errors.py

@@ -1,10 +1,21 @@
+import builtins
+import sys
+from unittest.mock import MagicMock, patch
+
+import httpx
 import pytest
 
 from agents import Agent
 from agents.exceptions import UserError
-from agents.mcp.server import _MCPServerWithClientSession
+from agents.mcp.server import MCPServerStreamableHttp, _MCPServerWithClientSession
 from agents.run_context import RunContextWrapper
 
+# Handle Python version compatibility for ExceptionGroups
+if sys.version_info < (3, 11):
+    from exceptiongroup import BaseExceptionGroup
+else:
+    BaseExceptionGroup = builtins.BaseExceptionGroup
+
 
 class CrashingClientSessionServer(_MCPServerWithClientSession):
     def __init__(self):
@@ -45,3 +56,30 @@ async def test_not_calling_connect_causes_error():
 
     with pytest.raises(UserError):
         await server.call_tool("foo", {})
+
+
+@pytest.mark.asyncio
+async def test_call_tool_nested_exception_group_mapping():
+    """
+    Regression test ensuring that nested ExceptionGroups containing HTTP errors
+    are recursively extracted and mapped to a UserError in call_tool().
+    """
+    # 1. Initialize the server with mock streamable parameters
+    server = MCPServerStreamableHttp(params={"url": "http://fake-mcp-server"})
+
+    # 2. Simulate an active connection by mocking the session object
+    server.session = MagicMock()
+
+    # 3. Construct a nested ExceptionGroup hierarchy containing a connection error
+    http_error = httpx.ConnectError("Network unreachable")
+    inner_group = BaseExceptionGroup("inner_failures", [http_error])
+    outer_group = BaseExceptionGroup("outer_failures", [inner_group])
+
+    # 4 & 5. Mock the internal retry handler to raise the nested group, and assert UserError
+    with patch.object(server, "_call_tool_with_isolated_retry", side_effect=outer_group):
+        with pytest.raises(UserError) as exc_info:
+            await server.call_tool(tool_name="test_tool", arguments={})
+
+    # 6. Verify that the user-facing message is mapped correctly based on the root cause
+    assert "Connection lost" in str(exc_info.value)
+    assert exc_info.value.__cause__ is http_error