Integrações de estrutura para pagamentos AgentCore

AgentCore os pagamentos se integram a estruturas de agentes populares para fornecer processamento automatizado de pagamentos. Cada estrutura usa um padrão de integração diferente:

Strands Agents

O plug-in de AgentCore pagamentos fornece processamento automatizado de pagamentos para Strands Agents. Ele suporta o protocolo x402 Payment Required, permitindo que os agentes lidem automaticamente com as respostas HTTP 402.

Instalação

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

Configure e use o 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")

Lidar com interrupções de pagamento

Quando o processamento do pagamento falha, o plug-in armazena a falha e gera uma interrupção. Seu aplicativo deve lidar com essas interrupções:

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)

Desativando o pagamento automático

Para acessar somente as ferramentas de visibilidade do pagamento sem a execução automática do pagamento (por exemplo, para manter uma lógica humana ou personalizada informada antes de qualquer transação de pagamento), desative o processamento 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
)

Preferências de rede

Você pode especificar redes blockchain preferidas para processamento de pagamentos:

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

Se não for especificado, o sistema usa uma ordem de preferência padrão priorizando Solana mainnet e Base (Ethereum L2) para taxas de transação baixas.

Opções de configuração

A tabela a seguir lista os AgentCorePaymentsPluginConfig parâmetros:

Built-in ferramentas de agente

O plug-in registra três ferramentas que os agentes podem usar para consultar informações de pagamento em tempo de execução:

Essas ferramentas permitem que os agentes tomem decisões informadas sobre métodos de pagamento e limites de pagamento durante as conversas. Para obter mais detalhes e exemplos completos, consulte a documentação do Strands Agents.

LangGraph

O middleware de AgentCore pagamentos fornece processamento automatizado de pagamentos para LangGraph agentes. Ele suporta o protocolo x402 Payment Required, permitindo que os agentes lidem automaticamente com as respostas HTTP 402.

Instalação

pip install 'bedrock-agentcore[langgraph]'

Configurar e usar o 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)

Como o middleware funciona

O middleware intercepta as chamadas da ferramenta e gerencia o fluxo de pagamento x402 em seis etapas:

Tratamento de erros com retornos de chamada

Use o on_payment_error retorno de chamada para lidar com falhas de pagamento com tranquilidade:

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

A ErrorResolution enumeração fornece as seguintes opções:

Desativando o pagamento automático

Para desativar o processamento automático de pagamentos e exigir aprovação explícita do pagamento:

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
)

Quando auto_payment estáFalse, o middleware apresenta 402 respostas ao agente sem processá-las, permitindo lógica personalizada ou aprovação humana antes do pagamento.

Lista de permissões da ferramenta de pagamento

Restrinja quais ferramentas podem acionar pagamentos 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"],
)

Somente chamadas de ferramentas de ferramentas na lista de permissões acionam o processamento automático do pagamento. As chamadas de ferramentas de outras ferramentas passam sem interceptação de pagamento.

Preferências de rede

Você pode especificar redes blockchain preferidas para processamento de pagamentos:

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

Se não for especificado, o sistema usa uma ordem de preferência padrão priorizando Solana mainnet e Base (Ethereum L2) para taxas de transação baixas.

Opções de configuração

A tabela a seguir lista os AgentCorePaymentsConfig parâmetros:

Built-in ferramentas de agente

O middleware registra cinco ferramentas que os agentes podem usar para consultar e gerenciar informações de pagamento em tempo de execução:

Sincronizar versus assíncrono

O LangGraph middleware suporta execução síncrona e assíncrona:

Síncrono:

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

Assíncrono:

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

Ambos os modos oferecem suporte às mesmas opções de configuração e comportamento de processamento de pagamentos. Use assíncrono ao fazer a integração com estruturas assíncronas ou ao lidar com vários agentes simultâneos.