Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Intégrations de cadres pour les paiements AgentCore

AgentCore payments s'intègre aux frameworks d'agents les plus populaires pour fournir un traitement automatisé des paiements. Chaque framework utilise un modèle d'intégration différent :

Strands Agents

Le plugin de AgentCore paiement fournit un traitement automatique des paiements pour Strands Agents. Il prend en charge le protocole x402 Payment Required, permettant aux agents de gérer automatiquement les réponses HTTP 402.

Installation

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

Configurer et utiliser le 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")

Gestion des interruptions de paiement

Lorsque le traitement du paiement échoue, le plugin enregistre l'échec et déclenche une interruption. Votre application doit gérer les interruptions suivantes :

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)

Désactiver le paiement automatique

Pour accéder uniquement aux outils de visibilité des paiements sans exécution automatique des paiements (par exemple, pour maintenir une logique humaine ou personnalisée au courant avant toute transaction de paiement), désactivez le traitement automatique :

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
)

Préférences réseau

Vous pouvez spécifier les réseaux blockchain préférés pour le traitement des paiements :

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"],
)

Si cela n'est pas spécifié, le système utilise un ordre de préférence par défaut donnant la priorité au réseau principal Solana et à Base (Ethereum L2) pour des frais de transaction peu élevés.

Options de configuration

Le tableau suivant répertorie les AgentCorePaymentsPluginConfig paramètres :

Built-in outils d'agent

Le plugin enregistre trois outils que les agents peuvent utiliser pour interroger les informations de paiement lors de l'exécution :

Ces outils permettent aux agents de prendre des décisions éclairées concernant les méthodes de paiement et les limites de paiement lors des conversations. Pour plus de détails et des exemples complets, consultez la documentation Strands Agents.

LangGraph

L'intergiciel de AgentCore paiement permet le traitement automatique des paiements pour les LangGraph agents. Il prend en charge le protocole x402 Payment Required, permettant aux agents de gérer automatiquement les réponses HTTP 402.

Installation

pip install 'bedrock-agentcore[langgraph]'

Configuration et utilisation du 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)

Comment fonctionne le middleware

Le middleware intercepte les appels aux outils et gère le flux de paiement x402 en six étapes :

Gestion des erreurs avec les callbacks

Utilisez le on_payment_error rappel pour gérer les échecs de paiement avec élégance :

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énumération fournit les options suivantes :

Désactiver le paiement automatique

Pour désactiver le traitement automatique des paiements et demander une approbation explicite des paiements, procédez comme suit :

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
)

Lorsque auto_payment c'est le casFalse, le middleware envoie 402 réponses à l'agent sans les traiter, ce qui permet une logique personnalisée ou une approbation humaine avant le paiement.

Liste des outils de paiement autorisés

Restreignez les outils qui peuvent déclencher des paiements automatiques :

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"],
)

Seuls les appels d'outils provenant des outils de la liste autorisée déclenchent le traitement automatique des paiements. Les appels d'outils provenant d'autres outils sont transmis sans interception de paiement.

Préférences réseau

Vous pouvez spécifier les réseaux blockchain préférés pour le traitement des paiements :

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"],
)

Si cela n'est pas spécifié, le système utilise un ordre de préférence par défaut donnant la priorité au réseau principal Solana et à Base (Ethereum L2) pour des frais de transaction peu élevés.

Options de configuration

Le tableau suivant répertorie les AgentCorePaymentsConfig paramètres :

Built-in outils d'agent

L'intergiciel enregistre cinq outils que les agents peuvent utiliser pour interroger et gérer les informations de paiement au moment de l'exécution :

Synchronisation ou asynchronisation

Le LangGraph middleware prend en charge l'exécution synchrone et asynchrone :

Synchrone :

result = agent.invoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})

Asynchrone :

result = await agent.ainvoke({"messages": [{"role": "user", "content": "access the paid endpoint"}]})

Les deux modes prennent en charge les mêmes options de configuration et le même comportement de traitement des paiements. Utilisez async lors de l'intégration à des frameworks asynchrones ou lors de la gestion de plusieurs agents simultanés.