Integrasi kerangka kerja untuk pembayaran AgentCore

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

• Strands Agents — Plugin-based integrasi menggunakan kait

• LangGraph— Middleware-based integrasi yang membungkus panggilan alat

Agen Helai

Plugin AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk Agen Strands. Ini mendukung protokol X402 Payment Required, memungkinkan agen untuk secara otomatis menangani respons 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 interupsi 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 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 dan Base Solana (Ethereum L2) untuk biaya transaksi yang rendah.

Opsi konfigurasi

Tabel berikut mencantumkan AgentCorePaymentsPluginConfig parameter:

Parameter	Tipe	Diperlukan	Deskripsi
payment_manager_arn	str	Ya	ARN dari sumber daya Manajer Pembayaran Batuan Dasar AgentCore
user_id	str	Ya	Pengidentifikasi unik untuk pengguna
payment_instrument_id	Optional[str]	Tidak	ID instrumen pembayaran. Dapat diatur nanti melalui update_payment_instrument_id()
payment_session_id	Optional[str]	Tidak	ID sesi pembayaran. Dapat diatur nanti melalui update_payment_session_id()
region	Optional[str]	Tidak	AWS wilayah untuk manajer pembayaran
network_preferences_config	Optional[list[str]]	Tidak	Daftar CAIP-2 pengidentifikasi jaringan sesuai urutan preferensi
auto_payment	bool	Tidak (default:True)	Apakah akan secara otomatis memproses 402 persyaratan pembayaran
max_interrupt_retries	int	Tidak (default:5)	Percobaan ulang interupsi maksimum per penggunaan alat. Setel ke 0 untuk menonaktifkan interupsi
agent_name	Optional[str]	Tidak	Nama agen disebarkan melalui header HTTP pada panggilan API

Built-in alat agen

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

Alat	Deskripsi
get_payment_instrument	Mengambil rincian tentang instrumen pembayaran tertentu
list_payment_instruments	Daftar semua instrumen pembayaran untuk pengguna
get_payment_session	Mengambil detail tentang sesi pembayaran (anggaran, status, kedaluwarsa)

Alat-alat ini memungkinkan agen untuk membuat keputusan berdasarkan informasi tentang metode pembayaran dan batas pembayaran selama percakapan. Untuk detail selengkapnya 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 respons 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 alur pembayaran x402 dalam enam langkah:

1. Agen membuat panggilan alat yang menghasilkan permintaan HTTP ke titik akhir berbayar.

2. Titik akhir merespons dengan HTTP 402 Payment Required dan payload pembayaran x402.

3. Middleware mencegat respons 402 dan mengekstrak persyaratan pembayaran.

4. Middleware memanggil ProcessPayment dengan instrumen pembayaran dan sesi untuk menghasilkan bukti kriptografi.

5. Middleware mencoba ulang permintaan asli dengan header bukti pembayaran terlampir.

6. Titik akhir memvalidasi bukti dan mengembalikan konten yang diminta ke agen.

Penanganan kesalahan dengan callback

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:

Nilai	Perilaku
RETRY	Coba lagi pembayaran dengan konfigurasi saat ini
STOP	Hentikan pemrosesan dan kembalikan kesalahan ke agen
SKIP	Lewati pembayaran dan lanjutkan tanpa konten berbayar

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
)

auto_paymentKapanFalse, middleware memunculkan 402 respons ke agen tanpa memprosesnya, memungkinkan logika khusus atau persetujuan manusia sebelum pembayaran.

Daftar alat pembayaran yang diizinkan

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 daftar yang diizinkan 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 dan Base Solana (Ethereum L2) untuk biaya transaksi yang rendah.

Opsi konfigurasi

Tabel berikut mencantumkan AgentCorePaymentsConfig parameter:

Parameter	Tipe	Diperlukan	Deskripsi
payment_manager_arn	str	Ya	ARN dari sumber daya Manajer Pembayaran Batuan Dasar AgentCore
user_id	str	Ya	Pengidentifikasi unik untuk pengguna
payment_instrument_id	Optional[str]	Tidak	ID instrumen pembayaran
payment_session_id	Optional[str]	Tidak	ID sesi pembayaran. Tidak diperlukan kapan auto_session True
region	Optional[str]	Tidak	AWS wilayah untuk manajer pembayaran
auto_session	bool	Tidak (default:False)	Membuat atau menggunakan kembali sesi pembayaran secara otomatis
auto_session_expiry_minutes	int	Tidak (default:60)	Waktu kedaluwarsa untuk sesi yang dibuat secara otomatis dalam hitungan menit
auto_session_max_spend	str	Tidak (default:"5.00")	Jumlah pengeluaran maksimum untuk sesi yang dibuat secara otomatis
auto_session_currency	str	Tidak (default:"USD")	Mata uang untuk batas pengeluaran sesi yang dibuat secara otomatis
auto_payment	bool	Tidak (default:True)	Apakah akan secara otomatis memproses 402 persyaratan pembayaran
network_preferences_config	Optional[list[str]]	Tidak	Daftar CAIP-2 pengidentifikasi jaringan sesuai urutan preferensi
tool_allowlist	Optional[list[str]]	Tidak	Daftar nama alat yang dapat memicu pembayaran otomatis. Jika tidak diatur, semua alat dapat memicu pembayaran
max_retries	int	Tidak (default:3)	Jumlah maksimum percobaan ulang pembayaran per panggilan alat
on_payment_error	Optional[Callable]	Tidak	Fungsi callback dipanggil pada kegagalan pembayaran
on_payment_success	Optional[Callable]	Tidak	Fungsi callback dipanggil pada pembayaran yang berhasil
on_payment_start	Optional[Callable]	Tidak	Fungsi callback dipanggil sebelum proses pembayaran dimulai
agent_name	Optional[str]	Tidak	Nama agen disebarkan melalui header HTTP pada panggilan API
endpoint_url	Optional[str]	Tidak	URL endpoint kustom untuk layanan AgentCore pembayaran

Built-in alat agen

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

Alat	Deskripsi
get_payment_instrument	Mengambil rincian tentang instrumen pembayaran tertentu
list_payment_instruments	Daftar semua instrumen pembayaran untuk pengguna
get_payment_session	Mengambil detail tentang sesi pembayaran (anggaran, status, kedaluwarsa)
get_payment_balance	Mengambil saldo instrumen pembayaran saat ini
list_payment_sessions	Daftar semua sesi pembayaran untuk pengguna

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.