Intégrations de cadres pour les paiements AgentCore

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

Strands Agents — Plugin-based intégration à l'aide de crochets
LangGraph— Middleware-based intégration qui permet de terminer les appels aux outils

Agents à mèches

Le plugin de AgentCore paiement fournit un traitement automatique des paiements pour Strands Agents. Il prend en charge le protocole x402 Payment Required, qui permet 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 suivre une logique humaine ou personnalisée 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 de 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 ce 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 de Solana et à la base (Ethereum L2) pour des frais de transaction peu élevés.

Options de configuration

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

Paramètre	Type	Obligatoire	Description
`payment_manager_arn`	`str`	Oui	ARN de la ressource Bedrock AgentCore Payment Manager
`user_id`	`str`	Oui	Identifiant unique pour l'utilisateur
`payment_instrument_id`	`Optional[str]`	Non	Identifiant de l'instrument de paiement. Peut être réglé ultérieurement via `update_payment_instrument_id()`
`payment_session_id`	`Optional[str]`	Non	ID de session de paiement. Peut être réglé ultérieurement via `update_payment_session_id()`
`region`	`Optional[str]`	Non	AWS région pour le gestionnaire de paiement
`network_preferences_config`	`Optional[list[str]]`	Non	Liste des CAIP-2 identifiants réseau par ordre de préférence
`auto_payment`	`bool`	Non (par défaut :`True`)	S'il faut traiter automatiquement 402 exigences de paiement
`max_interrupt_retries`	`int`	Non (par défaut :`5`)	Nombre maximum de tentatives d'interruption par outil utilisé. Régler sur 0 pour désactiver les interruptions
`agent_name`	`Optional[str]`	Non	Nom de l'agent propagé via un en-tête HTTP lors des appels d'API

Built-in outils d'agent

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

Outil	Description
`get_payment_instrument`	Récupérer les informations relatives à un instrument de paiement spécifique
`list_payment_instruments`	Répertorier tous les instruments de paiement pour un utilisateur
`get_payment_session`	Récupérer les détails d'une session de paiement (budget, statut, expiration)

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

LangGraph

L'intergiciel de AgentCore paiement fournit un traitement automatisé des paiements aux LangGraph agents. Il prend en charge le protocole x402 Payment Required, qui permet 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 des outils et gère le flux de paiement x402 en six étapes :

L'agent effectue un appel d'outil qui entraîne une requête HTTP vers un point de terminaison payant.
Le point de terminaison répond par HTTP 402 Payment Required et une charge utile de paiement x402.
Le middleware intercepte la réponse 402 et extrait les exigences de paiement.
Le middleware fait appel à l'instrument ProcessPayment de paiement et à la session pour générer des preuves cryptographiques.
Le middleware réessaie la demande d'origine avec l'en-tête de preuve de paiement joint.
Le point de terminaison valide la preuve et renvoie le contenu demandé à l'agent.

Gestion des erreurs avec les rappels

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'ErrorResolutionenum propose les options suivantes :

Value	Comportement
`RETRY`	Réessayer le paiement avec la configuration actuelle
`STOP`	Arrêter le traitement et renvoyer l'erreur à l'agent
`SKIP`	Ignorez le paiement et continuez sans le contenu payant

Désactiver le paiement automatique

Pour désactiver le traitement automatique des paiements et demander une approbation explicite du paiement :


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
)

Dans auto_payment ce casFalse, le middleware affiche 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

Limitez 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 d'outils figurant dans la liste d'autorisation déclenchent le traitement automatique des paiements. Les appels d'outils provenant d'autres outils sont transmis sans interception des paiements.

Préférences réseau

Vous pouvez spécifier les réseaux de 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"],
)

Options de configuration

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

Paramètre	Type	Obligatoire	Description
`payment_manager_arn`	`str`	Oui	ARN de la ressource Bedrock AgentCore Payment Manager
`user_id`	`str`	Oui	Identifiant unique pour l'utilisateur
`payment_instrument_id`	`Optional[str]`	Non	Identifiant de l'instrument de paiement
`payment_session_id`	`Optional[str]`	Non	ID de session de paiement. Non requis quand `auto_session` c'est `True`
`region`	`Optional[str]`	Non	AWS région pour le gestionnaire de paiement
`auto_session`	`bool`	Non (par défaut :`False`)	Création ou réutilisation automatique d'une session de paiement
`auto_session_expiry_minutes`	`int`	Non (par défaut :`60`)	Délai d'expiration des sessions créées automatiquement en minutes
`auto_session_max_spend`	`str`	Non (par défaut :`"5.00"`)	Montant maximal des dépenses pour les sessions créées automatiquement
`auto_session_currency`	`str`	Non (par défaut :`"USD"`)	Devise pour les limites de dépenses de session créées automatiquement
`auto_payment`	`bool`	Non (par défaut :`True`)	S'il faut traiter automatiquement 402 exigences de paiement
`network_preferences_config`	`Optional[list[str]]`	Non	Liste des CAIP-2 identifiants réseau par ordre de préférence
`tool_allowlist`	`Optional[list[str]]`	Non	Liste des noms d'outils pouvant déclencher des paiements automatiques. S'ils ne sont pas définis, tous les outils peuvent déclencher des paiements
`max_retries`	`int`	Non (par défaut :`3`)	Nombre maximum de tentatives de paiement par appel à l'outil
`on_payment_error`	`Optional[Callable]`	Non	Fonction de rappel invoquée en cas d'échec de paiement
`on_payment_success`	`Optional[Callable]`	Non	Fonction de rappel invoquée en cas de paiement réussi
`on_payment_start`	`Optional[Callable]`	Non	Fonction de rappel invoquée avant le début du traitement du paiement
`agent_name`	`Optional[str]`	Non	Nom de l'agent propagé via un en-tête HTTP lors des appels d'API
`endpoint_url`	`Optional[str]`	Non	URL de point de terminaison personnalisée pour le service de AgentCore paiement

Built-in outils d'agent

Le middleware enregistre cinq outils que les agents peuvent utiliser pour interroger et gérer les informations de paiement lors de l'exécution :

Outil	Description
`get_payment_instrument`	Récupérer les informations relatives à un instrument de paiement spécifique
`list_payment_instruments`	Répertorier tous les instruments de paiement pour un utilisateur
`get_payment_session`	Récupérer les détails d'une session de paiement (budget, statut, expiration)
`get_payment_balance`	Récupérez le solde actuel d'un instrument de paiement
`list_payment_sessions`	Répertorier toutes les sessions de paiement d'un utilisateur

Synchronisation ou asynchrone

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 l'async lors de l'intégration à des frameworks asynchrones ou lors de la gestion simultanée de plusieurs agents.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Procéder au paiement

Observabilité