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

AgentCore 付款快速入门

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

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

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

使用 “ AgentCore 付款” 技能

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

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

该技能还使用与框架无关的工具将付款汇入你的代理，因此它可以与 Strands、OpenAI Agents SDK 或任 LangGraph何 Python 框架配合使用。

先决条件

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

AWS 已配置凭据的@@ 账户 (aws configure)
可以 AgentCore 付款的 AWS 区域 — us-east-1、us-w est-2、eu-central-1 或 ap-southeast-2。参见支持的 AWS 区域。
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

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

该技能能起到什么作用

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

验证或安装 C AgentCore LI 并设置项目
创建付款管理器
暂停 — 你跑agentcore add payment-connector去输入你的提供商机密（Coinbase CDP 或 Stripe Privy 凭证）
将资源部署到您的 AWS 账户 () agentcore deploy -y
将与框架无关的支付工具 () x402_payment_tool.py 连接到您的代理
通过 SDK 创建按用户使用的钱包（工具）和预算有限的会话
暂停 — 您授权钱包（委托），并使用来自 Circle 水龙头网站的测试网 USDC 为其注资
设置环境变量并针对付费端点运行测试付款

在运行连接器命令之前，请从您的提供商那里获取凭证：

C@@ oinbase CDP — 来自 Coinb ase 开发者平台网站的 API 密钥 ID、API 密钥和钱包密钥（启用委托签名）。
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+
可以 AgentCore 付款的 AWS 区域 — us-east-1、us-w est-2、eu-central-1 或 ap-southeast-2。参见支持的 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 步：获取支付服务提供商凭证

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

例

Coinbase CDP

登录 Coinbase 开发者平台并创建或选择一个项目。
生成 API 密钥并记下 API 密钥 ID、API 密钥密钥和钱包密钥。
在 “项目” > “钱包” > “Non-custodial 钱包” > “安全” 下，启用委托签名。

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

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

Privy

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

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

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

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

步骤 2：在 “ AgentCore 身份” 中存储凭证

将您的支付服务提供商凭证存储为 PaymentCredentialProvider. 这会将机密保存在S AWS ecrets Manager中，而不是您的应用程序代码中。

例

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

CLI 替代方案：存储凭证

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

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

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

例

Console

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

打开 Amazon Bedrock AgentCore 控制台。
在导航窗格的 “构建” 下，选择 “付款”。
选择 “创建付款管理器”。
输入您的付款管理器的姓名。
在 “权限” 下，选择创建并使用新的服务角色（或选择现有角色）。
在入站身份验证下，选择使用 IAM 用户名进行 I AM 授权。
（可选）在支付连接器部分中，为连接器选择一个名称，然后选择现有的出站身份验证，或者通过选择您的提供商（Coinbase 或 Stripe Privy）并输入您的凭据来创建新的出站身份验证。
选择 “创建付款管理器”。

AgentCore CLI

CLI 在一个流程中创建凭证提供商、付款管理器和支付连接器。在您的 AgentCore 项目目录中，将付款管理器和连接器一起添加。

交互式向导：


agentcore add payment-manager

向导会提示输入经理姓名、模式（拦截器）、自动付款切换开关和默认支出限额。然后，它会询问是否添加连接器，并逐步完成提供商选择和凭据输入。

Non-interactive （Coinbase CDP）：


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

agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --api-key-id <YOUR_CDP_API_KEY_ID> \
  --api-key-secret <YOUR_CDP_API_KEY_SECRET> \
  --wallet-secret <YOUR_CDP_WALLET_SECRET>

Non-interactive （Privy）：


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

agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-privy-connector \
  --provider StripePrivy \
  --app-id <YOUR_PRIVY_APP_ID> \
  --app-secret <YOUR_PRIVY_APP_SECRET> \
  --authorization-id <YOUR_PRIVY_AUTHORIZATION_ID> \
  --authorization-private-key <YOUR_PRIVY_PRIVATE_KEY_BASE64>

添加后，部署以配置支付基础架构：


agentcore deploy

部署步骤创建 IAM 角色，在 Ident AgentCore ity 中存储证书，并配置支付管理器和连接器。您将在输出中看到 “创建支付基础设施...”。

AgentCore SDK

S AgentCore DK 只需一次调用即可创建付款管理器、凭证提供商和连接器。


from bedrock_agentcore.payments import PaymentClient

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

response = payment_client.create_payment_manager_with_connector(
    payment_manager_name="my-first-payment-manager",
    payment_manager_description="Payment manager for my agent.",
    authorizer_type="AWS_IAM",
    role_arn="<YOUR_SERVICE_ROLE_ARN>",
    payment_connector_config={
        "name": "my-coinbase-connector",
        "description": "Coinbase CDP connector",
        "payment_credential_provider_config": {
            "name": "my-coinbase-provider",
            "credential_provider_vendor": "CoinbaseCDP",
            "credentials": {
                "api_key_id": "<YOUR_CDP_API_KEY_ID>",
                "api_key_secret": "<YOUR_CDP_API_KEY_SECRET>",
                "wallet_secret": "<YOUR_CDP_WALLET_SECRET>",
            },
        },
    },
    wait_for_ready=True,
    max_wait=300,
    poll_interval=5,
)

PAYMENT_MANAGER_ARN = response["paymentManager"]["paymentManagerArn"]
PAYMENT_CONNECTOR_ID = response["paymentConnector"]["paymentConnectorId"]
print(f"Payment Manager ARN: {PAYMENT_MANAGER_ARN}")
print(f"Connector ID: {PAYMENT_CONNECTOR_ID}")

对于 Stripe Privy，请将替换为credential_provider_vendor: "StripePrivy"和相应的 Privy payment_credential_provider_config 凭据。

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 CLI 工作流程，请参阅创建付款管理器和连接器。

AWS SDK

首先，创建付款管理器（两个提供商都相同）：


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)

然后为您的提供商创建支付连接器：

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
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(f"Connector created: {PAYMENT_CONNECTOR_ID}")

如果您没有服务角色，请参阅用于 AgentCore 付款的 IAM 角色以获取有关创建该角色的说明。控制台也可以代表您创建角色。有关完整的请求和响应架构，请参阅 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— 存储在 Ident AgentCore ity 中的支付提供商凭证
PaymentManager— 协调支付业务的 Top-level 资源
PaymentConnector— 您的经理和外部支付提供商之间的集成
PaymentInstrument— 嵌入式加密钱包，由最终用户资助和授权
PaymentSession— 有时间限制、预算有限的支付环境
Strands Agent — 自动处理 x402 付款的人工智能代理

后续步骤

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

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

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

文档惯例

核心概念

工作原理