Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Integrazioni del framework per i pagamenti AgentCore

AgentCore payments si integra con i più diffusi framework di agenti per fornire l'elaborazione automatizzata dei pagamenti. Ogni framework utilizza un modello di integrazione diverso:

Strands Agents

Il plug-in per AgentCore i pagamenti fornisce l'elaborazione automatica dei pagamenti per gli agenti di Strands. 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 plug-in memorizza l'errore e genera un'interruzione. La tua 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)

Disattivazione del pagamento automatico

Per accedere solo agli strumenti di visibilità dei pagamenti senza l'esecuzione automatica dei pagamenti (ad esempio, per tenere traccia di una logica umana o personalizzata prima di qualsiasi transazione di pagamento), disabilita 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à priorità alla rete principale di Solana e a Base (Ethereum L2) per commissioni di transazione basse.

Opzioni di configurazione

La tabella seguente elenca i parametri: AgentCorePaymentsPluginConfig

Built-in strumenti per agenti

Il plugin registra tre strumenti che gli agenti possono utilizzare per richiedere le informazioni di pagamento in fase di esecuzione:

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 automatica 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 dello strumento e gestisce il flusso di pagamento x402 in sei fasi:

Gestione degli errori con 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:

Disattivazione del pagamento automatico

Per disattivare 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 tal caso auto_paymentFalse, il middleware trasmette 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 i 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 provenienti dagli strumenti inclusi nella lista consentita attivano l'elaborazione automatica dei pagamenti. Le chiamate agli strumenti provenienti da altri strumenti vengono effettuate 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à priorità alla rete principale di Solana e a Base (Ethereum L2) per commissioni di transazione basse.

Opzioni di configurazione

La tabella seguente elenca i parametri: AgentCorePaymentsConfig

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:

Sincronizzazione vs asincrona

Il LangGraph middleware supporta l'esecuzione sincrona e 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.