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: Plugin-based integrazione tramite hook
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, 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 Agents.

LangGraph

Il middleware per AgentCore i pagamenti fornisce l'elaborazione automatizzata dei pagamenti per gli agenti. LangGraph Supporta il protocollo x402 Payment Required, 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:

L'agente effettua una chiamata allo strumento che genera una richiesta HTTP a un endpoint a pagamento.
L'endpoint risponde con HTTP 402 Payment Required e un payload di pagamento x402.
Il middleware intercetta la risposta 402 ed estrae i requisiti di pagamento.
Il middleware chiama lo strumento di pagamento e la sessione per ProcessPayment generare una prova crittografica.
Il middleware riprova la richiesta originale con l'intestazione della prova di pagamento allegata.
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'ErrorResolutionenum 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 casoFalse, 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.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Elabora il pagamento

Osservabilità