AWS bedrock-agentcore documentation change
Summary
Completely restructured the payments getting started guide into a detailed step-by-step tutorial with provider-specific examples, added troubleshooting section, cleanup instructions, and clarified prerequisites.
Security assessment
The changes document security best practices including dedicated credential storage in AgentCore Identity (avoiding hardcoded secrets), IAM role configuration, and provider-specific security recommendations (dedicated Privy apps). However, there's no evidence this change addresses a specific security vulnerability or incident.
Diff
diff --git a/bedrock-agentcore/latest/devguide/payments-getting-started.md b/bedrock-agentcore/latest/devguide/payments-getting-started.md index 7c3971ec4..ad7c17f1f 100644 --- a//bedrock-agentcore/latest/devguide/payments-getting-started.md +++ b//bedrock-agentcore/latest/devguide/payments-getting-started.md @@ -7 +7 @@ -PrerequisitesSetting up payments for your first transactionQuick example with Strands SDKNext steps +PrerequisitesStep 1: Obtain payment provider credentialsStep 2: Store credentials in AgentCore IdentityStep 3: Create a Payment Manager and ConnectorStep 4: Create a payment instrumentStep 5: Create a payment sessionStep 6: Process a payment with a Strands agentVerify the paymentTroubleshootingCleanupWhat you’ve builtNext steps @@ -11 +11 @@ PrerequisitesSetting up payments for your first transactionQuick example with St -This guide walks you through setting up AgentCore payments and processing your first microtransaction. By the end, your agent will be able to access paid x402 endpoints autonomously. +This tutorial walks you through setting up AgentCore payments and processing your first microtransaction. By the end, your agent will pay for a resource using the x402 protocol on a test network. @@ -15 +15 @@ This guide walks you through setting up AgentCore payments and processing your f -Before you start, ensure you have: +Before starting, make sure you have: @@ -17 +17 @@ Before you start, ensure you have: - * An AWS account with credentials configured. See [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + * **AWS Account** with credentials configured (`aws configure`) @@ -19 +19 @@ Before you start, ensure you have: - * Python 3.10+ installed. + * **Python 3.10+** installed @@ -21 +21 @@ Before you start, ensure you have: - * Boto3 installed: `pip install boto3` + * **An AWS Region where AgentCore payments is available** — us-east-1, us-west-2, eu-central-1, or ap-southeast-2. See [Supported AWS Regions](./agentcore-regions.html). @@ -23 +22,0 @@ Before you start, ensure you have: - * The AgentCore SDK installed: `pip install bedrock-agentcore[strands-agents]` @@ -25 +23,0 @@ Before you start, ensure you have: - * Credentials from at least one payment provider (Coinbase CDP or Stripe Privy). See [Prerequisites](./payments-prerequisites.html) for details. @@ -27 +24,0 @@ Before you start, ensure you have: - * An AWS Region where AgentCore payments is available (us-east-1, us-west-2, eu-central-1, or ap-southeast-2). See [Supported AWS Regions](./agentcore-regions.html). @@ -28,0 +26 @@ Before you start, ensure you have: +Install the required packages: @@ -30,0 +29 @@ Before you start, ensure you have: + pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools @@ -32 +31 @@ Before you start, ensure you have: -## Setting up payments for your first transaction +Verify your credentials are configured: @@ -34 +32,0 @@ Before you start, ensure you have: -Follow these steps to set up payments and process your first transaction: @@ -36 +34 @@ Follow these steps to set up payments and process your first transaction: - 1. **Create a payment credential provider** — Store your Coinbase CDP or Stripe Privy credentials securely in AgentCore Identity. See [Creating a payment credential provider](./resource-providers.html#payment-credential-provider). + aws sts get-caller-identity @@ -38 +36 @@ Follow these steps to set up payments and process your first transaction: - 2. **Set up IAM roles** — Configure the required roles for administration, management, execution, and service operations. See [IAM roles for AgentCore payments](./payments-iam-roles.html). +## Step 1: Obtain payment provider credentials @@ -40 +38 @@ Follow these steps to set up payments and process your first transaction: - 3. **Create a Payment Manager and Connector** — Set up the top-level resource that coordinates payment operations and connect it to your payment provider. See [Create a Payment Manager and Connector](./payments-create-manager.html). +AgentCore payments connects to an external payment provider for wallet operations. You need credentials from one of the supported providers before proceeding. @@ -42 +40 @@ Follow these steps to set up payments and process your first transaction: - 4. **Create a payment instrument** — Provision an embedded crypto wallet for your agent. See [Create a payment instrument](./payments-create-instrument.html). +###### Example @@ -44 +42 @@ Follow these steps to set up payments and process your first transaction: - 5. **Fund the wallet** — Redirect the end user to the wallet hub to top up and grant agent permissions. See [Funding the wallet](./payments-how-it-works.html#payments-how-it-works-funding-wallet). +Coinbase CDP @@ -46 +43,0 @@ Follow these steps to set up payments and process your first transaction: - 6. **Create a payment session** — Establish a time-bounded session with optional spending limits. See [Create a payment session](./payments-create-session.html). @@ -48 +45 @@ Follow these steps to set up payments and process your first transaction: - 7. **Process a payment** — Call a paid endpoint and let AgentCore payments handle the x402 flow. See [Process a payment](./payments-process-payment.html). + 1. Log in to the [Coinbase Developer Platform](https://docs.cdp.coinbase.com/api-reference/v2/authentication) and create or select a project. @@ -49,0 +47 @@ Follow these steps to set up payments and process your first transaction: + 2. Generate an API key and note the **API Key ID** , **API Key Secret** , and **Wallet Secret**. @@ -50,0 +49 @@ Follow these steps to set up payments and process your first transaction: + 3. Under **Project** > **Wallet** > **Embedded Wallets** > **Policies** , enable **Delegated signing**. @@ -53 +51,0 @@ Follow these steps to set up payments and process your first transaction: -## Quick example with Strands SDK @@ -55 +53,219 @@ Follow these steps to set up payments and process your first transaction: -The following example shows the minimal code to enable automatic payments in a Strands agent: + +You will use these three values in the next step: + +Credential | Description +---|--- +`API Key ID` | Public identifier for your CDP project +`API Key Secret` | Private secret for signing API requests +`Wallet Secret` | Secret for cryptographic wallet operations (deriving addresses, signing transactions) + +Privy + + + 1. Create a **dedicated** Privy app at [dashboard.privy.io](https://dashboard.privy.io/). Do not reuse apps that serve other purposes. + + 2. Copy the **App ID** and **App Secret** from your app settings. + + 3. Navigate to **Wallet Infrastructure** > **Authorization** and choose **New Key** to generate a P-256 key pair. + + 4. Strip the `wallet-auth:` prefix from the generated private key. Use only the raw base64 content. + + + + +You will use these four values in the next step: + +Credential | Description +---|--- +`App ID` | Your Privy application identifier +`App Secret` | Secret for server-to-server Basic Auth +`Authorization ID` | Public key identifier from the P-256 key pair +`Authorization Private Key` | Private key (base64 only, without the `wallet-auth:` prefix) + +For full details including security best practices and credential rotation, see [Prerequisites](./payments-prerequisites.html). + +## Step 2: Store credentials in AgentCore Identity + +Store your payment provider credentials as a PaymentCredentialProvider. This keeps secrets in AWS Secrets Manager rather than in your application code. + +###### Example + +Coinbase CDP + + + + import boto3 + + client = boto3.client("bedrock-agentcore-control", region_name="us-west-2") + + credential_provider = client.create_payment_credential_provider( + name="my-coinbase-credentials", + credentialProviderVendor="CoinbaseCDP", + coinbaseCdpConfig={ + "apiKeyId": "<YOUR_CDP_API_KEY_ID>", + "apiKeySecret": "<YOUR_CDP_API_KEY_SECRET>", + "walletSecret": "<YOUR_CDP_WALLET_SECRET>" + } + ) + CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"] + print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}") + +Privy + + + + import boto3 + + client = boto3.client("bedrock-agentcore-control", region_name="us-west-2") + + credential_provider = client.create_payment_credential_provider( + name="my-privy-credentials", + credentialProviderVendor="StripePrivy", + stripePrivyConfig={ + "appId": "<YOUR_PRIVY_APP_ID>", + "appSecret": "<YOUR_PRIVY_APP_SECRET>", + "authorizationId": "<YOUR_PRIVY_AUTHORIZATION_ID>", + "authorizationPrivateKey": "<YOUR_PRIVY_PRIVATE_KEY_BASE64>" + } + ) + CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"] + print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}") + +For the complete request and response schema, see [CreatePaymentCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentCredentialProvider.html) in the API Reference. + +## Step 3: Create a Payment Manager and Connector + +A Payment Manager is the top-level resource that coordinates payment operations. A Payment Connector links the manager to your payment provider credentials. Before creating these resources, set up the required IAM roles as described in [IAM roles for AgentCore payments](./payments-iam-roles.html). + +First, create the Payment Manager (the same for both providers): + + + import time + + manager = client.create_payment_manager( + name="my-first-payment-manager", + authorizerType="AWS_IAM", + roleArn="<YOUR_SERVICE_ROLE_ARN>" + ) + PAYMENT_MANAGER_ARN = manager["paymentManagerArn"] + print(f"Payment Manager created: {PAYMENT_MANAGER_ARN}") + + # Wait for the manager to reach READY state + while True: + status = client.get_payment_manager(paymentManagerArn=PAYMENT_MANAGER_ARN) + if status["status"] == "READY": + break + print(f"Status: {status['status']}... waiting") + time.sleep(5) + +Then create the Payment Connector for your provider: + +###### Example + +Coinbase CDP + + + + connector = client.create_payment_connector( + paymentManagerArn=PAYMENT_MANAGER_ARN, + name="my-coinbase-connector", + paymentConnectorType="CoinbaseCDP", + credentialProviderArn=CREDENTIAL_PROVIDER_ARN + ) + PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"] + print(f"Connector created: {PAYMENT_CONNECTOR_ID}") + +Privy + + + + connector = client.create_payment_connector( + paymentManagerArn=PAYMENT_MANAGER_ARN, + name="my-privy-connector", + paymentConnectorType="StripePrivy", + credentialProviderArn=CREDENTIAL_PROVIDER_ARN + )