支付框架集成 AgentCore

AgentCore 支付与流行的代理框架集成，提供自动付款处理。每个框架使用不同的集成模式：

Strands Agents — 使用挂Plugin-based 钩进行集成
LangGraph— 封装工具调用的Middleware-based 集成

Strands Agents

AgentCore 付款插件为Strands代理提供自动付款处理。它支持 x402 需要付款协议，使代理能够自动处理 HTTP 402 响应。

安装


pip install 'bedrock-agentcore[strands-agents]'

配置和使用该插件


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

# Configure the plugin
config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    payment_session_id="payment-session-xuzrnUCd7RT725G",
    region="us-west-2",
)

# Create the plugin
plugin = AgentCorePaymentsPlugin(config=config)

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

# Use the agent -- 402 responses are automatically handled
agent("access https://drvd12nxpcyd5.cloudfront.net/market-recap")

处理付款中断

当付款处理失败时，插件会存储故障并引发中断。您的应用程序应处理以下中断：


result = agent("Access the premium endpoint at https://api.example.com/premium")
while result.stop_reason == "interrupt":
    responses = []
    for interrupt in result.interrupts:
        if interrupt.name.startswith("payment-failure-"):
            reason = interrupt.reason
            exception_type = reason.get("exceptionType")

            if exception_type == "PaymentInstrumentConfigurationRequired":
                plugin.config.update_payment_instrument_id("payment-instrument-new123")
                responses.append({
                    "interruptResponse": {
                        "interruptId": interrupt.id,
                        "response": "Payment instrument configured. Please retry.",
                    }
                })
            elif exception_type == "PaymentSessionConfigurationRequired":
                plugin.config.update_payment_session_id("payment-session-new456")
                responses.append({
                    "interruptResponse": {
                        "interruptId": interrupt.id,
                        "response": "Payment session configured. Please retry.",
                    }
                })
            else:
                responses.append({
                    "interruptResponse": {
                        "interruptId": interrupt.id,
                        "response": f"Payment failed: {reason.get('exceptionMessage')}",
                    }
                })

    result = agent(responses)

禁用自动付款

要仅访问不执行自动付款的支付可见性工具（例如，在任何支付交易之前让人工或自定义逻辑保持在循环中），请禁用自动处理：


config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-east-1:123456789012:payment-manager/pm-abc123",
    user_id="user-123",
    region="us-east-1",
    auto_payment=False,  # Disable automatic 402 processing
)

网络偏好

您可以为付款处理指定首选的区块链网络：


config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-east-1:123456789012:payment-manager/pm-abc123",
    user_id="user-123",
    payment_instrument_id="payment-instrument-xyz789",
    payment_session_id="payment-session-def456",
    region="us-east-1",
    network_preferences_config=["eip155:8453", "base-sepolia", "solana-mainnet"],
)

如果未指定，则系统使用默认优先顺序优先考虑 Solana 主网和基地（以太坊 L2）以降低交易费用。

配置选项

下表列出了AgentCorePaymentsPluginConfig参数：

参数	Type	必需	描述
`payment_manager_arn`	`str`	是	Bedrock P AgentCore ayment Manager 资源的 ARN
`user_id`	`str`	是	用户的唯一标识符
`payment_instrument_id`	`Optional[str]`	否	付款工具编号。可以稍后通过以下方式进行设置 `update_payment_instrument_id()`
`payment_session_id`	`Optional[str]`	否	付款会话 ID。可以稍后通过以下方式进行设置 `update_payment_session_id()`
`region`	`Optional[str]`	否	AWS 付款管理器区域
`network_preferences_config`	`Optional[list[str]]`	否	按优先顺序排列的网络 CAIP-2 标识符列表
`auto_payment`	`bool`	否（默认值：`True`）	是否自动处理 402 付款要求
`max_interrupt_retries`	`int`	否（默认值：`5`）	每次使用工具的最大中断重试次数。设置为 0 以禁用中断
`agent_name`	`Optional[str]`	否	在 API 调用时通过 HTTP 标头传播代理名称

Built-in 代理工具

该插件注册了三种工具，代理商可以在运行时使用这些工具来查询付款信息：

工具	说明
`get_payment_instrument`	检索有关特定支付工具的详细信息
`list_payment_instruments`	列出用户的所有付款工具
`get_payment_session`	检索有关付款会话的详细信息（预算、状态、到期时间）

这些工具使代理能够在对话中就付款方式和付款限额做出明智的决定。有关更多详细信息和端到端示例，请参阅 Strands 代理文档。

LangGraph

AgentCore 支付中间件为 LangGraph 代理提供自动付款处理。它支持 x402 需要付款协议，使代理能够自动处理 HTTP 402 响应。

安装


pip install 'bedrock-agentcore[langgraph]'

配置和使用中间件


from langchain.agents import create_agent
from bedrock_agentcore.payments.integrations.langgraph import (
    AgentCorePaymentsConfig,
    AgentCorePaymentsMiddleware,
)

config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
)

payments = AgentCorePaymentsMiddleware(config)

