feat: add SessionConfiguration with proxy, extensions, and profile support

Replace ad-hoc TypedDicts in browser_client.py with composable dataclasses
in config.py following the established BrowserConfiguration pattern:

- ProxyCredentials, ExternalProxy, ProxyConfiguration for proxy routing
- ExtensionS3Location, BrowserExtension for loading browser extensions
- SessionConfiguration composite that produces kwargs for start()
- Add extensions and profile_configuration params to start() and browser_session()

Usage: client.start(**session_config.to_dict())

Author: keorel

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- feat: add SessionConfiguration with proxy, extensions, and profile support for browser sessions (#274)
+
 ## [1.3.1] - 2026-02-17
 
 ### Fixed

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

@@ -4,10 +4,16 @@
 from .code_interpreter_client import CodeInterpreter, code_session
 from .config import (
     BrowserConfiguration,
+    BrowserExtension,
     BrowserSigningConfiguration,
     CodeInterpreterConfiguration,
+    ExtensionS3Location,
+    ExternalProxy,
     NetworkConfiguration,
+    ProxyConfiguration,
+    ProxyCredentials,
     RecordingConfiguration,
+    SessionConfiguration,
     ViewportConfiguration,
     VpcConfig,
     create_browser_config,
@@ -19,10 +25,16 @@
     "CodeInterpreter",
     "code_session",
     "BrowserConfiguration",
+    "BrowserExtension",
     "BrowserSigningConfiguration",
     "CodeInterpreterConfiguration",
+    "ExtensionS3Location",
+    "ExternalProxy",
     "NetworkConfiguration",
+    "ProxyConfiguration",
+    "ProxyCredentials",
     "RecordingConfiguration",
+    "SessionConfiguration",
     "ViewportConfiguration",
     "VpcConfig",
     "create_browser_config",

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 Any, Dict, Generator, List, Optional, Tuple
 from urllib.parse import urlparse
 
 import boto3
@@ -289,6 +289,9 @@ def start(
         name: Optional[str] = None,
         session_timeout_seconds: Optional[int] = DEFAULT_SESSION_TIMEOUT,
         viewport: Optional[Dict[str, int]] = None,
+        proxy_configuration: Optional[Dict[str, Any]] = None,
+        extensions: Optional[List[Dict[str, Any]]] = None,
+        profile_configuration: Optional[Dict[str, Any]] = None,
     ) -> str:
         """Start a browser sandbox session.
 
@@ -302,6 +305,15 @@ 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[Dict[str, Any]]): Proxy configuration for
+                routing browser traffic through external proxy servers. See
+                https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-proxies.html
+            extensions (Optional[List[Dict[str, Any]]]): List of browser extensions to
+                load into the session. Each extension specifies an S3 location:
+                [{"location": {"s3": {"bucket": "...", "prefix": "..."}}}]
+            profile_configuration (Optional[Dict[str, Any]]): Profile configuration for
+                persisting browser state across sessions:
+                {"profileIdentifier": "my-profile-id"}
 
         Returns:
             str: The session ID of the newly created session.
@@ -316,6 +328,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 +354,15 @@ def start(
         if viewport is not None:
             request_params["viewPort"] = viewport
 
+        if proxy_configuration is not None:
+            request_params["proxyConfiguration"] = proxy_configuration
+
+        if extensions is not None:
+            request_params["extensions"] = extensions
+
+        if profile_configuration is not None:
+            request_params["profileConfiguration"] = profile_configuration
+
         response = self.data_plane_client.start_browser_session(**request_params)
 
         self.identifier = response["browserIdentifier"]
@@ -581,14 +616,25 @@ 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[Dict[str, Any]] = None,
+    extensions: Optional[List[Dict[str, Any]]] = None,
+    profile_configuration: Optional[Dict[str, Any]] = 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[Dict[str, Any]]): Proxy configuration for
+            routing browser traffic through external proxy servers.
+        extensions (Optional[List[Dict[str, Any]]]): List of browser extensions
+            to load into the session.
+        profile_configuration (Optional[Dict[str, Any]]): Profile configuration
+            for persisting browser state across sessions.
 
     Yields:
         BrowserClient: An initialized and started browser client.
@@ -602,13 +648,26 @@ 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
+    if extensions is not None:
+        start_kwargs["extensions"] = extensions
+    if profile_configuration is not None:
+        start_kwargs["profile_configuration"] = profile_configuration
 
     client.start(**start_kwargs)
 

src/bedrock_agentcore/tools/config.py

@@ -198,6 +198,107 @@ def mobile(cls) -> "ViewportConfiguration":
         return cls(width=375, height=667)
 
 
+@dataclass
+class ProxyCredentials:
+    """Credentials for authenticating with a proxy server."""
+
+    secret_arn: str
+
+    def to_dict(self) -> Dict:
+        """Convert to API-compatible dictionary."""
+        return {"basicAuth": {"secretArn": self.secret_arn}}
+
+
+@dataclass
+class ExternalProxy:
+    """Configuration for an external proxy server."""
+
+    server: str
+    port: int
+    domain_patterns: Optional[List[str]] = None
+    credentials: Optional[ProxyCredentials] = None
+
+    def to_dict(self) -> Dict:
+        """Convert to API-compatible dictionary."""
+        proxy = {"server": self.server, "port": self.port}
+        if self.domain_patterns:
+            proxy["domainPatterns"] = self.domain_patterns
+        if self.credentials:
+            proxy["credentials"] = self.credentials.to_dict()
+        return {"externalProxy": proxy}
+
+
+@dataclass
+class ProxyConfiguration:
+    """Proxy configuration for routing browser traffic through external proxy servers."""
+
+    proxies: List[ExternalProxy]
+    bypass_patterns: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict:
+        """Convert to API-compatible dictionary."""
+        config = {"proxies": [p.to_dict() for p in self.proxies]}
+        if self.bypass_patterns:
+            config["bypass"] = {"domainPatterns": self.bypass_patterns}
+        return config
+
+
+@dataclass
+class ExtensionS3Location:
+    """S3 location for a browser extension."""
+
+    bucket: str
+    prefix: str
+    version_id: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        """Convert to API-compatible dictionary."""
+        location = {"bucket": self.bucket, "prefix": self.prefix}
+        if self.version_id:
+            location["versionId"] = self.version_id
+        return location
+
+
+@dataclass
+class BrowserExtension:
+    """A browser extension to load into a session."""
+
+    s3_location: ExtensionS3Location
+
+    def to_dict(self) -> Dict:
+        """Convert to API-compatible dictionary."""
+        return {"location": {"s3": self.s3_location.to_dict()}}
+
+
+@dataclass
+class SessionConfiguration:
+    """Complete session configuration for start().
+
+    Bundles all session-level parameters into one composable type.
+    Usage: client.start(**session_config.to_dict())
+    """
+
+    viewport: Optional[ViewportConfiguration] = None
+    proxy: Optional[ProxyConfiguration] = None
+    extensions: Optional[List[BrowserExtension]] = None
+    profile_identifier: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        """Convert to kwargs dict for start()."""
+        config = {}
+        if self.viewport:
+            config["viewport"] = self.viewport.to_dict()
+        if self.proxy:
+            config["proxy_configuration"] = self.proxy.to_dict()
+        if self.extensions:
+            config["extensions"] = [e.to_dict() for e in self.extensions]
+        if self.profile_identifier:
+            config["profile_configuration"] = {
+                "profileIdentifier": self.profile_identifier
+            }
+        return config
+
+
 @dataclass
 class BrowserConfiguration:
     """Complete browser configuration for create_browser.