使用 AgentCore 付款技能使用 CLI、SDK 或 Boto3 问题排查资源清理你建造了什么后续步骤

AgentCore 付款快速入门

本教程将引导您设置 AgentCore 付款和处理您的第一笔微交易。最后，您的代理将在测试网络上使用 x402 协议支付资源费用。

您可以通过两种方式设置付款：

使用 AgentCore 付款技能 — 一种自动设置体验，通过与 Kiro、Claude Code 或 Codex 等人工智能编程代理进行引导式对话来配置所有资源。该技能可为您处理 CLI 命令、SDK 脚本和框架布线。
使用 CLI、SDK 或 Boto3 — 直接使用 AgentCore CLI、 AWS SDK 或 AWS CLI 进行分步手动设置。

在创建 Coinbase 连接器时，您可以通过两种方式提供凭据。使用快速创建（推荐），您可以通过Coinbase和 AgentCore 付款条款进行授权，并为您存储凭据——无需生成或粘贴密钥。使用手动，您可以提供自己生成的Coinbase API密钥。Stripe（Privy）仅使用手动流程。使用快速创建，您可以跳过手动设置的第 1 步和第 2 步。

使用 AgentCore 付款技能

AgentCore 付款技能通过交互式、引导式体验自动完成整个设置过程。它提供以下资源：

PaymentCredentialProvider— 在 I AgentCore dentity 中存储支付提供商凭证。
付款管理器 — 协调支付操作的顶级资源。
付款连接器 — 通过 AgentCore CLI 将经理链接到您的凭证。
支付工具 — 您的代理人用来代表用户向商家付款的加密钱包。
付款会话 —带有支出限额的时间限制的背景。

该技能还使用与框架无关的工具向您的代理汇款，因此它适用于Strands LangGraph、OpenAI Agents SDK或任何Python框架。

先决条件

在开始之前，请确保你有：

AWS 配置了凭据的账户 (aws configure)
可以 AgentCore 付款的地 AWS 区 -请参阅支持 AWS 的地区。
Coinbase AWS 市场订阅（仅限Coinbase）——如果您使用Coinbase作为支付提供商，则必须订阅市场中的 Coinbase AgentCore 付款钱包列表。 AWS 通过此订阅，您的Coinbase钱包使用费将根据Coinbase在Coinbase网站上的定价合并到您的月度 AWS 账单中。请参阅订阅Coinbase钱包以在 AWS 市场上 AgentCore 付款。
Node.js 已安装 20 个以上（该技能会自动安装 AgentCore CLI）
访问付费终端节点的代理 — 该技能使您的代理能够为受 x402 保护的 API 付费。要进行测试，您可以使用沙盒端点https://sandbox.node4all.com/v1/x402-test。
安装在 AI 编码代理中的 AWSaws-agents插件代理工具包：
例
Claude Code

/plugin marketplace add aws/agent-toolkit-for-aws /plugin install aws-agents@agent-toolkit-for-aws

Codex

该插件是从市场清单中自动发现的。要添加市场，请运行以下命令：

codex plugin marketplace add aws/agent-toolkit-for-aws

调用技能

付款技能是代理工具包中agents-build技能的一部分 AWS。要触发它，请在 AI 编码代理中描述你的意图。例如：

“使用aws-agents插件中的agents-build技能向我的代理添加付款”
“使用aws-agents插件中的agents-build技能为我的代理设置微交易”
“我需要使用aws-agents插件中的agents-build技能处理 402 个 “需要付款” 的回复
“电汇我的代理使用插件中的agents-build技能来支付受 x402 保护的 API” aws-agents

该技能可检测与付款相关的意图并自动加载付款工作流程。

这个技能能做什么

该技能运行一个自动化流程，端到端地配置您的支付基础设施。该技能会自动运行大多数步骤，并会暂停两次以供您输入：