agent = create_agent(
    model="us.anthropic.claude-sonnet-4-20250514-v1:0",
    tools=[],
    middleware=[payments],
)

result = agent.invoke({"messages": [{"role": "user", "content": "access https://drvd12nxpcyd5.cloudfront.net/market-recap"}]})
print(result)

中间件的工作原理

中间件拦截工具调用并分六个步骤处理 x402 付款流程：

代理进行工具调用，从而向付费终端节点发出 HTTP 请求。
该端点以 HTTP 402 “需要付款” 和 x402 付款有效载荷进行响应。
中间件拦截402响应并提取付款要求。
中间件调ProcessPayment用支付工具和会话以生成加密证明。
中间件会重试附有付款证明标头的原始请求。
端点验证证明并将请求的内容返回给代理。

使用回调进行错误处理

使用on_payment_error回调来优雅地处理付款失败：


from bedrock_agentcore.payments.integrations.langgraph import (
    AgentCorePaymentsConfig,
    AgentCorePaymentsMiddleware,
    ErrorResolution,
)

def handle_payment_error(error, context):
    """Custom error handler for payment failures."""
    if "InsufficientFunds" in str(error):
        return ErrorResolution.STOP  # Stop the agent
    return ErrorResolution.RETRY  # Retry with updated config

config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
    on_payment_error=handle_payment_error,
)

该ErrorResolution枚举提供以下选项：

值	行为
`RETRY`	使用当前配置重试付款
`STOP`	停止处理并将错误返回给代理
`SKIP`	跳过付款，继续不使用付费内容

禁用自动付款

要禁用自动付款处理并要求明确的付款批准，请执行以下操作：


config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    region="us-west-2",
    auto_payment=False,  # Disable automatic 402 processing
)

如果auto_payment是False，中间件会向代理显示 402 个响应，而不对其进行处理，从而允许在付款前进行自定义逻辑或人工批准。

付款工具许可名单

限制哪些工具可以触发自动付款：


config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
    tool_allowlist=["http_request", "web_fetch", "mcp_call"],
)

只有来自许可名单中工具的工具调用才会触发自动付款处理。来自其他工具的工具调用无需支付拦截即可通过。

网络偏好

您可以为付款处理指定首选的区块链网络：


config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
    network_preferences_config=["eip155:8453", "base-sepolia", "solana-mainnet"],
)

如果未指定，则系统使用默认优先顺序优先考虑 Solana 主网和基地（以太坊 L2）以降低交易费用。

配置选项

下表列出了AgentCorePaymentsConfig参数：

参数	Type	必需	描述
`payment_manager_arn`	`str`	是	Bedrock P AgentCore ayment Manager 资源的 ARN
`user_id`	`str`	是	用户的唯一标识符
`payment_instrument_id`	`Optional[str]`	否	支付工具 ID
`payment_session_id`	`Optional[str]`	否	付款会话 ID。什么时候`auto_session`不需要 `True`
`region`	`Optional[str]`	否	AWS 付款管理器区域
`auto_session`	`bool`	否（默认值：`False`）	自动创建或重复使用付款会话
`auto_session_expiry_minutes`	`int`	否（默认值：`60`）	自动创建的会话的到期时间（以分钟为单位）
`auto_session_max_spend`	`str`	否（默认值：`"5.00"`）	自动创建的会话的最大支出金额
`auto_session_currency`	`str`	否（默认值：`"USD"`）	自动创建的会话支出限额的货币
`auto_payment`	`bool`	否（默认值：`True`）	是否自动处理 402 付款要求
`network_preferences_config`	`Optional[list[str]]`	否	按优先顺序排列的网络 CAIP-2 标识符列表
`tool_allowlist`	`Optional[list[str]]`	否	可以触发自动付款的工具名称列表。如果未设置，所有工具都可以触发付款
`max_retries`	`int`	否（默认值：`3`）	每次工具调用的最大付款重试次数
`on_payment_error`	`Optional[Callable]`	否	付款失败时调用回调函数
`on_payment_success`	`Optional[Callable]`	否	成功付款时调用回调函数
`on_payment_start`	`Optional[Callable]`	否	在付款处理开始之前调用回调函数
`agent_name`	`Optional[str]`	否	在 API 调用时通过 HTTP 标头传播代理名称
`endpoint_url`	`Optional[str]`	否	AgentCore 支付服务的自定义终端节点 URL

Built-in 代理工具

中间件注册了五种工具，代理商可以在运行时使用这些工具来查询和管理付款信息：

工具	说明
`get_payment_instrument`	检索有关特定支付工具的详细信息
`list_payment_instruments`	列出用户的所有付款工具
`get_payment_session`	检索有关付款会话的详细信息（预算、状态、到期时间）
`get_payment_balance`	检索支付工具的当前余额
`list_payment_sessions`	列出用户的所有付款会话

同步与异步

LangGraph 中间件支持同步和异步执行：

同步：


result = agent.invoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})

异步：


result = await agent.ainvoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})

两种模式都支持相同的配置选项和付款处理行为。与异步框架集成或处理多个并发代理时使用异步。

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

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

文档惯例

处理付款

可观测性