@aws/agentcore 1.0.0-preview.12 → 1.0.0-preview.14

package/dist/assets/python/http/strands/base/mcp_client/client.py

@@ -29,18 +29,22 @@ def _get_bearer_token_{{snakeCase name}}(*, access_token: str):
 {{#each gatewayProviders}}
 def get_{{snakeCase name}}_mcp_client() -> MCPClient | None:
     """Returns an MCP Client connected to the {{name}} gateway."""
+    {{#if hardcodedUrl}}
+    url = {{safeJson hardcodedUrl}}
+    {{else}}
     url = os.environ.get("{{envVarName}}")
     if not url:
         logger.warning("{{envVarName}} not set — {{name}} gateway tools unavailable")
         return None
+    {{/if}}
     {{#if (eq authType "AWS_IAM")}}
-    return MCPClient(lambda: aws_iam_streamablehttp_client(url, aws_service="bedrock-agentcore", aws_region=os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION"))))
+    return MCPClient(lambda: aws_iam_streamablehttp_client(url, aws_service="bedrock-agentcore", aws_region=os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION"))), prefix="{{snakeCase name}}")
     {{else if (eq authType "CUSTOM_JWT")}}
     token = _get_bearer_token_{{snakeCase name}}()
     headers = {"Authorization": f"Bearer {token}"} if token else {}
-    return MCPClient(lambda: streamablehttp_client(url, headers=headers))
+    return MCPClient(lambda: streamablehttp_client(url, headers=headers), prefix="{{snakeCase name}}")
     {{else}}
-    return MCPClient(lambda: streamablehttp_client(url))
+    return MCPClient(lambda: streamablehttp_client(url), prefix="{{snakeCase name}}")
     {{/if}}
 
 {{/each}}
@@ -53,7 +57,41 @@ def get_all_gateway_mcp_clients() -> list[MCPClient]:
         clients.append(client)
     {{/each}}
     return clients
-{{else}}
+{{/if}}
+{{#if remoteMcpTools}}
+{{#if (some remoteMcpTools "headerCredentials")}}
+from bedrock_agentcore.identity.auth import requires_api_key
+{{/if}}
+{{#each remoteMcpTools}}
+{{#if headerCredentials}}
+{{#each headerCredentials}}
+@requires_api_key(provider_name="{{credentialName}}")
+def _get_{{snakeCase ../name}}_{{snakeCase headerKey}}_key(api_key: str) -> str:
+    """Fetch {{headerKey}} credential for {{../name}} from AgentCore Identity."""
+    return api_key
+
+{{/each}}
+{{/if}}
+def get_{{snakeCase name}}_mcp_client() -> MCPClient | None:
+    """Returns an MCP Client for the {{name}} remote MCP server."""
+    url = {{safeJson url}}
+    {{#if headerCredentials}}
+    if os.getenv("LOCAL_DEV") == "1":
+        headers = { {{#each headerCredentials}}{{safeJson headerKey}}: os.environ.get("{{envVarName}}", ""){{#unless @last}}, {{/unless}}{{/each}} }
+    else:
+        headers = { {{#each headerCredentials}}{{safeJson headerKey}}: _get_{{snakeCase ../name}}_{{snakeCase headerKey}}_key(){{#unless @last}}, {{/unless}}{{/each}} }
+    return MCPClient(lambda: streamablehttp_client(url, headers=headers))
+    {{else}}
+    return MCPClient(lambda: streamablehttp_client(url))
+    {{/if}}
+
+{{/each}}
+def get_all_remote_mcp_clients() -> list[MCPClient]:
+    """Returns all configured remote MCP clients."""
+    clients = [{{#each remoteMcpTools}}get_{{snakeCase name}}_mcp_client(){{#unless @last}}, {{/unless}}{{/each}}]
+    return [c for c in clients if c is not None]
+{{/if}}
+{{#unless (or hasGateway remoteMcpTools)}}
 {{#if isVpc}}
 # VPC mode: external MCP endpoints are not reachable without a NAT gateway.
 # Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
@@ -62,6 +100,7 @@ def get_streamable_http_mcp_client() -> MCPClient | None:
     """No MCP server configured. Add a gateway with `agentcore add gateway`."""
     return None
 {{else}}
+{{#unless isExportHarness}}
 # ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
 EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
 
@@ -69,5 +108,6 @@ def get_streamable_http_mcp_client() -> MCPClient:
     """Returns an MCP Client compatible with Strands"""
     # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
     return MCPClient(lambda: streamablehttp_client(EXAMPLE_MCP_ENDPOINT))
+{{/unless}}
 {{/if}}
-{{/if}}
+{{/unless}}

package/dist/assets/python/http/strands/base/model/load.py

@@ -4,7 +4,7 @@ from strands.models.bedrock import BedrockModel
 
 def load_model() -> BedrockModel:
     """Get Bedrock model client using IAM credentials."""
-    return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")
+    return BedrockModel(model_id="{{#if modelId}}{{modelId}}{{else}}global.anthropic.claude-sonnet-4-5-20250929-v1:0{{/if}}")
 {{/if}}
 {{#if (eq modelProvider "Anthropic")}}
 import os
@@ -80,7 +80,7 @@ def load_model() -> OpenAIModel:
     """Get authenticated OpenAI model client."""
     return OpenAIModel(
         client_args={"api_key": _get_api_key()},
-        model_id="gpt-4.1",
+        model_id="{{#if modelId}}{{modelId}}{{else}}gpt-4.1{{/if}}",
     )
 {{/if}}
 {{#if (eq modelProvider "Gemini")}}
@@ -118,6 +118,6 @@ def load_model() -> GeminiModel:
     """Get authenticated Gemini model client."""
     return GeminiModel(
         client_args={"api_key": _get_api_key()},
-        model_id="gemini-2.5-flash",
+        model_id="{{#if modelId}}{{modelId}}{{else}}gemini-2.5-flash{{/if}}",
     )
 {{/if}}

package/dist/assets/python/http/strands/base/pyproject.toml

@@ -16,8 +16,11 @@ dependencies = [
     {{#if (eq modelProvider "Gemini")}}"google-genai >= 1.0.0",
     {{/if}}"mcp >= 1.19.0",
     {{#if (eq modelProvider "OpenAI")}}"openai >= 1.0.0",
-    {{/if}}"strands-agents >= 1.13.0",
-    {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
+    {{/if}}"strands-agents >= 1.15.0",
+    {{#if (or hasBrowser hasCodeInterpreter)}}"strands-agents-tools >= 0.1.0",
+    {{/if}}{{#if hasBrowser}}"nest-asyncio >= 1.5.0",
+    "playwright >= 1.42.0",
+    {{/if}}{{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
     {{/if}}{{/if}}
 ]
 

package/dist/assets/python/http/strands/base/skills/fetcher.py

@@ -0,0 +1,279 @@
+"""Skill fetcher — downloads s3/git skills to local filesystem on first use.
+
+Resolved paths are passed to AgentSkills(skills=...) in main.py.
+Cache directory: <tmpdir>/.agents/skills/ — an absolute path under the system temp
+directory (honors $TMPDIR, defaults to /tmp). The runtime working directory (e.g.
+/var/task in a CodeZip runtime) is read-only, so the cache must live somewhere
+guaranteed-writable.
+"""
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_SKILLS_BASE = Path(tempfile.gettempdir()) / ".agents" / "skills"
+_GIT_TIMEOUT = 60
+_S3_MAX_SIZE_BYTES = 1 * 1024 * 1024 * 1024  # 1 GB
+
+
+def _stable_hash(value: str) -> str:
+    return hashlib.sha256(value.encode()).hexdigest()[:12]
+
+
+def _cleanup(path: Path) -> None:
+    """Remove a partially-created skill directory so retries don't see stale state."""
+    shutil.rmtree(path, ignore_errors=True)
+
+
+def _read_map(type_dir: Path) -> dict:
+    map_file = type_dir / ".map.json"
+    return json.loads(map_file.read_text()) if map_file.exists() else {}
+
+
+def _write_map(type_dir: Path, mapping: dict) -> None:
+    type_dir.mkdir(parents=True, exist_ok=True)
+    (type_dir / ".map.json").write_text(json.dumps(mapping))
+
+
+def _resolve_cached(type_dir: Path, source_hash: str) -> Optional[str]:
+    """Return the cached skill directory for a source hash, or None if not on disk."""
+    mapping = _read_map(type_dir)
+    dir_name = mapping.get(source_hash)
+    if dir_name and (type_dir / dir_name).exists():
+        return str(type_dir / dir_name)
+    return None
+
+
+def _read_skill_name(skill_dir: Path) -> str:
+    """Extract the skill name from SKILL.md YAML frontmatter."""
+    content = (skill_dir / "SKILL.md").read_text()
+    if not content.startswith("---"):
+        raise ValueError(f"SKILL.md in {skill_dir} has no YAML frontmatter (must start with ---)")
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ValueError(f"SKILL.md in {skill_dir} has malformed frontmatter (missing closing ---)")
+    for line in parts[1].strip().splitlines():
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip("\"'")
+            if name:
+                return name
+    raise ValueError(f"SKILL.md in {skill_dir} is missing a 'name' field in frontmatter")
+
+
+def _pick_dir_name(type_dir: Path, name: str, source_hash: str) -> str:
+    """Pick a unique directory name, appending a hash suffix on collision."""
+    if not (type_dir / name).exists():
+        return name
+    return f"{name}-{source_hash[:8]}"
+
+
+def _rename_and_cache_skill(type_dir: Path, temp_dir: Path, source_hash: str, skill_root: Path,
+                            source_label: str = "") -> Path:
+    """Validate SKILL.md, rename the temp dir to the skill's declared name, and update the map.
+
+    Raises ValueError if SKILL.md is missing or has invalid frontmatter.
+    """
+    if not (skill_root / "SKILL.md").exists():
+        _cleanup(temp_dir)
+        hint = f" (source: {source_label})" if source_label else ""
+        raise ValueError(f"No SKILL.md found in fetched skill{hint}")
+
+    name = _read_skill_name(skill_root)
+    dir_name = _pick_dir_name(type_dir, name, source_hash)
+    final_dir = type_dir / dir_name
+    if final_dir != temp_dir:
+        temp_dir.rename(final_dir)
+
+    mapping = _read_map(type_dir)
+    mapping[source_hash] = dir_name
+    _write_map(type_dir, mapping)
+    return final_dir
+
+
+def _fetch_s3_skill(source: str, s3_client=None) -> Path:
+    """Download an s3:// skill prefix and return the local directory."""
+    uri = source if source.endswith("/") else source + "/"
+    source_hash = _stable_hash(uri)
+    type_dir = _SKILLS_BASE / "s3"
+
+    cached = _resolve_cached(type_dir, source_hash)
+    if cached:
+        return Path(cached)
+
+    import boto3
+    client = s3_client or boto3.client("s3")
+    bucket, _, prefix = uri[len("s3://"):].partition("/")
+    if not bucket:
+        raise ValueError(f"Invalid S3 URI (no bucket): {uri}")
+
+    temp_dir = type_dir / source_hash
+    _cleanup(temp_dir)
+    temp_dir.mkdir(parents=True, exist_ok=True)
+    temp_root = temp_dir.resolve()
+
+    paginator = client.get_paginator("list_objects_v2")
+    total = 0
+    for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
+        for obj in page.get("Contents", []):
+            total += obj["Size"]
+            if total > _S3_MAX_SIZE_BYTES:
+                _cleanup(temp_dir)
+                raise ValueError(f"S3 skill {uri} exceeds 1 GB size limit")
+            rel = obj["Key"][len(prefix):].lstrip("/")
+            if not rel:
+                continue
+            dest = (temp_dir / rel).resolve()
+            if dest != temp_root and not str(dest).startswith(str(temp_root) + os.sep):
+                _cleanup(temp_dir)
+                raise ValueError(f"Path traversal detected in S3 key: {obj['Key']}")
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            client.download_file(bucket, obj["Key"], str(dest))
+
+    if total == 0:
+        _cleanup(temp_dir)
+        raise ValueError(f"No files found at S3 URI: {uri}")
+
+    return _rename_and_cache_skill(type_dir, temp_dir, source_hash, temp_dir, source_label=uri)
+
+
+def _resolve_credential_arn(credential_arn: str, identity_client) -> str:
+    """Resolve a Token Vault API-key credential ARN to its secret value via AgentCore Identity.
+
+    ARN format: arn:<p>:bedrock-agentcore:<region>:<account>:token-vault/<vault>/apikeycredentialprovider/<name>
+    """
+    from bedrock_agentcore.runtime.context import BedrockAgentCoreContext  # noqa: PLC0415
+
+    provider_name = credential_arn.rsplit("/", 1)[-1]
+    if not provider_name:
+        raise ValueError(f"Invalid credential ARN: {credential_arn}")
+    workload_token = BedrockAgentCoreContext.get_workload_access_token()
+    if not workload_token:
+        raise ValueError("Credential ARN resolution requires a workload access token")
+    api_key = identity_client.dp_client.get_resource_api_key(
+        resourceCredentialProviderName=provider_name,
+        workloadIdentityToken=workload_token,
+    )["apiKey"]
+    if not api_key:
+        raise ValueError(f"Identity returned empty API key for provider: {provider_name}")
+    return api_key
+
+
+def _build_git_auth_env(credential_arn: Optional[str], username: Optional[str], identity_client=None) -> dict:
+    """Build GIT_CONFIG_* env vars for HTTP Basic auth using a Token Vault credential ARN.
+
+    Uses env vars instead of -c args to avoid leaking credentials in /proc/*/cmdline,
+    and so auth propagates to sub-commands (e.g. sparse-checkout triggering a fetch).
+    """
+    if not credential_arn or not identity_client:
+        return {}
+    password = _resolve_credential_arn(credential_arn, identity_client)
+    user = username or "oauth2"
+    encoded = base64.b64encode(f"{user}:{password}".encode()).decode()
+    return {
+        "GIT_CONFIG_COUNT": "1",
+        "GIT_CONFIG_KEY_0": "http.extraHeader",
+        "GIT_CONFIG_VALUE_0": f"Authorization: Basic {encoded}",
+    }
+
+
+def _fetch_git_skill(url: str, skill_path: str = "", credential_arn: Optional[str] = None,
+                     username: Optional[str] = None, identity_client=None) -> Path:
+    """Shallow-clone a git skill repository and return the local skill directory.
+
+    Returns the directory containing SKILL.md (the subdir itself for sparse checkouts).
+    """
+    if skill_path and (os.path.isabs(skill_path) or ".." in Path(skill_path).parts):
+        raise ValueError(f"Path traversal detected in skill path: {skill_path}")
+
+    source_hash = _stable_hash(f"{url}:{skill_path}")
+    type_dir = _SKILLS_BASE / "git"
+
+    cached = _resolve_cached(type_dir, source_hash)
+    if cached:
+        return Path(cached) / skill_path if skill_path else Path(cached)
+
+    temp_dir = type_dir / source_hash
+    _cleanup(temp_dir)
+    temp_dir.mkdir(parents=True, exist_ok=True)
+
+    extra_env = _build_git_auth_env(credential_arn, username, identity_client)
+    git_env = {**os.environ, **extra_env} if extra_env else None
+
+    try:
+        if skill_path:
+            subprocess.run(
+                ["git", "clone", "--depth", "1", "--filter=blob:none", "--sparse", url, str(temp_dir)],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, env=git_env,
+            )
+            subprocess.run(
+                ["git", "sparse-checkout", "set", skill_path],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, cwd=str(temp_dir), env=git_env,
+            )
+        else:
+            subprocess.run(
+                ["git", "clone", "--depth", "1", url, str(temp_dir)],
+                check=True, timeout=_GIT_TIMEOUT, capture_output=True, env=git_env,
+            )
+    except Exception:
+        _cleanup(temp_dir)
+        raise
+
+    if skill_path and not (temp_dir / skill_path).exists():
+        _cleanup(temp_dir)
+        raise ValueError(f"Skill path '{skill_path}' not found in repository '{url}'")
+
+    # SKILL.md lives inside the subdir for sparse checkouts.
+    skill_root = temp_dir / skill_path if skill_path else temp_dir
+    label = f"{url}:{skill_path}" if skill_path else url
+    final_dir = _rename_and_cache_skill(type_dir, temp_dir, source_hash, skill_root, source_label=label)
+    return final_dir / skill_path if skill_path else final_dir
+
+
+def resolve_s3_skills(sources: list, s3_client=None) -> list:
+    """Resolve s3:// skill URIs to local filesystem paths.
+
+    Any fetch failure raises and fails the invocation — a partial skill set
+    would silently run the agent without capabilities the harness declared.
+    """
+    paths = []
+    for uri in sources:
+        try:
+            skill_dir = _fetch_s3_skill(uri, s3_client)
+        except Exception as e:
+            raise ValueError(f"Failed to resolve S3 skill '{uri}': {e}") from e
+        paths.append(str(skill_dir.resolve()))
+    return paths
+
+
+def resolve_git_skills(sources: list, identity_client=None) -> list:
+    """Resolve git skill dicts to local filesystem paths.
+
+    Each source is a dict with keys: url (required), path (optional),
+    credentialArn (optional), username (optional).
+
+    Any fetch failure raises and fails the invocation — a partial skill set
+    would silently run the agent without capabilities the harness declared.
+    """
+    paths = []
+    for source in sources:
+        try:
+            skill_dir = _fetch_git_skill(
+                url=source["url"],
+                skill_path=source.get("path") or "",
+                credential_arn=source.get("credentialArn"),
+                username=source.get("username"),
+                identity_client=identity_client,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to resolve git skill '{source.get('url', source)}': {e}") from e
+        paths.append(str(skill_dir.resolve()))
+    return paths

package/dist/assets/python/http/strands/capabilities/execution-limits/hooks/execution_limits.py

@@ -0,0 +1,54 @@
+import time
+from typing import Optional
+
+from strands.hooks import BeforeModelCallEvent
+from strands.hooks.registry import HookProvider, HookRegistry
+from strands.types.exceptions import EventLoopException
+
+
+class ExecutionLimitExceeded(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class ExecutionLimitsHook(HookProvider):
+    def __init__(
+        self,
+        max_iterations: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+        timeout_seconds: Optional[float] = None,
+    ) -> None:
+        self._max_iterations = max_iterations
+        self._max_tokens = max_tokens
+        self._timeout_seconds = timeout_seconds
+        self._iteration_count = 0
+        self._start_time = time.monotonic()
+
+    def register_hooks(self, registry: HookRegistry, **kwargs) -> None:
+        registry.add_callback(BeforeModelCallEvent, self._check_limits)
+
+    def _check_limits(self, event: BeforeModelCallEvent) -> None:
+        self._iteration_count += 1
+
+        if self._max_iterations is not None and self._iteration_count > self._max_iterations:
+            raise EventLoopException(
+                ExecutionLimitExceeded(f"Max iterations exceeded: {self._max_iterations}")
+            )
+
+        if self._timeout_seconds is not None:
+            elapsed = time.monotonic() - self._start_time
+            if elapsed > self._timeout_seconds:
+                raise EventLoopException(
+                    ExecutionLimitExceeded(
+                        f"Timeout exceeded: {self._timeout_seconds}s (elapsed {elapsed:.1f}s)"
+                    )
+                )
+
+        if self._max_tokens is not None:
+            used = event.agent.event_loop_metrics.accumulated_usage.get("outputTokens", 0)
+            if used >= self._max_tokens:
+                raise EventLoopException(
+                    ExecutionLimitExceeded(
+                        f"Max output tokens exceeded: {used}/{self._max_tokens}"
+                    )
+                )

package/dist/assets/python/http/strands/capabilities/memory/session.py

@@ -24,8 +24,11 @@ def get_memory_session_manager(session_id: Optional[str], actor_id: str) -> Opti
 {{#if (includes memoryProviders.[0].strategies "USER_PREFERENCE")}}
         f"/users/{actor_id}/preferences": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
+{{#if (includes memoryProviders.[0].strategies "EPISODIC")}}
+        f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
+{{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
-        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

package/dist/assets/python/http/strands/capabilities/payments/__init__.py

@@ -0,0 +1,4 @@
+"""Payment capabilities for Strands agents."""
+from .payments import create_payments_plugin
+
+__all__ = ["create_payments_plugin"]

package/dist/assets/python/http/strands/capabilities/payments/payments.py

@@ -0,0 +1,142 @@
+"""Payment capability -- auto-generated by agentcore CLI.
+
+Configures AgentCorePaymentsPlugin for Strands agents.
+Manager config is auto-discovered from AGENTCORE_PAYMENT_*
+environment variables set at deploy time.
+
+Uses a per-invocation factory pattern so each request gets its own
+plugin instance with the correct user_id, instrument_id, and session_id.
+This prevents concurrency bugs where one user's payment context
+could leak to another user's request.
+
+Uses the official SDK plugin which handles:
+- x402 v1 (body-based) and v2 (header-based) payment detection
+- Automatic 402 response interception and payment processing
+- Retry limiting (max 3 payment retries per tool use)
+- Error management and logging
+"""
+import os
+import logging
+
+import boto3
+from bedrock_agentcore.payments.integrations.strands import AgentCorePaymentsPlugin
+from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
+
+logger = logging.getLogger(__name__)
+
+PAYMENT_SYSTEM_PROMPT = """
+You have payment capabilities via the x402 protocol:
+- Use http_request to call HTTP endpoints. 402 Payment Required responses are settled automatically by the plugin and the call is retried.
+- Use get_payment_session to check your remaining budget before expensive operations
+- Use get_payment_instrument_balance to check wallet USDC balance
+- Use list_payment_instruments to see available payment instruments
+- If budget is low, inform the user before proceeding with paid requests
+"""
+
+_manager_arn = None
+_connector_id = None
+_process_payment_role_arn = None
+_name_segment = None
+_region = None
+_auth_mode = None
+_manager_count = 0
+for key, value in os.environ.items():
+    if key.startswith("AGENTCORE_PAYMENT_") and key.endswith("_MANAGER_ARN"):
+        if _manager_arn is None:
+            _manager_arn = value
+            _name_segment = key[len("AGENTCORE_PAYMENT_"):-len("_MANAGER_ARN")]
+        _manager_count += 1
+if _manager_count > 1:
+    logger.warning(
+        "Multiple payment managers detected in environment. Using the first one found. "
+        "Remove extra AGENTCORE_PAYMENT_*_MANAGER_ARN env vars to eliminate ambiguity."
+    )
+_region = os.getenv("AWS_REGION")
+
+_prefix = f"AGENTCORE_PAYMENT_{_name_segment}_" if _name_segment else "AGENTCORE_PAYMENT_"
+_auth_mode = os.getenv(f"{_prefix}AUTH_MODE", "sigv4")
+_connector_id = os.getenv(f"{_prefix}CONNECTOR_ID")
+_process_payment_role_arn = os.getenv(f"{_prefix}PROCESS_PAYMENT_ROLE_ARN")
+_auto_payment = os.getenv(f"{_prefix}AUTO_PAYMENT", "true").lower() == "true"
+_allowlist_raw = os.getenv(f"{_prefix}TOOL_ALLOWLIST")
+_allowlist = _allowlist_raw.split(",") if _allowlist_raw else None
+_network_prefs_raw = os.getenv(f"{_prefix}NETWORK_PREFERENCES")
+_network_prefs = _network_prefs_raw.split(",") if _network_prefs_raw else None
+
+if not _manager_arn:
+    logger.warning("No payment manager config found in environment")
+if not _connector_id:
+    logger.warning("No payment connector config found in environment")
+
+
+def _assume_role_session(role_arn):
+    """Assume an IAM role and return a boto3 session with temporary credentials."""
+    sts = boto3.client("sts", region_name=_region)
+    creds = sts.assume_role(
+        RoleArn=role_arn,
+        RoleSessionName="agentcore-payment-plugin",
+    )["Credentials"]
+    return boto3.Session(
+        aws_access_key_id=creds["AccessKeyId"],
+        aws_secret_access_key=creds["SecretAccessKey"],
+        aws_session_token=creds["SessionToken"],
+        region_name=_region,
+    )
+
+
+def create_payments_plugin(user_id, instrument_id=None, session_id=None):
+    """Create a fresh plugin instance per invocation.
+
+    Args:
+        user_id: From invocation context (required for SigV4, derived from JWT for bearer)
+        instrument_id: From invocation payload (created by app backend per user)
+        session_id: From invocation payload (created by app backend per conversation)
+
+    Returns:
+        AgentCorePaymentsPlugin instance, or None if no manager is configured.
+    """
+    if not _manager_arn:
+        return None
+
+    config_kwargs = {
+        "payment_manager_arn": _manager_arn,
+        "region": _region,
+        "payment_instrument_id": instrument_id,
+        "payment_session_id": session_id,
+        "payment_connector_id": _connector_id,
+    }
+
+    config_kwargs["auto_payment"] = _auto_payment
+    if _allowlist:
+        config_kwargs["payment_tool_allowlist"] = _allowlist
+    if _network_prefs:
+        config_kwargs["network_preferences_config"] = _network_prefs
+
+    if _process_payment_role_arn:
+        # Only pass boto3_session if SDK supports it (added in bedrock-agentcore >= 1.11).
+        # Older SDKs use the runtime role's default credentials and can still call ProcessPayment
+        # if the runtime role has been granted permission directly.
+        import inspect
+        if "boto3_session" in inspect.signature(AgentCorePaymentsPluginConfig).parameters:
+            config_kwargs["boto3_session"] = _assume_role_session(_process_payment_role_arn)
+        else:
+            logger.warning(
+                "PROCESS_PAYMENT_ROLE_ARN set but bedrock-agentcore SDK does not support boto3_session. "
+                "Upgrade to bedrock-agentcore>=1.11 to enable cross-role payment processing."
+            )
+
+    if _auth_mode == "bearer":
+        bearer_token = os.getenv("AGENTCORE_BEARER_TOKEN")
+        if bearer_token:
+            config_kwargs["bearer_token"] = bearer_token
+        else:
+            logger.warning(
+                "Bearer auth mode configured but AGENTCORE_BEARER_TOKEN not set. "
+                "Falling back to SigV4. Set AGENTCORE_BEARER_TOKEN or pass bearer_token in invoke context."
+            )
+            config_kwargs["user_id"] = user_id or "default-user"
+    else:
+        config_kwargs["user_id"] = user_id or "default-user"
+
+    config = AgentCorePaymentsPluginConfig(**config_kwargs)
+    return AgentCorePaymentsPlugin(config=config)