Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Integraciones marco para pagos AgentCore

AgentCore Los pagos se integran con los marcos de agentes más populares para proporcionar un procesamiento de pagos automatizado. Cada marco utiliza un patrón de integración diferente:

Strands Agents

El complemento de AgentCore pagos proporciona un procesamiento de pagos automatizado para los agentes de Strands. Es compatible con el protocolo x402 Payment Required, que permite a los agentes gestionar automáticamente las respuestas HTTP 402.

Instalación

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

Configura y usa el complemento

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

Cómo gestionar las interrupciones de pago

Cuando el procesamiento del pago falla, el complemento almacena el error y genera una interrupción. Tu aplicación debería gestionar estas interrupciones:

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)

Desactivar el pago automático

Para acceder únicamente a las herramientas de visibilidad de los pagos sin la ejecución automática de los pagos (por ejemplo, para mantener al día una lógica humana o personalizada antes de realizar cualquier transacción de pago), desactiva el procesamiento automático:

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
)

Preferencias de red

Puedes especificar las redes blockchain preferidas para el procesamiento de pagos:

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 no se especifica, el sistema usa un orden de preferencias predeterminado que prioriza la red principal y la base de Solana (Ethereum L2) para obtener tarifas de transacción bajas.

Opciones de configuración

En la siguiente tabla se enumeran los parámetros: AgentCorePaymentsPluginConfig

Built-in herramientas de agente

El complemento registra tres herramientas que los agentes pueden usar para consultar la información de pago durante el tiempo de ejecución:

Estas herramientas permiten a los agentes tomar decisiones informadas sobre los métodos de pago y los límites de pago durante las conversaciones. Para obtener más detalles y ejemplos integrales, consulte la documentación de Strands Agents.

LangGraph

El middleware de AgentCore pagos proporciona un procesamiento de pagos automatizado para LangGraph los agentes. Es compatible con el protocolo x402 Payment Required, que permite a los agentes gestionar automáticamente las respuestas HTTP 402.

Instalación

pip install 'bedrock-agentcore[langgraph]'

Configure y utilice el 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)

Cómo funciona el middleware

El middleware intercepta las llamadas de la herramienta y gestiona el flujo de pagos del x402 en seis pasos:

Gestión de errores con las devoluciones de llamadas

Usa la on_payment_error devolución de llamada para gestionar correctamente los errores de pago:

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

La ErrorResolution enumeración ofrece las siguientes opciones:

Desactivar el pago automático

Para inhabilitar el procesamiento automático de pagos y solicitar la aprobación explícita del pago:

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
)

FalseEn auto_payment ese momento, el middleware envía 402 respuestas al agente sin procesarlas, lo que permite la lógica personalizada o la aprobación humana antes del pago.

Lista de herramientas de pago permitidas

Restrinja las herramientas que pueden activar los pagos automáticos:

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 las llamadas a herramientas desde las herramientas de la lista de pagos permitidos activan el procesamiento automático de los pagos. Las llamadas a herramientas desde otras herramientas se realizan sin interceptar el pago.

Preferencias de red

Puedes especificar las redes blockchain preferidas para el procesamiento de pagos:

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 no se especifica, el sistema usa un orden de preferencias predeterminado que prioriza la red principal y la base de Solana (Ethereum L2) para obtener tarifas de transacción bajas.

Opciones de configuración

En la siguiente tabla se enumeran los parámetros: AgentCorePaymentsConfig

Built-in herramientas de agente

El middleware registra cinco herramientas que los agentes pueden utilizar para consultar y gestionar la información de pago en tiempo de ejecución:

Sincronización frente a asincrónica

El LangGraph middleware admite la ejecución sincrónica y asincrónica:

Sincrónico:

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

Asincrónico:

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

Ambos modos admiten las mismas opciones de configuración y comportamiento de procesamiento de pagos. Utilice la tecnología asincrónica cuando se integre con marcos asíncronos o cuando gestione varios agentes simultáneos.