验证或安装 AgentCore CLI 并设置项目
创建付款管理器
暂停 -您添加付款连接器。对于支持快速创建（推荐）的 Coinbase，您可以通过Coinbase进行授权， AgentCore 付款会为您提供凭据——无需输入任何秘密。对于 Coinbase手册或 Stripe（Privy），你agentcore add payment-connector需要输入提供商的密码。
向您的 AWS 账户部署资源 () agentcore deploy -y
将与框架无关的付款工具 () x402_payment_tool.py 绑定到您的代理
通过 SDK 创建每用户钱包（工具）和预算限制会话
暂停 — 您授权钱包（委托），然后使用Circle水龙头网站上的测试网USDC为其提供资金
设置环境变量并针对付费终端节点进行测试付款

如果您使用手动流程（Coinbase手册或Stripe Privy），请在添加连接器之前从您的提供商那里获取证书。使用Coinbase 快速创建，你可以跳过这个——你可以通过Coinbase进行授权，而不是粘贴密钥。

Coinbase CDP（仅限手动）— 来自 Co inbase 开发者平台网站的 API 密钥 ID、API 密钥和钱包密钥（启用委托签名）。Coinbase还要求在 AWS 市场上积极订阅 Coinbase AgentCore 付款钱包列表。请参阅订阅Coinbase钱包以在 AWS 市场上 AgentCore 付款。
Stripe Privy — 来自 Priv y 仪表板网站的应用程序 ID、应用程序密钥、授权 ID 和授权私钥。

成功运行显示代理正在呼叫x402_fetch、检测到402、通过 AgentCore SDK 结算付款，然后重试返回200付费内容。

使用 CLI、SDK 或 Boto3

本节将引导您使用 AgentCore CLI、 AWS CLI 或 AWS SDK (Boto3) 手动完成每个步骤。

先决条件

在开始之前，请确保你有：

AWS 配置了凭据的账户 (aws configure)
已安装 Python 3.10+
Coinbase AWS 市场订阅（仅限Coinbase）——如果您使用Coinbase作为支付提供商，则必须订阅市场中的 Coinbase AgentCore 付款钱包列表。 AWS 通过此订阅，您的Coinbase钱包使用费将根据Coinbase在Coinbase网站上的定价合并到您的月度 AWS 账单中。请参阅订阅Coinbase钱包以在 AWS 市场上 AgentCore 付款。
可以 AgentCore 付款的地 AWS 区 -请参阅支持 AWS 的地区。

安装所需的软件包：


pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools

验证您的证书是否已配置：


aws sts get-caller-identity

提示

如果您安装了 AgentCore CLI v0.19.0 或更高版本，则可以在步骤 2、3、5 和 6 中使用 CLI 命令作为软件开发工具包的替代方案。以下每个步骤都显示了这两个选项。

第 1 步：获取支付服务提供商证书（手动流程）

步骤1和2适用于手动凭证流程——Coinbase（手动）或Stripe（Privy）。

注意

为 Coinbase 使用快速创建（推荐）。跳过步骤 1 和 2，查看步骤 3 。 AgentCore 付款会在您通过Coinbase进行授权后为您提供Coinbase凭证——您无需获取或存储任何密钥。

AgentCore 支付连接到外部支付提供商进行钱包操作。在继续操作之前，您需要从支持的提供商处获得证书。

例

Coinbase CDP

登录到 Coinbase开发者平台并创建或登录您的帐户。选择项目。
导航到您的 API 密钥控制面板，选择创建机密 API 密钥，然后记下 API 密钥 ID 和 API 密钥密钥。回到你的项目。
在 “产品” > “钱包” > “Non-custodial 钱包” > “安全” 下，选择 “生成新钱包密钥”，并记下钱包密钥。
在 “产品” > “钱包” > “Non-custodial 钱包” > “安全” 下，启用委托签名。

您将在下一步中使用这些值：

凭证	说明
`API Key ID`	您的 CDP 项目的公共标识符
`API Key Secret`	用于签署 API 请求的私钥
`Wallet Secret`	加密钱包操作的秘密（派生地址、签署交易）

Privy

在 dash board.p rivy.io 上创建专用 Privy 应用程序。不要重复使用用于其他目的的应用程序。
从您的应用程序设置中复制应用程序 ID 和应用程序密钥。
导航到 “钱包基础架构” > “授权”，然后选择 “新密钥” 以生成 P-256 密钥对。

您将在下一步中使用这四个值：

