# 支付框架集成 AgentCore
<a name="payments-framework-integrations"></a>

AgentCore payments 与流行的代理框架集成，提供自动付款处理。每个框架都使用不同的集成模式：
+  **[Strands Agen](#payments-framework-strands)** ts — Plugin-based 使用挂钩进行
+  **[LangGraph](#payments-framework-langgraph)**— 封装工具调用的Middleware-based 集成

## Strands Agents
<a name="payments-framework-strands"></a>

 AgentCore 付款插件为Strands Agents提供自动付款处理。它支持 [x402 需要付款](https://www.x402.org/)协议，使代理能够自动处理 HTTP 402 响应。

### 安装
<a name="payments-framework-strands-install"></a>

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

### 配置和使用插件
<a name="payments-framework-strands-usage"></a>

```
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")
```

### 处理付款中断
<a name="payments-framework-strands-interrupts"></a>

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

```
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)
```

### 禁用自动付款
<a name="payments-framework-strands-auto-payment"></a>

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

```
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
)
```

### 网络首选项
<a name="payments-framework-strands-network"></a>

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

```
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），以降低交易费用。

### 配置选项
<a name="payments-framework-strands-config"></a>

下表列出了`AgentCorePaymentsPluginConfig`参数：


| 参数 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `payment_manager_arn`  |  `str`  | 是 | 基岩 AgentCore 支付管理器资源的 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 代理工具
<a name="payments-framework-strands-tools"></a>

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


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

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



## LangGraph
<a name="payments-framework-langgraph"></a>

 AgentCore 支付中间件为 LangGraph 代理提供自动付款处理。它支持 [x402 需要付款](https://www.x402.org/)协议，使代理能够自动处理 HTTP 402 响应。

### 安装
<a name="payments-framework-langgraph-install"></a>

```
pip install 'bedrock-agentcore[langgraph]'
```

### 配置和使用中间件
<a name="payments-framework-langgraph-usage"></a>

```
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)
```

### 中间件的工作原理
<a name="payments-framework-langgraph-how-it-works"></a>

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

1. 代理进行工具调用，从而向付费端点发出 HTTP 请求。

1. 端点以 HTTP 402 “需要付款” 和 x402 付款有效负载进行响应。

1. 中间件拦截 402 响应并提取付款要求。

1. 中间件使用支付工具和会话调`ProcessPayment`用以生成加密证明。

1. 中间件在附加付款证明标头的情况下重试原始请求。

1. 端点验证证据，并将请求的内容返回给代理。

### 使用回调处理错误
<a name="payments-framework-langgraph-error-handling"></a>

使用`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`  | 跳过付款，在没有付费内容的情况下继续付款 | 

### 禁用自动付款
<a name="payments-framework-langgraph-auto-payment"></a>

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

```
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 个响应，从而允许在付款前自定义逻辑或人工批准。

### 支付工具许可名单
<a name="payments-framework-langgraph-allowlist"></a>

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

```
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"],
)
```

只有来自许可名单中工具的工具调用才会触发自动付款处理。来自其他工具的工具调用不会被拦截付款。

### 网络首选项
<a name="payments-framework-langgraph-network"></a>

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

```
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），以降低交易费用。

### 配置选项
<a name="payments-framework-langgraph-config"></a>

下表列出了`AgentCorePaymentsConfig`参数：


| 参数 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `payment_manager_arn`  |  `str`  | 是 | 基岩 AgentCore 支付管理器资源的 ARN | 
|  `user_id`  |  `str`  | 是 | 用户的唯一标识符 | 
|  `payment_instrument_id`  |  `Optional[str]`  | 否 | 付款工具编号 | 
|  `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 代理工具
<a name="payments-framework-langgraph-tools"></a>

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


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

### 同步与异步
<a name="payments-framework-langgraph-async"></a>

 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。