feat(tools): add WebSearchClient for invoking Amazon Web Search

src/bedrock_agentcore/_utils/endpoints.py

@@ -13,6 +13,19 @@
 # Uses \A and \Z anchors to prevent newline injection bypass that $ allows.
 _VALID_REGION_PATTERN = re.compile(r"\A[a-z]{2}(-[a-z]+)+-\d+\Z")
 
+# A gateway identifier becomes a DNS label in the gateway's MCP endpoint, so it is
+# constrained to the characters a label allows. Anchored with \A and \Z for the same
+# reason as the region pattern.
+_VALID_GATEWAY_ID_PATTERN = re.compile(r"\A[a-zA-Z0-9][a-zA-Z0-9-]{0,62}\Z")
+
+
+class InvalidGatewayIdentifierError(ValueError):
+    """Raised when a gateway identifier is not a valid DNS label.
+
+    The identifier is interpolated into the endpoint hostname, so an
+    unvalidated value could redirect requests to a non-AWS host.
+    """
+
 
 class InvalidRegionError(ValueError):
     """Raised when an invalid AWS region string is provided.
@@ -79,3 +92,26 @@ def get_control_plane_endpoint(region: str = DEFAULT_REGION) -> str:
     validate_region(region)
     url = f"https://bedrock-agentcore-control.{region}.amazonaws.com"
     return _validate_endpoint_url(url)
+
+
+def get_gateway_mcp_endpoint(gateway_id: str, region: str = DEFAULT_REGION) -> str:
+    """Build the MCP endpoint URL for a gateway.
+
+    Args:
+        gateway_id: The gateway identifier (not an ARN).
+        region: The region the gateway lives in.
+
+    Returns:
+        The gateway's streamable HTTP MCP endpoint URL.
+
+    Raises:
+        InvalidGatewayIdentifierError: If the identifier is not a valid DNS label.
+        InvalidRegionError: If the region is malformed or the URL resolves off-AWS.
+    """
+    if not isinstance(gateway_id, str) or not _VALID_GATEWAY_ID_PATTERN.match(gateway_id):
+        raise InvalidGatewayIdentifierError(
+            f"Invalid gateway identifier: {gateway_id!r}. Expected a gateway ID such as 'my-gateway-abc123'."
+        )
+    validate_region(region)
+    url = f"https://{gateway_id}.gateway.bedrock-agentcore.{region}.amazonaws.com/mcp"
+    return _validate_endpoint_url(url)

src/bedrock_agentcore/tools/__init__.py

@@ -26,6 +26,13 @@
     VpcConfig,
     create_browser_config,
 )
+from .web_search_client import (
+    WebSearchBackend,
+    WebSearchClient,
+    WebSearchError,
+    WebSearchResponse,
+    WebSearchResult,
+)
 
 __all__ = [
     "BasicAuth",
@@ -53,5 +60,10 @@
     "SessionConfiguration",
     "ViewportConfiguration",
     "VpcConfig",
+    "WebSearchBackend",
+    "WebSearchClient",
+    "WebSearchError",
+    "WebSearchResponse",
+    "WebSearchResult",
     "create_browser_config",
 ]