Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Integrasi kerangka kerja untuk pembayaran AgentCore

AgentCore pembayaran terintegrasi dengan kerangka agen populer untuk menyediakan pemrosesan pembayaran otomatis. Setiap kerangka kerja menggunakan pola integrasi yang berbeda:

Agen Helai

Plugin AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk Strands Agents. Ini mendukung protokol X402 Payment Required, memungkinkan agen untuk secara otomatis menangani tanggapan HTTP 402.

Penginstalan

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

Konfigurasikan dan gunakan plugin

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

Menangani gangguan pembayaran

Ketika pemrosesan pembayaran gagal, plugin menyimpan kegagalan dan menimbulkan interupsi. Aplikasi Anda harus menangani interupsi ini:

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)

Menonaktifkan pembayaran otomatis

Untuk mengakses hanya alat visibilitas pembayaran tanpa eksekusi pembayaran otomatis (misalnya, untuk menjaga logika manusia atau kustom tetap dalam loop sebelum transaksi pembayaran apa pun), nonaktifkan pemrosesan otomatis:

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
)

Preferensi jaringan

Anda dapat menentukan jaringan blockchain pilihan untuk pemrosesan pembayaran:

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

Jika tidak ditentukan, sistem menggunakan urutan preferensi default yang memprioritaskan mainnet Solana dan Base (Ethereum L2) untuk biaya transaksi yang rendah.

Opsi konfigurasi

Tabel berikut mencantumkan AgentCorePaymentsPluginConfig parameter:

Built-in alat agen

Plugin mendaftarkan tiga alat yang dapat digunakan agen untuk menanyakan informasi pembayaran saat runtime:

Alat ini memungkinkan agen untuk membuat keputusan berdasarkan informasi tentang metode pembayaran dan batas pembayaran selama percakapan. Untuk detail lebih lanjut dan contoh ujung ke ujung, lihat dokumentasi Strands Agents.

LangGraph

Middleware AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk LangGraph agen. Ini mendukung protokol X402 Payment Required, memungkinkan agen untuk secara otomatis menangani tanggapan HTTP 402.

Penginstalan

pip install 'bedrock-agentcore[langgraph]'

Konfigurasikan dan gunakan middleware

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)

Cara kerja middleware

Middleware mencegat panggilan alat dan menangani aliran pembayaran x402 dalam enam langkah:

Penanganan kesalahan dengan panggilan balik

Gunakan on_payment_error callback untuk menangani kegagalan pembayaran dengan anggun:

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

ErrorResolutionEnum menyediakan opsi berikut:

Menonaktifkan pembayaran otomatis

Untuk menonaktifkan pemrosesan pembayaran otomatis dan memerlukan persetujuan pembayaran eksplisit:

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
)

Ketika auto_payment ituFalse, middleware menampilkan 402 respons ke agen tanpa memprosesnya, memungkinkan logika khusus atau persetujuan manusia sebelum pembayaran.

Daftar izin alat pembayaran

Batasi alat mana yang dapat memicu pembayaran otomatis:

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

Hanya panggilan alat dari alat di allowlist yang memicu pemrosesan pembayaran otomatis. Panggilan alat dari alat lain melewati tanpa intersepsi pembayaran.

Preferensi jaringan

Anda dapat menentukan jaringan blockchain pilihan untuk pemrosesan pembayaran:

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

Jika tidak ditentukan, sistem menggunakan urutan preferensi default yang memprioritaskan mainnet Solana dan Base (Ethereum L2) untuk biaya transaksi yang rendah.

Opsi konfigurasi

Tabel berikut mencantumkan AgentCorePaymentsConfig parameter:

Built-in alat agen

Middleware mencatat lima alat yang dapat digunakan agen untuk menanyakan dan mengelola informasi pembayaran saat runtime:

Sinkronisasi vs asinkron

LangGraph Middleware mendukung eksekusi sinkron dan asinkron:

Sinkron:

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

Asinkron:

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

Kedua mode mendukung opsi konfigurasi dan perilaku pemrosesan pembayaran yang sama. Gunakan async saat mengintegrasikan dengan kerangka kerja async atau saat menangani beberapa agen bersamaan.