支付框架集成 AgentCore

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

Strands Agents

AgentCore 付款插件为Strands Agents提供自动付款处理。它支持 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 主网和 Base（以太坊 L2），以降低交易费用。

配置选项

下表列出了AgentCorePaymentsPluginConfig参数：

Built-in 代理工具

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

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

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 支付流程：

使用回调处理错误

使用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枚举提供了以下选项：

禁用自动付款

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

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 主网和 Base（以太坊 L2），以降低交易费用。

配置选项

下表列出了AgentCorePaymentsConfig参数：

Built-in 代理工具

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

同步与异步

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

同步：

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

异步：

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

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