# Integrazioni di framework per i pagamenti AgentCore
AgentCore payments si integra con i più diffusi framework di agenti per fornire un'elaborazione automatizzata dei pagamenti. Ogni framework utilizza un modello di integrazione diverso:
+ **[Strands Agents](#payments-framework-strands)**: Plugin-based integrazione tramite hook
+ **[LangGraph](#payments-framework-langgraph)**— Middleware-based integrazione che racchiude le chiamate agli strumenti
## Agenti Strands
Il plug-in per AgentCore i pagamenti fornisce l'elaborazione automatizzata dei pagamenti per Strands Agents. Supporta il protocollo [x402 Payment Required](https://www.x402.org/), che consente agli agenti di gestire automaticamente le risposte HTTP 402.
### Installazione
```
pip install 'bedrock-agentcore[strands-agents]'
```
### Configura e usa il 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")
```
### Gestione delle interruzioni di pagamento
Quando l'elaborazione del pagamento fallisce, il plugin memorizza l'errore e genera un'interruzione. L'applicazione dovrebbe gestire queste interruzioni:
```
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)
```
### Disabilitazione del pagamento automatico
Per accedere solo agli strumenti di visibilità dei pagamenti senza esecuzione automatica dei pagamenti (ad esempio, per mantenere attiva una logica umana o personalizzata prima di qualsiasi transazione di pagamento), disattiva l'elaborazione automatica:
```
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
)
```
### Preferenze di rete
Puoi specificare le reti blockchain preferite per l'elaborazione dei pagamenti:
```
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"],
)
```
Se non specificato, il sistema utilizza un ordine di preferenza predefinito che dà la priorità alla mainnet e alla base di Solana (Ethereum L2) per commissioni di transazione basse.
### Opzioni di configurazione
La tabella seguente elenca i parametri: `AgentCorePaymentsPluginConfig`
| Parametro | Tipo | Campo obbligatorio | Descrizione |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Sì | ARN della risorsa Bedrock Payment Manager AgentCore |
| `user_id` | `str` | Sì | Identificatore univoco per l'utente |
| `payment_instrument_id` | `Optional[str]` | No | ID dello strumento di pagamento. Può essere impostato in un secondo momento tramite `update_payment_instrument_id()` |
| `payment_session_id` | `Optional[str]` | No | ID della sessione di pagamento. Può essere impostato in un secondo momento tramite `update_payment_session_id()` |
| `region` | `Optional[str]` | No | AWS regione per il gestore dei pagamenti |
| `network_preferences_config` | `Optional[list[str]]` | No | Elenco degli CAIP-2 identificatori di rete in ordine di preferenza |
| `auto_payment` | `bool` | No (impostazione predefinita:`True`) | Se elaborare automaticamente 402 requisiti di pagamento |
| `max_interrupt_retries` | `int` | No (impostazione predefinita:`5`) | Numero massimo di tentativi di interruzione per utilizzo dello strumento. Impostare su 0 per disabilitare le interruzioni |
| `agent_name` | `Optional[str]` | No | Nome dell'agente propagato tramite l'intestazione HTTP nelle chiamate API |
### Built-in strumenti per agenti
Il plugin registra tre strumenti che gli agenti possono utilizzare per interrogare le informazioni di pagamento in fase di esecuzione:
| Strumento | Description |
| --- | --- |
| `get_payment_instrument` | Recupera i dettagli su uno strumento di pagamento specifico |
| `list_payment_instruments` | Elenca tutti gli strumenti di pagamento per un utente |
| `get_payment_session` | Recupera i dettagli su una sessione di pagamento (budget, stato, scadenza) |
Questi strumenti consentono agli agenti di prendere decisioni informate sui metodi di pagamento e sui limiti di pagamento durante le conversazioni. Per maggiori dettagli ed esempi completi, consulta la documentazione di [Strands](https://strandsagents.com/latest/) Agents.
## LangGraph
Il middleware per AgentCore i pagamenti fornisce l'elaborazione automatizzata dei pagamenti per gli agenti. LangGraph Supporta il protocollo [x402 Payment Required](https://www.x402.org/), che consente agli agenti di gestire automaticamente le risposte HTTP 402.
### Installazione
```
pip install 'bedrock-agentcore[langgraph]'
```
### Configura e usa il 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)
```
### Come funziona il middleware
Il middleware intercetta le chiamate allo strumento e gestisce il flusso di pagamento x402 in sei passaggi:
1. L'agente effettua una chiamata allo strumento che genera una richiesta HTTP a un endpoint a pagamento.
1. L'endpoint risponde con HTTP 402 Payment Required e un payload di pagamento x402.
1. Il middleware intercetta la risposta 402 ed estrae i requisiti di pagamento.
1. Il middleware chiama lo strumento di pagamento e la sessione per `ProcessPayment` generare una prova crittografica.
1. Il middleware riprova la richiesta originale con l'intestazione della prova di pagamento allegata.
1. L'endpoint convalida la prova e restituisce il contenuto richiesto all'agente.
### Gestione degli errori con i callback
Usa il `on_payment_error` callback per gestire con garbo gli errori di pagamento:
```
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,
)
```
L'`ErrorResolution`enum fornisce le seguenti opzioni:
| Valore | Comportamento |
| --- | --- |
| `RETRY` | Riprova il pagamento con la configurazione corrente |
| `STOP` | Interrompi l'elaborazione e restituisci l'errore all'agente |
| `SKIP` | Salta il pagamento e continua senza i contenuti a pagamento |
### Disabilitazione del pagamento automatico
Per disabilitare l'elaborazione automatica dei pagamenti e richiedere l'approvazione esplicita del pagamento:
```
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
)
```
In `auto_payment` tal caso`False`, il middleware invia 402 risposte all'agente senza elaborarle, consentendo una logica personalizzata o l'approvazione umana prima del pagamento.
### Elenco degli strumenti di pagamento consentiti
Limita gli strumenti che possono attivare pagamenti automatici:
```
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"],
)
```
Solo le chiamate agli strumenti dagli strumenti nella lista consentita attivano l'elaborazione automatica dei pagamenti. Le chiamate agli strumenti provenienti da altri strumenti passano senza intercettazione dei pagamenti.
### Preferenze di rete
Puoi specificare le reti blockchain preferite per l'elaborazione dei pagamenti:
```
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"],
)
```
Se non specificato, il sistema utilizza un ordine di preferenza predefinito che dà la priorità alla mainnet e alla base di Solana (Ethereum L2) per commissioni di transazione basse.
### Opzioni di configurazione
La tabella seguente elenca i parametri: `AgentCorePaymentsConfig`
| Parametro | Tipo | Campo obbligatorio | Descrizione |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Sì | ARN della risorsa Bedrock Payment Manager AgentCore |
| `user_id` | `str` | Sì | Identificatore univoco per l'utente |
| `payment_instrument_id` | `Optional[str]` | No | ID dello strumento di pagamento |
| `payment_session_id` | `Optional[str]` | No | ID della sessione di pagamento. Non richiesto quando `auto_session` è `True` |
| `region` | `Optional[str]` | No | AWS regione per il gestore dei pagamenti |
| `auto_session` | `bool` | No (impostazione predefinita:`False`) | Crea o riutilizza automaticamente una sessione di pagamento |
| `auto_session_expiry_minutes` | `int` | No (impostazione predefinita:`60`) | Tempo di scadenza per le sessioni create automaticamente in minuti |
| `auto_session_max_spend` | `str` | No (impostazione predefinita:) `"5.00"` | Importo massimo di spesa per le sessioni create automaticamente |
| `auto_session_currency` | `str` | No (impostazione predefinita:`"USD"`) | Valuta per i limiti di spesa delle sessioni creati automaticamente |
| `auto_payment` | `bool` | No (impostazione predefinita:`True`) | Se elaborare automaticamente 402 requisiti di pagamento |
| `network_preferences_config` | `Optional[list[str]]` | No | Elenco degli CAIP-2 identificatori di rete in ordine di preferenza |
| `tool_allowlist` | `Optional[list[str]]` | No | Elenco dei nomi degli strumenti che possono attivare pagamenti automatici. Se non è impostato, tutti gli strumenti possono attivare i pagamenti |
| `max_retries` | `int` | No (impostazione predefinita:`3`) | Numero massimo di nuovi tentativi di pagamento per chiamata allo strumento |
| `on_payment_error` | `Optional[Callable]` | No | Funzione di callback richiamata in caso di mancato pagamento |
| `on_payment_success` | `Optional[Callable]` | No | Funzione di callback richiamata in caso di pagamento riuscito |
| `on_payment_start` | `Optional[Callable]` | No | Funzione di callback richiamata prima dell'inizio dell'elaborazione del pagamento |
| `agent_name` | `Optional[str]` | No | Nome dell'agente propagato tramite l'intestazione HTTP nelle chiamate API |
| `endpoint_url` | `Optional[str]` | No | URL endpoint personalizzato per il servizio di pagamento AgentCore |
### Built-in strumenti per agenti
Il middleware registra cinque strumenti che gli agenti possono utilizzare per interrogare e gestire le informazioni di pagamento in fase di esecuzione:
| Strumento | Description |
| --- | --- |
| `get_payment_instrument` | Recupera i dettagli su uno strumento di pagamento specifico |
| `list_payment_instruments` | Elenca tutti gli strumenti di pagamento per un utente |
| `get_payment_session` | Recupera i dettagli su una sessione di pagamento (budget, stato, scadenza) |
| `get_payment_balance` | Recupera il saldo corrente di uno strumento di pagamento |
| `list_payment_sessions` | Elenca tutte le sessioni di pagamento per un utente |
### Sincronizzazione vs asincrona
Il LangGraph middleware supporta l'esecuzione sia sincrona che asincrona:
**Sincrono:**
```
result = agent.invoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})
```
**Asincrono:**
```
result = await agent.ainvoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})
```
Entrambe le modalità supportano le stesse opzioni di configurazione e lo stesso comportamento di elaborazione dei pagamenti. Usa async durante l'integrazione con framework asincroni o quando gestisci più agenti simultanei.