# Integrasi kerangka kerja untuk pembayaran AgentCore
<a name="payments-framework-integrations"></a>

AgentCore pembayaran terintegrasi dengan kerangka kerja agen populer untuk menyediakan pemrosesan pembayaran otomatis. Setiap framework menggunakan pola integrasi yang berbeda:
+  **[Strands Agents](#payments-framework-strands)** — Plugin-based integrasi menggunakan kait
+  **[LangGraph](#payments-framework-langgraph)**— Middleware-based integrasi yang membungkus panggilan alat

## Agen Helai
<a name="payments-framework-strands"></a>

Plugin AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk Agen Strands. Ini mendukung protokol [X402 Payment Required](https://www.x402.org/), memungkinkan agen untuk secara otomatis menangani respons HTTP 402.

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

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

### Konfigurasikan dan gunakan plugin
<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")
```

### Menangani interupsi pembayaran
<a name="payments-framework-strands-interrupts"></a>

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
<a name="payments-framework-strands-auto-payment"></a>

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
<a name="payments-framework-strands-network"></a>

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
<a name="payments-framework-strands-config"></a>

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
<a name="payments-framework-strands-tools"></a>

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](https://strandsagents.com/latest/).



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

Middleware AgentCore pembayaran menyediakan pemrosesan pembayaran otomatis untuk LangGraph agen. Ini mendukung protokol [X402 Payment Required](https://www.x402.org/), memungkinkan agen untuk secara otomatis menangani respons HTTP 402.

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

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

### Konfigurasikan dan gunakan middleware
<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)
```

### Cara kerja middleware
<a name="payments-framework-langgraph-how-it-works"></a>

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.

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

1. Middleware mencegat respons 402 dan mengekstrak persyaratan pembayaran.

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

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

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

### Penanganan kesalahan dengan callback
<a name="payments-framework-langgraph-error-handling"></a>

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

`ErrorResolution`Enum 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
<a name="payments-framework-langgraph-auto-payment"></a>

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_payment`Kapan`False`, middleware memunculkan 402 respons ke agen tanpa memprosesnya, memungkinkan logika khusus atau persetujuan manusia sebelum pembayaran.

### Daftar alat pembayaran yang diizinkan
<a name="payments-framework-langgraph-allowlist"></a>

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
<a name="payments-framework-langgraph-network"></a>

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
<a name="payments-framework-langgraph-config"></a>

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
<a name="payments-framework-langgraph-tools"></a>

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
<a name="payments-framework-langgraph-async"></a>

 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.