凭证	说明
`App ID`	您的 Privy 应用程序标识符
`App Secret`	服务器到服务器基本身份验证的密钥
`Authorization ID`	密钥对中的公 P-256 钥标识符
`Authorization Private Key`	密钥对中的私 P-256 钥

有关包括安全最佳实践和凭证轮换在内的完整详细信息，请参阅先决条件。

第 2 步：将凭据存储在 AgentCore Identity 中（手动流程）

将您的支付服务提供商凭证存储为 PaymentCredentialProvider. 这会将机密保存在 AWS 密钥管理器中，而不是保存在您的应用程序代码中。如果您使用的是Coinbase 快速创建，请跳过此步骤。 AgentCore 付款会在步骤 3 中为您创建和存储凭证提供商。

例

有关完整的请求和响应架构，请参阅 API 参考CreatePaymentCredentialProvider中的。

CLI 替代方案：存储凭证

使用 AgentCore CLI，当您添加支付连接器时，凭据存储会自动生成（步骤 3）。如果您计划使用 CLI 路径，请跳过此步骤。

第 3 步：创建付款管理器和连接器

付款管理器是协调支付操作的顶级资源。支付连接器将经理链接到您的支付服务提供商证书。在创建这些资源之前，按照 AgentCore 付款的 IAM 角色中所述设置所需的 IAM 角色。

首先，创建付款管理器（适用于所有提供商）：

例

Console

打开亚马逊 Bedrock AgentCore 控制台。
在导航窗格的 “构建” 下，选择 “付款” 。
选择创建付款经理，输入名称，然后在权限下选择创建和使用新的服务角色（或选择现有角色）。
在 “入站身份验证” 下，选择 “使用 IAM 用户名”。
选择 “创建付款管理器” 。您可以在下面的提供商部分中添加连接器。

有关包括 JWT 授权和自定义声明在内的完整控制台演练，请参阅创建支付管理器和连接器。

AgentCore CLI


agentcore add payment-manager \
  --name my-payment-manager \
  --auto-payment \
  --default-spend-limit 5.00

在下面的提供商部分添加连接器，然后运行agentcore deploy。

AgentCore SDK


from bedrock_agentcore.payments.client import PaymentClient

payment_client = PaymentClient(region_name="us-west-2")

