AgentCore 支払いのフレームワーク統合

AgentCore 支払いは、一般的なエージェントフレームワークと統合され、自動化された支払い処理を提供します。各フレームワークは、異なる統合パターンを使用します。

ストランドエージェント — フックを使用したプラグインベースの統合
LangGraph — ツール呼び出しをラップするミドルウェアベースの統合

Strands Agents

AgentCore 支払いプラグインは、Strands エージェントの自動支払い処理を提供します。x402 Payment Required プロトコルをサポートしているため、エージェントは 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 mainnet と Base (Ethereum L2) を優先するデフォルトの優先順序を使用して、トランザクション料金が低くなります。

設定オプション

次の表にAgentCorePaymentsPluginConfigパラメータを示します。

パラメータ	タイプ	必須	説明
`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`	No (default: `True`)	402 の支払い要件を自動的に処理するかどうか
`max_interrupt_retries`	`int`	No (default: `5`)	ツールの使用あたりの割り込みの最大再試行回数。割り込みを無効にするには、0 に設定します。
`agent_name`	`Optional[str]`	いいえ	API コールで HTTP ヘッダーを介して伝達されるエージェント名

組み込みエージェントツール

プラグインは、エージェントが実行時に支払い情報をクエリするために使用できる 3 つのツールを登録します。

ツール	説明
`get_payment_instrument`	特定の支払い手段に関する詳細を取得する
`list_payment_instruments`	ユーザーのすべての支払い手段を一覧表示する
`get_payment_session`	支払いセッションの詳細を取得する (予算、ステータス、有効期限)

これらのツールを使用すると、エージェントは会話中に支払い方法と支払い制限について情報に基づいた意思決定を行うことができます。詳細とend-to-endの例については、「 Strands Agents ドキュメント」を参照してください。

LangGraph

AgentCore 支払いミドルウェアは、LangGraph エージェントの自動支払い処理を提供します。x402 Payment Required プロトコルをサポートしているため、エージェントは 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 支払いフローを呼び出して 6 つのステップで処理します。

エージェントはツール呼び出しを行い、その結果、有料エンドポイントへの HTTP リクエストが発生します。
エンドポイントは HTTP 402 Payment Required と x402 Payment ペイロードで応答します。
ミドルウェアは 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 mainnet と Base (Ethereum L2) を優先するデフォルトの優先順序を使用して、トランザクション料金が低くなります。

設定オプション

次の表にAgentCorePaymentsConfigパラメータを示します。

パラメータ	タイプ	必須	説明
`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`	No (default: `False`)	支払いセッションを自動的に作成または再利用する
`auto_session_expiry_minutes`	`int`	No (default: `60`)	分単位で自動作成されたセッションの有効期限
`auto_session_max_spend`	`str`	No (default: `"5.00"`)	自動作成されたセッションの最大支出額
`auto_session_currency`	`str`	No (default: `"USD"`)	自動作成されたセッション使用制限の通貨
`auto_payment`	`bool`	No (default: `True`)	402 の支払い要件を自動的に処理するかどうか
`network_preferences_config`	`Optional[list[str]]`	いいえ	ネットワーク CAIP-2 識別子の優先順のリスト
`tool_allowlist`	`Optional[list[str]]`	いいえ	自動支払いをトリガーできるツール名のリスト。設定されていない場合、すべてのツールが支払いをトリガーできます
`max_retries`	`int`	No (default: `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

組み込みエージェントツール

ミドルウェアは、エージェントが実行時に支払い情報をクエリおよび管理するために使用できる 5 つのツールを登録します。

ツール	説明
`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 が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

支払いの処理

オブザーバビリティ