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

package/dist/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -73,12 +73,14 @@ async function main() {
   const spec = await configIO.readProjectSpec();
   const targets = await configIO.readAWSDeploymentTargets();
 
-  // Extract MCP configuration from project spec.
-  // Gateway fields are stored in agentcore.json but may not yet be on the
-  // AgentCoreProjectSpec type from @aws/agentcore-cdk, so we read them
-  // dynamically and cast the resulting object.
+  // The vended CDK project compiles against the published @aws/agentcore-cdk
+  // schema type, which may lag the CLI's own AgentCoreProjectSpec (e.g. payments,
+  // harnesses, gateway fields). Cast once so those fields are reachable.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const specAny = spec as any;
+
+  // Extract MCP configuration from project spec.
+  // Gateway fields are stored in agentcore.json but may not yet be on the
   const mcpSpec = specAny.agentCoreGateways?.length
     ? {
         agentCoreGateways: specAny.agentCoreGateways,
@@ -113,6 +115,7 @@ async function main() {
     apiKeyArn?: string;
     efsAccessPoints?: { accessPointArn: string; mountPath: string }[];
     s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
+    apiFormat?: 'converse_stream' | 'responses' | 'chat_completions';
   }[] = [];
   for (const entry of specAny.harnesses ?? []) {
     const harnessDir = path.resolve(projectRoot, entry.path);
@@ -131,6 +134,7 @@ async function main() {
         apiKeyArn: harnessSpec.model?.apiKeyArn,
         efsAccessPoints: harnessSpec.efsAccessPoints,
         s3AccessPoints: harnessSpec.s3AccessPoints,
+        apiFormat: harnessSpec.model?.apiFormat,
       });
     } catch (err) {
       throw new Error(
@@ -154,11 +158,51 @@ async function main() {
       | Record<string, { credentialProviderArn: string; clientSecretArn?: string }>
       | undefined;
 
+    // Payment credential provider ARNs live in the same credentials map as identity credentials
+    const paymentCredentials = credentials;
+
+    const paymentSpec = specAny.payments?.length
+      ? specAny.payments.map(
+          (p: {
+            name: string;
+            description?: string;
+            authorizerType: 'AWS_IAM' | 'CUSTOM_JWT';
+            authorizerConfiguration?: unknown;
+            autoPayment?: boolean;
+            paymentToolAllowlist?: string[];
+            networkPreferences?: string[];
+            connectors: { name: string; provider?: string; credentialName: string }[];
+          }) => ({
+            name: p.name,
+            description: p.description,
+            authorizerType: p.authorizerType,
+            authorizerConfiguration: p.authorizerConfiguration,
+            autoPayment: p.autoPayment,
+            paymentToolAllowlist: p.paymentToolAllowlist,
+            networkPreferences: p.networkPreferences,
+            connectors: p.connectors.map(c => {
+              const credentialProviderArn = paymentCredentials?.[c.credentialName]?.credentialProviderArn;
+              if (!credentialProviderArn) {
+                // Fail fast with an actionable message rather than passing an empty
+                // ARN that fails opaquely server-side at CreatePaymentConnector.
+                throw new Error(
+                  \`Payment connector "\${c.name}" on manager "\${p.name}" references credential \` +
+                    \`"\${c.credentialName}", but no deployed credential provider was found for it. \` +
+                    \`Run \\\`agentcore deploy\\\` so the credential provider is created first.\`
+                );
+              }
+              return { name: c.name, provider: c.provider, credentialProviderArn };
+            }),
+          })
+        )
+      : undefined;
+
     new AgentCoreStack(app, stackName, {
       spec,
       mcpSpec,
       credentials,
       harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
+      paymentSpec,
       env,
       description: \`AgentCore stack for \${spec.name} deployed to \${target.name} (\${target.region})\`,
       tags: {
@@ -173,7 +217,7 @@ async function main() {
 
 main().catch((error: unknown) => {
   console.error('AgentCore CDK synthesis failed:', error instanceof Error ? error.message : error);
-  process.exitCode = 1;
+  process.exit(1);
 });
 "
 `;
@@ -300,10 +344,14 @@ exports[`Assets Directory Snapshots > CDK assets > cdk/cdk/lib/cdk-stack.ts shou
 "import {
   AgentCoreApplication,
   AgentCoreMcp,
+  AgentCorePaymentManager,
+  AgentCorePaymentConnector,
   type AgentCoreProjectSpec,
   type AgentCoreMcpSpec,
+  type CustomJWTAuthorizerConfig,
 } from '@aws/agentcore-cdk';
 import { CfnOutput, Stack, type StackProps } from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import { Construct } from 'constructs';
 
 export interface HarnessConfig {
@@ -320,6 +368,23 @@ export interface HarnessConfig {
   s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
 }
 
+export interface PaymentConnectorSpec {
+  name: string;
+  provider: 'CoinbaseCDP' | 'StripePrivy';
+  credentialProviderArn: string;
+}
+
+export interface PaymentSpec {
+  name: string;
+  description?: string;
+  authorizerType: 'AWS_IAM' | 'CUSTOM_JWT';
+  authorizerConfiguration?: { customJWTAuthorizer: CustomJWTAuthorizerConfig };
+  autoPayment?: boolean;
+  paymentToolAllowlist?: string[];
+  networkPreferences?: string[];
+  connectors: PaymentConnectorSpec[];
+}
+
 export interface AgentCoreStackProps extends StackProps {
   /**
    * The AgentCore project specification containing agents, memories, and credentials.
@@ -337,6 +402,30 @@ export interface AgentCoreStackProps extends StackProps {
    * Harness role configurations.
    */
   harnesses?: HarnessConfig[];
+  /**
+   * Payment specifications with resolved credential provider ARNs.
+   */
+  paymentSpec?: PaymentSpec[];
+}
+
+function toCdkId(name: string): string {
+  return name.replace(/_/g, '');
+}
+
+/**
+ * Decide whether a deployed runtime should receive payment env vars + IAM grants.
+ * Payments today only ships a runtime shim for Python HTTP runtimes; injecting
+ * AGENTCORE_PAYMENT_* env vars into TypeScript / MCP / A2A / AGUI runtimes
+ * would surface env vars they cannot consume and would dilute least-privilege
+ * IAM grants for runtimes that never call ProcessPayment.
+ */
+function isPaymentEligibleAgent(agent: { entrypoint?: string; protocol?: string }): boolean {
+  if (agent.protocol && agent.protocol !== 'HTTP') {
+    return false;
+  }
+  const entrypoint = typeof agent.entrypoint === 'string' ? agent.entrypoint : '';
+  const entrypointFile = entrypoint.split(':')[0] ?? '';
+  return entrypointFile.endsWith('.py');
 }
 
 /**
@@ -352,7 +441,7 @@ export class AgentCoreStack extends Stack {
   constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
     super(scope, id, props);
 
-    const { spec, mcpSpec, credentials, harnesses } = props;
+    const { spec, mcpSpec, credentials, harnesses, paymentSpec } = props;
 
     // Create AgentCoreApplication with all agents and harness roles
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -373,6 +462,122 @@ export class AgentCoreStack extends Stack {
       });
     }
 
+    // Create payment infrastructure via CFN constructs
+    if (paymentSpec && paymentSpec.length > 0) {
+      for (const payment of paymentSpec) {
+        const mgrId = toCdkId(payment.name);
+        const manager = new AgentCorePaymentManager(this, \`Payment\${mgrId}\`, {
+          projectName: spec.name,
+          name: payment.name,
+          authorizerType: payment.authorizerType,
+          description: payment.description,
+          authorizerConfiguration: payment.authorizerConfiguration,
+          tags: spec.tags,
+        });
+
+        const prefix = \`AGENTCORE_PAYMENT_\${payment.name.toUpperCase().replace(/-/g, '_')}\`;
+
+        // Wire env vars from construct output tokens into eligible agent environments only.
+        // See isPaymentEligibleAgent — non-Python or non-HTTP runtimes have no shim that
+        // can consume these env vars, and giving them sts:AssumeRole on the
+        // ProcessPaymentRole would broaden the privilege surface unnecessarily.
+        for (const env of this.application.environments.values()) {
+          if (!isPaymentEligibleAgent(env.agent)) {
+            continue;
+          }
+          env.runtime.addEnvironmentVariable(\`\${prefix}_MANAGER_ARN\`, manager.paymentManagerArn);
+          env.runtime.addEnvironmentVariable(\`\${prefix}_PROCESS_PAYMENT_ROLE_ARN\`, manager.processPaymentRoleArn);
+
+          // Grant runtime execution role permission to assume the ProcessPaymentRole.
+          // The ProcessPaymentRole's trust policy allows AccountRootPrincipal, but the
+          // caller still needs sts:AssumeRole on its own role to perform the assumption.
+          env.runtime.role.addToPrincipalPolicy(
+            new iam.PolicyStatement({
+              actions: ['sts:AssumeRole'],
+              resources: [manager.processPaymentRoleArn],
+            })
+          );
+
+          // Grant payment data-plane actions directly to the runtime role.
+          //
+          // NOTE: This deviates from the canonical role model in the AgentCore Payments
+          // beta guide, which assigns Get/List/Create instrument+session actions to a
+          // separate ManagementRole and limits the agent's role to ProcessPayment only.
+          // The current SDK plugin (AgentCorePaymentsPlugin.generate_payment_header)
+          // calls GetPaymentInstrument internally during the 402 auto-pay path, so the
+          // runtime role needs read access. CreatePaymentSession is included so
+          // \`agentcore invoke --auto-session\` works without a separate ManagementRole
+          // call. Tighten this if the SDK is updated to accept pre-fetched instrument
+          // details and split create-session into a backend-only flow.
+          env.runtime.role.addToPrincipalPolicy(
+            new iam.PolicyStatement({
+              actions: [
+                'bedrock-agentcore:GetPaymentInstrument',
+                'bedrock-agentcore:ListPaymentInstruments',
+                'bedrock-agentcore:GetPaymentInstrumentBalance',
+                'bedrock-agentcore:GetPaymentSession',
+                'bedrock-agentcore:ListPaymentSessions',
+                'bedrock-agentcore:CreatePaymentSession',
+                'bedrock-agentcore:ProcessPayment',
+              ],
+              resources: [manager.paymentManagerArn, \`\${manager.paymentManagerArn}/*\`],
+            })
+          );
+
+          if (payment.autoPayment !== undefined) {
+            env.runtime.addEnvironmentVariable(\`\${prefix}_AUTO_PAYMENT\`, String(payment.autoPayment));
+          }
+          if (payment.paymentToolAllowlist) {
+            env.runtime.addEnvironmentVariable(\`\${prefix}_TOOL_ALLOWLIST\`, payment.paymentToolAllowlist.join(','));
+          }
+          if (payment.networkPreferences) {
+            env.runtime.addEnvironmentVariable(\`\${prefix}_NETWORK_PREFERENCES\`, payment.networkPreferences.join(','));
+          }
+          if (payment.authorizerType === 'CUSTOM_JWT') {
+            env.runtime.addEnvironmentVariable(\`\${prefix}_AUTH_MODE\`, 'bearer');
+          }
+        }
+
+        // Create connectors for this manager
+        for (const connector of payment.connectors) {
+          const connId = toCdkId(connector.name);
+          const conn = new AgentCorePaymentConnector(this, \`Payment\${mgrId}\${connId}\`, {
+            projectName: spec.name,
+            paymentManager: manager,
+            connectorName: connector.name,
+            connectorType: connector.provider,
+            credentialProviderArn: connector.credentialProviderArn,
+          });
+
+          // Wire first connector's ID as env var (eligible agents only)
+          if (connector === payment.connectors[0]) {
+            for (const env of this.application.environments.values()) {
+              if (!isPaymentEligibleAgent(env.agent)) continue;
+              env.runtime.addEnvironmentVariable(\`\${prefix}_CONNECTOR_ID\`, conn.paymentConnectorId);
+            }
+          }
+
+          new CfnOutput(this, \`Payment\${mgrId}\${connId}ConnectorId\`, {
+            value: conn.paymentConnectorId,
+          });
+        }
+
+        // CFN Outputs for post-deploy state parsing
+        new CfnOutput(this, \`Payment\${mgrId}ManagerArn\`, {
+          value: manager.paymentManagerArn,
+        });
+        new CfnOutput(this, \`Payment\${mgrId}ManagerId\`, {
+          value: manager.paymentManagerId,
+        });
+        new CfnOutput(this, \`Payment\${mgrId}ProcessPaymentRoleArn\`, {
+          value: manager.processPaymentRoleArn,
+        });
+        new CfnOutput(this, \`Payment\${mgrId}ResourceRetrievalRoleArn\`, {
+          value: manager.resourceRetrievalRoleArn,
+        });
+      }
+    }
+
     // Stack-level output
     new CfnOutput(this, 'StackNameOutput', {
       description: 'Name of the CloudFormation Stack',
@@ -445,6 +650,8 @@ test('AgentCoreStack synthesizes with empty spec', () => {
       evaluators: [],
       onlineEvalConfigs: [],
       policyEngines: [],
+      payments: [],
+      configBundles: [],
       agentCoreGateways: [],
       mcpRuntimeTools: [],
       unassignedTargets: [],
@@ -605,6 +812,8 @@ exports[`Assets Directory Snapshots > File listing > should match the expected f
   "python/http/strands/base/pyproject.toml",
   "python/http/strands/capabilities/memory/__init__.py",
   "python/http/strands/capabilities/memory/session.py",
+  "python/http/strands/capabilities/payments/__init__.py",
+  "python/http/strands/capabilities/payments/payments.py",
   "python/mcp/standalone/base/README.md",
   "python/mcp/standalone/base/gitignore.template",
   "python/mcp/standalone/base/main.py",
@@ -1629,7 +1838,7 @@ dependencies = [
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",
-    "bedrock-agentcore[a2a] >= 1.0.3",
+    "bedrock-agentcore[a2a] >= 1.8.0",
     "botocore[crt] >= 1.35.0",
     "langgraph >= 0.2.0",
 ]
@@ -2276,7 +2485,7 @@ requires-python = ">=3.10"
 dependencies = [
     "ag-ui-adk >= 0.6.0",
     "ag-ui-protocol >= 0.1.10",
-    "bedrock-agentcore >= 1.0.3",
+    "bedrock-agentcore >= 1.8.0",
     "fastapi >= 0.115.12",
     "google-adk >= 1.16.0, < 2.0.0",
     "google-genai >= 1.0.0, < 2.0.0",
@@ -2648,7 +2857,7 @@ dependencies = [
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",
-    "bedrock-agentcore >= 1.0.3",
+    "bedrock-agentcore >= 1.8.0",
     "botocore[crt] >= 1.35.0",
     "langgraph >= 0.3.25",
     "langchain >= 0.3.0",
@@ -3467,7 +3676,7 @@ dependencies = [
     "autogen-ext[mcp] >= 0.7.5",
     "opentelemetry-distro",
     "opentelemetry-exporter-otlp",
-    "bedrock-agentcore >= 1.0.3",
+    "bedrock-agentcore >= 1.8.0",
     "botocore[crt] >= 1.35.0",
     "tiktoken",
 {{#if (eq modelProvider "Bedrock")}}
@@ -4422,7 +4631,7 @@ dependencies = [
     "mcp >= 1.19.0",
     "langchain-mcp-adapters >= 0.1.11",
     "langchain >= 1.0.3",
-    "bedrock-agentcore >= 1.0.3",
+    "bedrock-agentcore >= 1.8.0",
     "botocore[crt] >= 1.35.0",
 {{#if (eq modelProvider "Bedrock")}}
     "langchain-aws >= 1.0.0",
@@ -4858,7 +5067,7 @@ requires-python = ">=3.10"
 dependencies = [
     "aws-opentelemetry-distro",
     "openai-agents >= 0.4.2",
-    "bedrock-agentcore >= 1.0.3",
+    "bedrock-agentcore >= 1.8.0",
     "botocore[crt] >= 1.35.0",
     {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
     {{/if}}{{/if}}
@@ -4977,6 +5186,9 @@ from memory.session import get_memory_session_manager
 {{#if needsOs}}
 import os
 {{/if}}
+{{#if hasPayment}}
+from capabilities.payments.payments import create_payments_plugin, PAYMENT_SYSTEM_PROMPT
+{{/if}}
 
 app = BedrockAgentCoreApp()
 log = app.logger
@@ -5112,12 +5324,12 @@ class ConfigBundleHook(HookProvider):
 {{/if}}
 
 {{#if hasMemory}}
+{{#unless hasPayment}}
 def agent_factory():
     cache = {}
     def get_or_create_agent(session_id, user_id):
         key = f"{session_id}/{user_id}"
         if key not in cache:
-            # Create an agent for the given session_id and user_id
             cache[key] = Agent(
                 model=load_model(),
                 session_manager=get_memory_session_manager(session_id, user_id),
@@ -5128,6 +5340,7 @@ def agent_factory():
         return cache[key]
     return get_or_create_agent
 get_or_create_agent = agent_factory()
+{{/unless}}
 {{else}}
 {{#if hasConfigBundle}}
 def create_agent():
@@ -5138,6 +5351,7 @@ def create_agent():
         hooks=[ConfigBundleHook()],
     )
 {{else}}
+{{#unless hasPayment}}
 _agent = None
 
 def get_or_create_agent():
@@ -5146,9 +5360,10 @@ def get_or_create_agent():
         _agent = Agent(
             model=load_model(),
             system_prompt=DEFAULT_SYSTEM_PROMPT,
-            tools=tools
+            tools=tools,
         )
     return _agent
+{{/unless}}
 {{/if}}
 {{/if}}
 
@@ -5157,16 +5372,47 @@ def get_or_create_agent():
 async def invoke(payload, context):
     log.info("Invoking Agent.....")
 
+{{#if hasPayment}}
+    user_id = payload.get("user_id") or getattr(context, "user_id", "default-user")
+    instrument_id = payload.get("payment_instrument_id")
+    session_id = payload.get("payment_session_id")
+    payments_plugin = create_payments_plugin(user_id, instrument_id, session_id)
+    plugins = [payments_plugin] if payments_plugin else []
+{{/if}}
+
 {{#if hasMemory}}
+{{#if hasPayment}}
+    mem_session_id = getattr(context, 'session_id', 'default-session')
+    mem_user_id = getattr(context, 'user_id', 'default-user')
+    agent = Agent(
+        model=load_model(),
+        session_manager=get_memory_session_manager(mem_session_id, mem_user_id),
+        system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
+        tools=tools,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
+    )
+{{else}}
     session_id = getattr(context, 'session_id', 'default-session')
     user_id = getattr(context, 'user_id', 'default-user')
     agent = get_or_create_agent(session_id, user_id)
+{{/if}}
+{{else}}
+{{#if hasPayment}}
+    agent = Agent(
+        model=load_model(),
+        system_prompt=DEFAULT_SYSTEM_PROMPT + PAYMENT_SYSTEM_PROMPT,
+        tools=tools,
+        plugins=plugins,{{#if hasConfigBundle}}
+        hooks=[ConfigBundleHook()],{{/if}}
+    )
 {{else}}
 {{#if hasConfigBundle}}
     agent = create_agent()
 {{else}}
     agent = get_or_create_agent()
 {{/if}}
+{{/if}}
 {{/if}}
 
     # Execute and format response
@@ -5479,6 +5725,160 @@ def get_memory_session_manager(session_id: Optional[str], actor_id: str) -> Opti
 "
 `;
 
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/strands/capabilities/payments/__init__.py should match snapshot 1`] = `
+""""Payment capabilities for Strands agents."""
+from .payments import create_payments_plugin
+
+__all__ = ["create_payments_plugin"]
+"
+`;
+
+exports[`Assets Directory Snapshots > Python framework assets > python/python/http/strands/capabilities/payments/payments.py should match snapshot 1`] = `
+""""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)
+"
+`;
+
 exports[`Assets Directory Snapshots > Python framework assets > python/python/mcp/standalone/base/README.md should match snapshot 1`] = `
 "# {{ name }}