Framework-Integrationen für Zahlungen AgentCore

AgentCore Payments lässt sich in gängige Agenten-Frameworks integrieren, um eine automatisierte Zahlungsabwicklung zu ermöglichen. Jedes Framework verwendet ein anderes Integrationsmuster:

Strands, Agenten

Das AgentCore Zahlungs-Plugin bietet eine automatisierte Zahlungsabwicklung für Strands Agents. Es unterstützt das Protokoll x402 Payment Required, sodass Agenten HTTP 402-Antworten automatisch verarbeiten können.

Installation

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

Konfigurieren und verwenden Sie das 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")

Umgang mit Zahlungsunterbrechungen

Wenn die Zahlungsabwicklung fehlschlägt, speichert das Plugin den Fehler und löst einen Interrupt aus. Ihre Anwendung sollte diese Interrupts verarbeiten:

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)

Automatische Zahlung deaktivieren

Um nur auf Tools zur Sichtbarkeit von Zahlungen ohne automatische Zahlungsausführung zuzugreifen (z. B. um vor jeder Zahlungstransaktion eine menschliche oder benutzerdefinierte Logik auf dem Laufenden zu halten), deaktivieren Sie die automatische Verarbeitung:

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
)

Netzwerkeinstellungen

Sie können bevorzugte Blockchain-Netzwerke für die Zahlungsabwicklung angeben:

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

Wenn nicht angegeben, verwendet das System eine Standard-Präferenzreihenfolge, bei der Solana-Mainnet und Base (Ethereum L2) für niedrige Transaktionsgebühren Vorrang haben.

Konfigurationsoptionen

In der folgenden Tabelle sind die Parameter aufgeführt: AgentCorePaymentsPluginConfig

Built-in Agententools

Das Plugin registriert drei Tools, mit denen Agenten Zahlungsinformationen zur Laufzeit abfragen können:

Diese Tools ermöglichen es Mitarbeitern, in Gesprächen fundierte Entscheidungen über Zahlungsmethoden und Zahlungslimits zu treffen. Weitere Informationen und ausführliche Beispiele finden Sie in der Dokumentation zu Strands Agents.

LangGraph

Die AgentCore Zahlungs-Middleware bietet eine automatisierte Zahlungsabwicklung für LangGraph Agenten. Sie unterstützt das Protokoll x402 Payment Required, sodass Agenten HTTP 402-Antworten automatisch verarbeiten können.

Installation

pip install 'bedrock-agentcore[langgraph]'

Konfigurieren und verwenden Sie die 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)

Wie funktioniert die Middleware

Die Middleware fängt Tool-Aufrufe ab und wickelt den x402-Zahlungsfluss in sechs Schritten ab:

Fehlerbehandlung bei Rückrufen

Verwenden Sie den on_payment_error Rückruf, um Zahlungsausfälle ordnungsgemäß zu behandeln:

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

Die ErrorResolution Aufzählung bietet die folgenden Optionen:

Automatische Zahlung deaktivieren

Um die automatische Zahlungsabwicklung zu deaktivieren und eine ausdrückliche Zahlungsgenehmigung zu verlangen:

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
)

Wenn dies der False Fall auto_payment ist, sendet die Middleware 402 Antworten an den Agenten, ohne sie zu verarbeiten. Dies ermöglicht eine benutzerdefinierte Logik oder die Genehmigung durch einen Mitarbeiter vor der Zahlung.

Zulassungsliste für Zahlungstools

Schränken Sie ein, welche Tools automatische Zahlungen auslösen können:

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

Nur Tool-Aufrufe von Tools auf der Zulassungsliste lösen eine automatische Zahlungsabwicklung aus. Werkzeuganrufe von anderen Tools werden ohne Abfangen von Zahlungen weitergeleitet.

Netzwerkeinstellungen

Sie können bevorzugte Blockchain-Netzwerke für die Zahlungsabwicklung angeben:

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

Wenn nicht angegeben, verwendet das System eine Standard-Präferenzreihenfolge, bei der Solana-Mainnet und Base (Ethereum L2) für niedrige Transaktionsgebühren Vorrang haben.

Konfigurationsoptionen

In der folgenden Tabelle sind die Parameter aufgeführt: AgentCorePaymentsConfig

Built-in Tools für Agenten

Die Middleware registriert fünf Tools, mit denen Agenten Zahlungsinformationen zur Laufzeit abfragen und verwalten können:

Synchronisieren oder Asynchron

Die LangGraph Middleware unterstützt sowohl synchrone als auch asynchrone Ausführung:

Synchron:

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

Asynchron:

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

Beide Modi unterstützen dieselben Konfigurationsoptionen und dasselbe Zahlungsverarbeitungsverhalten. Verwenden Sie Async bei der Integration mit asynchronen Frameworks oder beim Umgang mit mehreren gleichzeitigen Agenten.