feat: Add proxy_configuration support to browser_session() and BrowserClient.start()

The Browser Proxy (BYOP) feature launched GA on Feb 10, 2026, but the
SDK does not expose the proxyConfiguration parameter that the underlying
StartBrowserSession API supports. This forces customers to drop down to
raw Boto3 calls to use proxy configuration.

Changes:
- Add proxy_configuration parameter to BrowserClient.start()
- Add proxy_configuration parameter to browser_session() context manager
- Add ProxyConfiguration and related TypedDict definitions
- Export ProxyConfiguration from tools package
- Bump boto3/botocore minimum to >=1.42.54 (version that added
  proxyConfiguration to the bedrock-agentcore service model)
- Add 7 unit tests for proxy config passthrough

Author: keorel

pyproject.toml

@@ -26,8 +26,8 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "boto3>=1.40.52",
-    "botocore>=1.40.52",
+    "boto3>=1.42.54",
+    "botocore>=1.42.54",
     "pydantic>=2.0.0,<2.41.3",
     "urllib3>=1.26.0",
     "starlette>=0.46.2",

src/bedrock_agentcore/tools/__init__.py

@@ -1,6 +1,6 @@
 """Bedrock AgentCore SDK tools package."""
 
-from .browser_client import BrowserClient, browser_session
+from .browser_client import BrowserClient, ProxyConfiguration, browser_session
 from .code_interpreter_client import CodeInterpreter, code_session
 from .config import (
     BrowserConfiguration,
@@ -15,6 +15,7 @@
 
 __all__ = [
     "BrowserClient",
+    "ProxyConfiguration",
     "browser_session",
     "CodeInterpreter",
     "code_session",

src/bedrock_agentcore/tools/browser_client.py

@@ -11,7 +11,7 @@
 import secrets
 import uuid
 from contextlib import contextmanager
-from typing import Dict, Generator, Optional, Tuple
+from typing import Dict, Generator, List, Optional, Tuple, TypedDict
 from urllib.parse import urlparse
 
 import boto3
@@ -29,6 +29,49 @@
 MAX_LIVE_VIEW_PRESIGNED_URL_TIMEOUT = 300
 
 
+class BasicAuth(TypedDict, total=False):
+    """Basic authentication credentials for a proxy server."""
+
+    secretArn: str
+
+
+class ProxyCredentials(TypedDict, total=False):
+    """Credentials for authenticating with a proxy server."""
+
+    basicAuth: BasicAuth
+
+
+class ExternalProxy(TypedDict, total=False):
+    """Configuration for an external proxy server."""
+
+    server: str
+    port: int
+    domainPatterns: List[str]
+    credentials: ProxyCredentials
+
+
+class ProxyEntry(TypedDict, total=False):
+    """A single proxy entry in the proxy configuration."""
+
+    externalProxy: ExternalProxy
+
+
+class ProxyBypass(TypedDict, total=False):
+    """Domains that bypass all proxy servers."""
+
+    domainPatterns: List[str]
+
+
+class ProxyConfiguration(TypedDict, total=False):
+    """Proxy configuration for routing browser traffic through external proxy servers.
+
+    See: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-proxies.html
+    """
+
+    proxies: List[ProxyEntry]
+    bypass: ProxyBypass
+
+
 class BrowserClient:
     """Client for interacting with the AWS Browser sandbox service.
 
@@ -289,6 +332,7 @@ def start(
         name: Optional[str] = None,
         session_timeout_seconds: Optional[int] = DEFAULT_SESSION_TIMEOUT,
         viewport: Optional[Dict[str, int]] = None,
+        proxy_configuration: Optional[ProxyConfiguration] = None,
     ) -> str:
         """Start a browser sandbox session.
 
@@ -302,6 +346,9 @@ def start(
                 Range: 1-28800 (8 hours). Default: 3600 (1 hour).
             viewport (Optional[Dict[str, int]]): The viewport dimensions:
                 {'width': 1920, 'height': 1080}
+            proxy_configuration (Optional[ProxyConfiguration]): Proxy configuration for
+                routing browser traffic through external proxy servers. See
+                https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-proxies.html
 
         Returns:
             str: The session ID of the newly created session.
@@ -316,6 +363,20 @@ def start(
             ...     viewport={'width': 1920, 'height': 1080},
             ...     session_timeout_seconds=7200  # 2 hours
             ... )
+            >>>
+            >>> # Use proxy configuration
+            >>> session_id = client.start(
+            ...     proxy_configuration={
+            ...         "proxies": [{
+            ...             "externalProxy": {
+            ...                 "server": "proxy.example.com",
+            ...                 "port": 8080,
+            ...                 "domainPatterns": [".example.com"],
+            ...             }
+            ...         }],
+            ...         "bypass": {"domainPatterns": [".amazonaws.com"]}
+            ...     }
+            ... )
         """
         self.logger.info("Starting browser session...")
 
@@ -328,6 +389,9 @@ def start(
         if viewport is not None:
             request_params["viewPort"] = viewport
 
+        if proxy_configuration is not None:
+            request_params["proxyConfiguration"] = proxy_configuration
+
         response = self.data_plane_client.start_browser_session(**request_params)
 
         self.identifier = response["browserIdentifier"]
@@ -581,14 +645,19 @@ def release_control(self):
 
 @contextmanager
 def browser_session(
-    region: str, viewport: Optional[Dict[str, int]] = None, identifier: Optional[str] = None
+    region: str,
+    viewport: Optional[Dict[str, int]] = None,
+    identifier: Optional[str] = None,
+    proxy_configuration: Optional[ProxyConfiguration] = None,
 ) -> Generator[BrowserClient, None, None]:
     """Context manager for creating and managing a browser sandbox session.
 
     Args:
         region (str): AWS region.
         viewport (Optional[Dict[str, int]]): Viewport dimensions.
         identifier (Optional[str]): Browser identifier (system or custom).
+        proxy_configuration (Optional[ProxyConfiguration]): Proxy configuration for
+            routing browser traffic through external proxy servers.
 
     Yields:
         BrowserClient: An initialized and started browser client.
@@ -602,13 +671,22 @@ def browser_session(
         >>> with browser_session('us-west-2', identifier='my-signed-browser') as client:
         ...     # Automation with reduced CAPTCHA friction
         ...     pass
+        ...
+        >>> # Use proxy configuration
+        >>> with browser_session('us-west-2', proxy_configuration={
+        ...     "proxies": [{"externalProxy": {"server": "proxy.corp.com", "port": 8080}}],
+        ...     "bypass": {"domainPatterns": [".amazonaws.com"]}
+        ... }) as client:
+        ...     ws_url, headers = client.generate_ws_headers()
     """
     client = BrowserClient(region)
     start_kwargs = {}
     if viewport is not None:
         start_kwargs["viewport"] = viewport
     if identifier is not None:
         start_kwargs["identifier"] = identifier
+    if proxy_configuration is not None:
+        start_kwargs["proxy_configuration"] = proxy_configuration
 
     client.start(**start_kwargs)