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 :

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 :

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 :

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 :

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 :

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

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 AgentCorePaymentsConfig paramètres :

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 :

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.