fix(clients): expose WaitConfig and accept region_name aliases

docs/examples/agent_runtime_client_examples.md

@@ -4,6 +4,25 @@ This document provides practical examples for using the `AgentCoreRuntimeClient`
 
 ## Basic Usage
 
+`AgentCoreRuntimeClient` accepts either `region` or `region_name`. If both are
+provided, `region` takes precedence. You can also import `WaitConfig` alongside
+the client to configure polling:
+
+```python
+from bedrock_agentcore.runtime import AgentCoreRuntimeClient, WaitConfig
+
+client = AgentCoreRuntimeClient(region_name="us-west-2")
+wait_config = WaitConfig(max_wait=900, poll_interval=10)
+```
+
+Pass `wait_config=wait_config` to `create_agent_runtime_and_wait` or
+`update_agent_runtime_and_wait` alongside the runtime's configuration.
+
+`WaitConfig` is also available from `bedrock_agentcore.evaluation`,
+`bedrock_agentcore.gateway`, `bedrock_agentcore.knowledge_base`, and
+`bedrock_agentcore.policy`. `BatchEvaluationRunner` likewise accepts
+`region_name`, with the same precedence as the runtime client.
+
 ### Backend Service (SigV4 Headers)
 
 ```python

src/bedrock_agentcore/evaluation/__init__.py

@@ -1,5 +1,6 @@
 """AgentCore Evaluation: EvaluationClient, OnDemandEvaluationDatasetRunner, and Strands integration."""
 
+from bedrock_agentcore._utils.config import WaitConfig
 from bedrock_agentcore.evaluation.client import EvaluationClient, ReferenceInputs
 from bedrock_agentcore.evaluation.custom_code_based_evaluators import (
     EvaluatorInput,
@@ -65,6 +66,7 @@
 )
 
 __all__ = [
+    "WaitConfig",
     "ActorProfile",
     "AgentInvokerFn",
     "BatchEvaluationRunner",

src/bedrock_agentcore/evaluation/runner/batch/batch_evaluation_runner.py

@@ -63,14 +63,15 @@ class BatchEvaluationRunner:
         SimulatedScenario: SimulatedScenarioExecutor,
     }
 
-    def __init__(self, region: Optional[str] = None):
+    def __init__(self, region: Optional[str] = None, region_name: Optional[str] = None):
         """Initialize the batch evaluation runner.
 
         Args:
             region: AWS region. Defaults to boto3 session region or DEFAULT_REGION.
+            region_name: Alias for region. If both are provided, region takes precedence.
         """
         session = boto3.Session()
-        self.region = region or session.region_name or DEFAULT_REGION
+        self.region = region or region_name or session.region_name or DEFAULT_REGION
         self.data_plane_client = session.client(
             "bedrock-agentcore",
             region_name=self.region,

src/bedrock_agentcore/gateway/__init__.py

@@ -1,5 +1,7 @@
 """Bedrock AgentCore Gateway client."""
 
+from bedrock_agentcore._utils.config import WaitConfig
+
 from .client import GatewayClient
 
-__all__ = ["GatewayClient"]
+__all__ = ["WaitConfig", "GatewayClient"]

src/bedrock_agentcore/knowledge_base/__init__.py

@@ -1,5 +1,7 @@
 """Bedrock AgentCore Knowledge Base client."""
 
+from bedrock_agentcore._utils.config import WaitConfig
+
 from .client import KnowledgeBaseClient
 
-__all__ = ["KnowledgeBaseClient"]
+__all__ = ["WaitConfig", "KnowledgeBaseClient"]

src/bedrock_agentcore/policy/__init__.py

@@ -1,5 +1,7 @@
 """Bedrock AgentCore Policy Engine client."""
 
+from bedrock_agentcore._utils.config import WaitConfig
+
 from .client import PolicyEngineClient
 
-__all__ = ["PolicyEngineClient"]
+__all__ = ["WaitConfig", "PolicyEngineClient"]

src/bedrock_agentcore/runtime/__init__.py

@@ -6,6 +6,8 @@
 - BedrockAgentCoreContext: Agent identity context
 """
 
+from bedrock_agentcore._utils.config import WaitConfig
+
 from .agent_core_runtime_client import AgentCoreRuntimeClient
 from .app import BedrockAgentCoreApp
 from .context import BedrockAgentCoreContext, RequestContext
@@ -22,6 +24,7 @@
 )
 
 __all__ = [
+    "WaitConfig",
     "AgentCoreRuntimeClient",
     "AGUIApp",
     "AuthMode",

src/bedrock_agentcore/runtime/agent_core_runtime_client.py

@@ -74,6 +74,7 @@ def __init__(
         region: Optional[str] = None,
         session: Optional[boto3.Session] = None,
         integration_source: Optional[str] = None,
+        region_name: Optional[str] = None,
     ) -> None:
         """Initialize an AgentCoreRuntime client for the specified AWS region.
 
@@ -84,8 +85,11 @@ def __init__(
                 default session is created.
             integration_source: Optional integration source for user-agent
                 telemetry.
+            region_name: Alias for region. If both are provided, region takes precedence.
         """
-        self.region = validate_region(region or (session.region_name if session else None) or "us-west-2")
+        self.region = validate_region(
+            region or region_name or (session.region_name if session else None) or "us-west-2"
+        )
         self.session = session if session else boto3.Session(region_name=self.region)
         self.integration_source = integration_source
         self.logger = logging.getLogger(__name__)

tests/bedrock_agentcore/evaluation/runner/batch/test_batch_evaluation_runner.py

@@ -29,6 +29,37 @@
 # Fixtures
 # ---------------------------------------------------------------------------
 
+
+class TestRegionName:
+    @pytest.mark.parametrize(
+        "kwargs,session_region,expected",
+        [
+            ({"region_name": "eu-west-1"}, "us-east-1", "eu-west-1"),
+            ({"region": "us-west-2"}, "us-east-1", "us-west-2"),
+            ({"region": "us-west-2", "region_name": "eu-west-1"}, "us-east-1", "us-west-2"),
+            ({"region": "", "region_name": "eu-west-1"}, "us-east-1", "eu-west-1"),
+            ({}, "us-east-1", "us-east-1"),
+            ({}, None, "us-west-2"),
+        ],
+    )
+    def test_region_precedence(self, kwargs, session_region, expected):
+        with patch(
+            "bedrock_agentcore.evaluation.runner.batch.batch_evaluation_runner.boto3.Session"
+        ) as session_factory:
+            session = session_factory.return_value
+            session.region_name = session_region
+            runner = BatchEvaluationRunner(**kwargs)
+        assert runner.region == expected
+        assert len(session.client.call_args_list) == 2
+        for call in session.client.call_args_list:
+            assert call.kwargs["region_name"] == expected
+
+    def test_existing_positional_region(self):
+        with patch("bedrock_agentcore.evaluation.runner.batch.batch_evaluation_runner.boto3.Session"):
+            runner = BatchEvaluationRunner("eu-west-1")
+        assert runner.region == "eu-west-1"
+
+
 _T0 = datetime(2024, 1, 1, 0, 0, 0, tzinfo=timezone.utc)
 _T1 = datetime(2024, 1, 1, 0, 1, 0, tzinfo=timezone.utc)