Integraciones de marcos para pagos AgentCore

AgentCore payments se integra 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: Plugin-based integración mediante ganchos

• LangGraph— Middleware-based integración que agrupa las llamadas a las herramientas

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

Gestionar las interrupciones de pago

Cuando se produce un error en el procesamiento de pagos, el complemento guarda el error y provoca 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 una 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 de cadena de bloques 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 utiliza un orden de preferencia predeterminado que da prioridad a la red principal de Solana y a Base (Ethereum L2) a cambio de tarifas de transacción bajas.

Opciones de configuración

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

Parámetro	Tipo	Obligatorio	Descripción
payment_manager_arn	str	Sí	ARN del recurso Bedrock Payment Manager AgentCore
user_id	str	Sí	Identificador único del usuario
payment_instrument_id	Optional[str]	No	ID del instrumento de pago. Se puede configurar más adelante mediante update_payment_instrument_id()
payment_session_id	Optional[str]	No	ID de sesión de pago. Se puede configurar más adelante mediante update_payment_session_id()
region	Optional[str]	No	AWS región para el administrador de pagos
network_preferences_config	Optional[list[str]]	No	Lista de CAIP-2 identificadores de red por orden de preferencia
auto_payment	bool	No (valor predeterminado: True)	Si se deben procesar automáticamente 402 requisitos de pago
max_interrupt_retries	int	No (valor predeterminado: 5)	Interrupción máxima de reintentos por uso de la herramienta. Configúrelo en 0 para deshabilitar las interrupciones
agent_name	Optional[str]	No	El nombre del agente se propaga mediante el encabezado HTTP en las llamadas a la API

Built-in herramientas de agente

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

Herramienta	Description (Descripción)
get_payment_instrument	Recupera detalles sobre un instrumento de pago específico
list_payment_instruments	Enumere todos los instrumentos de pago de un usuario
get_payment_session	Recupera los detalles de una sesión de pago (presupuesto, estado, caducidad)

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, consulta 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 a las herramientas y gestiona el flujo de pagos x402 en seis pasos:

1. El agente realiza una llamada a una herramienta que da como resultado una solicitud HTTP a un punto final de pago.

2. El terminal responde con el protocolo HTTP 402: Se requiere el pago y una carga útil de pago x402.

3. El middleware intercepta la respuesta 402 y extrae los requisitos de pago.

4. El middleware llama ProcessPayment al instrumento de pago y a la sesión para generar una prueba criptográfica.

5. El middleware vuelve a intentar la solicitud original con el encabezado del comprobante de pago adjunto.

6. El punto final valida la prueba y devuelve el contenido solicitado al agente.

Gestión de errores con devoluciones de llamada

Utiliza la función de on_payment_error devolución de llamada para gestionar los impagos sin problemas:

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:

Valor	Comportamiento
RETRY	Vuelva a intentar el pago con la configuración actual
STOP	Detenga el procesamiento y devuelva el error al agente
SKIP	Omite el pago y continúa sin el contenido de pago

Desactivar el pago automático

Para deshabilitar 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
)

Cuando auto_payment es asíFalse, el middleware envía 402 respuestas al agente sin procesarlas, lo que permite una 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 permitidos activan el procesamiento automático de los pagos. Las llamadas de herramientas desde otras herramientas se transmiten sin que se intercepte el pago.

Preferencias de red

Puedes especificar las redes de cadena de bloques 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 utiliza un orden de preferencia predeterminado que da prioridad a la red principal de Solana y a Base (Ethereum L2) a cambio de tarifas de transacción bajas.

Opciones de configuración

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

Parámetro	Tipo	Obligatorio	Descripción
payment_manager_arn	str	Sí	ARN del recurso Bedrock Payment Manager AgentCore
user_id	str	Sí	Identificador único del usuario
payment_instrument_id	Optional[str]	No	ID del instrumento de pago
payment_session_id	Optional[str]	No	ID de sesión de pago. No es obligatorio cuando auto_session es True
region	Optional[str]	No	AWS región del administrador de pagos
auto_session	bool	No (valor predeterminado: False)	Crea o reutiliza automáticamente una sesión de pago
auto_session_expiry_minutes	int	No (valor predeterminado: 60)	Tiempo de caducidad de las sesiones creadas automáticamente en minutos
auto_session_max_spend	str	No (valor predeterminado: "5.00")	Importe máximo de gasto para sesiones creadas automáticamente
auto_session_currency	str	No (valor predeterminado: "USD")	Moneda para los límites de gasto de sesión creados automáticamente
auto_payment	bool	No (valor predeterminado: True)	Si se deben procesar automáticamente 402 requisitos de pago
network_preferences_config	Optional[list[str]]	No	Lista de CAIP-2 identificadores de red por orden de preferencia
tool_allowlist	Optional[list[str]]	No	Lista de nombres de herramientas que pueden activar pagos automáticos. Si no se establece, todas las herramientas pueden activar los pagos
max_retries	int	No (valor predeterminado: 3)	Número máximo de reintentos de pago por llamada a la herramienta
on_payment_error	Optional[Callable]	No	Se invoca la función de devolución de llamada en caso de impago
on_payment_success	Optional[Callable]	No	La función de devolución de llamada se invoca cuando el pago se realiza correctamente
on_payment_start	Optional[Callable]	No	La función de devolución de llamada se invoca antes de que comience el procesamiento del pago
agent_name	Optional[str]	No	El nombre del agente se propaga mediante un encabezado HTTP en las llamadas a la API
endpoint_url	Optional[str]	No	URL de punto final personalizada para el servicio de AgentCore pagos

Built-in herramientas para agentes

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

Herramienta	Description (Descripción)
get_payment_instrument	Recupera detalles sobre un instrumento de pago específico
list_payment_instruments	Enumere todos los instrumentos de pago de un usuario
get_payment_session	Recupera los detalles de una sesión de pago (presupuesto, estado, caducidad)
get_payment_balance	Recupera el saldo actual de un instrumento de pago
list_payment_sessions	Enumere todas las sesiones de pago de un usuario

Sincronización frente a asíncrona

El LangGraph middleware admite la ejecución sincrónica y asíncrona:

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 el mismo comportamiento de procesamiento de pagos. Utilice async cuando se integre con marcos asíncronos o cuando gestione varios agentes simultáneos.