manager = payment_client.create_payment_manager(
    name="my-first-payment-manager",
    authorizer_type="AWS_IAM",
    role_arn="<YOUR_SERVICE_ROLE_ARN>",
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

PAYMENT_MANAGER_ID与一起payment_client在下面的提供商部分中创建连接器。

AWS CLI


aws bedrock-agentcore-control create-payment-manager \
  --name "my-first-payment-manager" \
  --authorizer-type AWS_IAM \
  --role-arn "<YOUR_SERVICE_ROLE_ARN>" \
  --region us-west-2

等待管理员到达READY，然后在下面的提供商部分中创建连接器。

AWS SDK


import time

manager = client.create_payment_manager(
    name="my-first-payment-manager",
    authorizerType="AWS_IAM",
    roleArn="<YOUR_SERVICE_ROLE_ARN>"
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

while client.get_payment_manager(paymentManagerId=PAYMENT_MANAGER_ID)["status"] != "READY":
    time.sleep(5)

然后为您的提供商创建支付连接器。选择 Coinbase 部分（快速创建或手动）或 Stripe（Privy）部分。

Coinbase — 快速创建（推荐）

使用快速创建，您无需获取或存储Coinbase凭证。在控制台中，您可以通过选择 “使用Coinbase 快速创建” 来完成此操作。使用 AWS 命令行界面、 AWS 软件开发工具包、 AgentCore 命令行界面或 AgentCore 软件开发工具包，传递一个空的provisionMode=QUICK_CREATE凭证列表。连接器启动PENDING_AUTHENTICATION并返回authorizationUrl。你在浏览器authorizationUrl中打开返回的。在您通过 Coinbase 进行授权后， AgentCore 付款会预置凭据并将连接器移至READY。

例

Console

在支付连接器部分中，选择添加出站身份验证 > 创建付款身份验证，对于支付提供商，选择 Coinbase。
选择快速创建配置-推荐，然后选择创建付款身份验证。
Coinbase窗口打开——登录或注册并授权（链接）您的CoinbaseCDP账户。
AgentCore 付款会提供 Coinbase CDP API 密钥和钱包密钥并为您存储它们。连接器从移动PENDING_AUTHENTICATION到READY。

AgentCore CLI


agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --provision-mode QUICK_CREATE

agentcore deploy

CLI 打开 Coinbase 授权流程。在您授权后，服务会提供证书，连接器就会到达READY。

AgentCore SDK


connector = payment_client.create_payment_connector(
    payment_manager_id=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    connector_type="CoinbaseCDP",
    credential_provider_configurations=[],
    provision_mode="QUICK_CREATE",
)
# Open connector["authorizationUrl"], authorize through Coinbase,
# then poll get_payment_connector until status == "READY".

AWS CLI


aws bedrock-agentcore-control create-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --name "my-coinbase-connector" \
  --type CoinbaseCDP \
  --credential-provider-configurations '[]' \
  --provision-mode QUICK_CREATE \
  --region us-west-2

响应包括status: PENDING_AUTHENTICATION和authorizationUrl. 在浏览器中打开网址并完成 Coinbase 授权，然后轮询直到连接器READY变成：


aws bedrock-agentcore-control get-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --payment-connector-id "<PAYMENT_CONNECTOR_ID>" \
  --region us-west-2

AWS SDK


connector = client.create_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    type="CoinbaseCDP",
    credentialProviderConfigurations=[],
    provisionMode="QUICK_CREATE",
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(connector["status"], connector.get("authorizationUrl"))
# PENDING_AUTHENTICATION  https://...
# Open the authorizationUrl, authorize, then poll get_payment_connector until READY.

Coinbase — 手册

使用您自己生成的 Coinbase CDP 凭证（步骤 1—2）。创建凭证提供商，然后创建引用其 ARN 的连接器。有关控制台或 AgentCore CLI 的手册演练，请参阅创建支付管理器和连接器。

例

Stripe（Privy）— 手册

Stripe（Privy）仅使用手动流程。使用您的 Privy 凭据创建凭证提供商（步骤 1—2），然后创建引用其 ARN 的连接器。有关控制台或 AgentCore CLI 的手册演练，请参阅创建支付管理器和连接器。

例

如果您没有服务角色，请参阅用于 AgentCore 付款的 IAM 角色以获取创建服务角色的说明。控制台还可以代表你创建角色。有关完整的请求和响应架构，请参阅亚马逊基岩 AgentCore 控制 API 参考CreatePaymentConnector中的CreatePaymentManager和。

第 4 步：创建付款工具

支付工具是一种嵌入式加密钱包，您的代理使用它代表用户向商家付款。每种工具都与特定的区块链网络相关联。

例

AgentCore SDK


from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

instrument = manager.create_payment_instrument(
    user_id="test-user-123",
    payment_connector_id=PAYMENT_CONNECTOR_ID,
    payment_instrument_type="EMBEDDED_CRYPTO_WALLET",
    payment_instrument_details={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

AWS CLI


aws bedrock-agentcore create-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --user-id "test-user-123" \
    --payment-instrument-type "EMBEDDED_CRYPTO_WALLET" \
    --payment-instrument-details '{
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

保存响应redirectUrl中的paymentInstrumentId和。

AWS SDK


import uuid

dp_client = boto3.client("bedrock-agentcore", region_name="us-west-2",
    endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com")

instrument = dp_client.create_payment_instrument(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentType="EMBEDDED_CRYPTO_WALLET",
    paymentInstrumentDetails={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
    clientToken=str(uuid.uuid4()),
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

有关完整的请求和响应架构，请参阅 API 参考CreatePaymentInstrument中的。

为钱包注资并授予权限

在代理进行交易之前，最终用户必须为钱包注资并授予签名权限。在浏览器redirectUrl中打开上面响应中的。在钱包中心，用户可以：

使用加密转账、 credit/debit 信用卡、Apple Pay、Google Pay 或 ACH 为钱包充值
授予代理人代表他们签署交易的权限

对于测试环境，使用测试网 USDC 为钱包注资。

资助后，轮询仪器状态，直到其变成ACTIVE：

例

有关按提供商划分的资金流的更多详细信息，请参阅为钱包注资。

第 5 步：创建付款会话

付款会话是一个有时间限制的环境，具有可选的支出限额。当会话到期或预算用尽时，代理无法在该会话内进一步付款。

例

第 6 步：向 Strands 代理处理付款

在所有资源都准备就绪后，创建一个自动处理 x402 付款的 Strands 代理。当代理调用付费端点并收到 HTTP 402 响应时，支付插件对交易进行签名并重试请求。

例

AgentCore CLI

使用付款上下文调用已部署的代理。CLI 在运行时将支付工具和会话传递给代理，代理的 x402 拦截器会自动处理付款。


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id test-user-123

要传递显式会话而不是自动创建会话，请执行以下操作：


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --payment-session-id <SESSION_ID> \
  --payment-user-id test-user-123

AgentCore SDK

当您收到 HTTP 402 响应时，使用PaymentManager类生成付款标头：


import uuid
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

# When you receive a 402 response, generate payment proof
payment_required_request = {
    "statusCode": 402,
    "headers": payment_required["headers"],
    "body": payment_required["body"],
}
payment_proof_headers = manager.generate_payment_header(
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    payment_required_request=payment_required_request,
    client_token=str(uuid.uuid4()),
)

payment_proof_headers包含付款证明标题。重试向付费终端节点发出的请求时，请包含此标头。

AWS CLI

使用 x402 有效负载process-payment直接拨打电话（当你自己处理支付编排时使用）：


aws bedrock-agentcore process-payment \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-session-id "$SESSION_ID" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --payment-type "CRYPTO_X402" \
    --payment-input '{
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0xMERCHANT_ADDRESS",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"}
            }
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

有关完整的请求和响应架构，请参阅 API 参考ProcessPayment中的。

AWS SDK


from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin

config = AgentCorePaymentsPluginConfig(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    region="us-west-2",
)

plugin = AgentCorePaymentsPlugin(config=config)
agent = Agent(
    system_prompt="You are a helpful assistant that can access paid APIs.",
    tools=[http_request],
    plugins=[plugin],
)

# The agent handles 402 responses automatically
response = agent("Access the premium endpoint at https://example-x402-merchant.com/paid-api")
print(response)

有关底层 API 调用的完整请求和响应架构，请参阅 API 参考ProcessPayment中的。

验证付款

代理处理付款后，检查会话以确认交易已记录：

例

问题排查

以下问题适用于基于技能的设置路径和手动设置路径。

问题	解决方案
付款经理在创建时卡住了	最多等待 2 分钟。如果它移至 CREATE_FAILED，请检查您的服务角色 ARN 和权限是否正确。
“PaymentInstrument 未激活”	在代理进行交易之前，最终用户必须通过重定向网址为钱包注资并授予签名权限。
“会话已过期或超出预算”	创建一个到期时间更长或支出限额更高的新付款会话。
“CredentialProvider 未找到”	验证凭证提供商 ARN 与您在步骤 2 中创建的 ARN 相匹配。确保所有通话的区域保持一致。
ProcessPayment 退货失败	检查钱包是否有足够的USDC余额来支付交易金额和汽油费。

资源清理

删除您在本教程中创建的资源：

例

你建造了什么

通过本教程，您创建了：

PaymentCredentialProvider— 支付提供商凭证存储在 AgentCore Identity 中
PaymentManager— 协调支付业务的 Top-level 资源
PaymentConnector— 您的经理与外部支付提供商之间的整合
PaymentInstrument— 嵌入式加密钱包，由最终用户资助和授权
PaymentSession— 有时间限制、预算有限的付款环境
Strands Agent — 自动处理 x402 付款的 AI 代理

后续步骤

连接到 Coinbase x402 Bazaar，发现 10,000 多种付费 MCP 工具。
与浏览器工具集成以访问付费网站。
启用可观察性以监控中的支付操作。 CloudWatch
查看 IAM 角色以配置最低权限的生产访问权限。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

核心概念

工作原理