# AgentCore 付款的架構整合
<a name="payments-framework-integrations"></a>

AgentCore 付款與熱門的代理程式架構整合，以提供自動化付款處理。每個架構使用不同的整合模式：
+  ** [Strands Agents](#payments-framework-strands) ** — 使用勾點進行 以外掛程式為基礎的整合
+  ** [LangGraph](#payments-framework-langgraph)** ：包裝工具呼叫的 中介軟體型整合

## Strands 代理程式
<a name="payments-framework-strands"></a>

AgentCore 付款外掛程式為 Strands Agents 提供自動付款處理。它支援 [x402 Payment Required](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 mainnet 和 Base (Ethereum L2) 為優先順序的預設偏好設定順序。

### 組態選項
<a name="payments-framework-strands-config"></a>

下表列出`AgentCorePaymentsPluginConfig`參數：


| 參數 | Type | 必要 | 描述 | 
| --- | --- | --- | --- | 
|  `payment_manager_arn`  |  `str`  | 是 | Bedrock AgentCore Payment Manager 資源的 ARN | 
|  `user_id`  |  `str`  | 是 | 使用者的唯一識別符 | 
|  `payment_instrument_id`  |  `Optional[str]`  | 否 | 付款工具 ID。稍後可以透過 設定 `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 標頭傳播的代理程式名稱 | 

### 內建代理程式工具
<a name="payments-framework-strands-tools"></a>

外掛程式會註冊三種工具，客服人員可以用來在執行時間查詢付款資訊：


| 工具 | 說明 | 
| --- | --- | 
|  `get_payment_instrument`  | 擷取特定付款工具的詳細資訊 | 
|  `list_payment_instruments`  | 列出使用者的所有付款工具 | 
|  `get_payment_session`  | 擷取付款工作階段的詳細資訊 （預算、狀態、到期） | 

這些工具可讓客服人員在對話期間做出有關付款方式和付款限制的明智決策。如需詳細資訊和end-to-end範例，請參閱 [Strands Agents](https://strandsagents.com/latest/) 文件。



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

AgentCore 付款中介軟體可為 LangGraph 代理程式提供自動付款處理。它支援 [x402 Payment Required](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` 列舉提供下列選項：


| Value | Behavior (行為) | 
| --- | --- | 
|  `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 mainnet 和 Base (Ethereum L2) 為優先順序的預設偏好設定順序。

### 組態選項
<a name="payments-framework-langgraph-config"></a>

下表列出`AgentCorePaymentsConfig`參數：


| 參數 | Type | 必要 | 描述 | 
| --- | --- | --- | --- | 
|  `payment_manager_arn`  |  `str`  | 是 | Bedrock AgentCore Payment 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 | 

### 內建代理程式工具
<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"}]})
```

這兩種模式都支援相同的組態選項和付款處理行為。與非同步架構整合或處理多個並行代理程式時，請使用非同步。