# 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 Agents](#payments-framework-strands)** — Plugin-based Integration mithilfe von Hooks
+ **[LangGraph](#payments-framework-langgraph)**— Middleware-based Integration, die Tool-Aufrufe umschließt
## Strands, Agenten
Das AgentCore Zahlungs-Plugin bietet eine automatisierte Zahlungsabwicklung für Strands Agents. Es unterstützt das Protokoll [x402 Payment Required](https://www.x402.org/), 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`
| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Ja | ARN der Bedrock AgentCore Payment Manager-Ressource |
| `user_id` | `str` | Ja | Eindeutige Kennung für den Benutzer |
| `payment_instrument_id` | `Optional[str]` | Nein | ID des Zahlungsinstruments. Kann später eingestellt werden über `update_payment_instrument_id()` |
| `payment_session_id` | `Optional[str]` | Nein | ID der Zahlungssitzung. Kann später eingestellt werden über `update_payment_session_id()` |
| `region` | `Optional[str]` | Nein | AWS Region für den Zahlungsmanager |
| `network_preferences_config` | `Optional[list[str]]` | Nein | Liste der CAIP-2 Netzwerkkennungen in der Reihenfolge ihrer Präferenz |
| `auto_payment` | `bool` | Nein (Standard:`True`) | Ob 402-Zahlungsanforderungen automatisch verarbeitet werden sollen |
| `max_interrupt_retries` | `int` | Nein (Standard:`5`) | Maximale Anzahl von Interrupt-Wiederholungen pro verwendetem Tool. Auf 0 setzen, um Interrupts zu deaktivieren |
| `agent_name` | `Optional[str]` | Nein | Agentenname, der bei API-Aufrufen über den HTTP-Header weitergegeben wird |
### Built-in Agententools
Das Plugin registriert drei Tools, mit denen Agenten Zahlungsinformationen zur Laufzeit abfragen können:
| Tool | Description |
| --- | --- |
| `get_payment_instrument` | Rufen Sie Details zu einem bestimmten Zahlungsinstrument ab |
| `list_payment_instruments` | Listet alle Zahlungsinstrumente für einen Benutzer auf |
| `get_payment_session` | Rufen Sie Details zu einer Zahlungssitzung ab (Budget, Status, Ablauf) |
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](https://strandsagents.com/latest/).
## LangGraph
Die AgentCore Zahlungs-Middleware bietet eine automatisierte Zahlungsabwicklung für LangGraph Agenten. Sie unterstützt das Protokoll [x402 Payment Required](https://www.x402.org/), 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:
1. Der Agent führt einen Tool-Aufruf durch, der zu einer HTTP-Anfrage an einen kostenpflichtigen Endpunkt führt.
1. Der Endpunkt antwortet mit HTTP 402 Payload Required und einer Payload für x402-Zahlungen.
1. Die Middleware fängt die 402-Antwort ab und extrahiert die Zahlungsanforderungen.
1. Die Middleware ruft `ProcessPayment` das Zahlungsinstrument und die Sitzung an, um einen kryptografischen Nachweis zu generieren.
1. Die Middleware wiederholt die ursprüngliche Anfrage mit dem angehängten Header für den Zahlungsnachweis.
1. Der Endpunkt validiert den Nachweis und sendet den angeforderten Inhalt an den Agenten zurück.
### 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:
| Wert | Behavior |
| --- | --- |
| `RETRY` | Versuchen Sie die Zahlung mit der aktuellen Konfiguration erneut |
| `STOP` | Beenden Sie die Verarbeitung und geben Sie den Fehler an den Agenten zurück |
| `SKIP` | Überspringen Sie die Zahlung und fahren Sie ohne den kostenpflichtigen Inhalt fort |
### 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`
| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Ja | ARN der Bedrock AgentCore Payment Manager-Ressource |
| `user_id` | `str` | Ja | Eindeutige Kennung für den Benutzer |
| `payment_instrument_id` | `Optional[str]` | Nein | ID des Zahlungsinstruments |
| `payment_session_id` | `Optional[str]` | Nein | ID der Zahlungssitzung. Nicht erforderlich, wann `auto_session` ist `True` |
| `region` | `Optional[str]` | Nein | AWS Region für den Zahlungsmanager |
| `auto_session` | `bool` | Nein (Standard:`False`) | Automatisch eine Zahlungssitzung erstellen oder wiederverwenden |
| `auto_session_expiry_minutes` | `int` | Nein (Standard:`60`) | Ablaufzeit für automatisch erstellte Sitzungen in Minuten |
| `auto_session_max_spend` | `str` | Nein (Standard:`"5.00"`) | Maximaler Ausgabenbetrag für automatisch erstellte Sitzungen |
| `auto_session_currency` | `str` | Nein (Standard:`"USD"`) | Währung für Ausgabenlimits für automatisch erstellte Sitzungen |
| `auto_payment` | `bool` | Nein (Standard:`True`) | Ob 402-Zahlungsanforderungen automatisch verarbeitet werden sollen |
| `network_preferences_config` | `Optional[list[str]]` | Nein | Liste der CAIP-2 Netzwerkkennungen in der Reihenfolge ihrer Präferenz |
| `tool_allowlist` | `Optional[list[str]]` | Nein | Liste der Toolnamen, die automatische Zahlungen auslösen können. Wenn nicht gesetzt, können alle Tools Zahlungen auslösen |
| `max_retries` | `int` | Nein (Standard:`3`) | Maximale Anzahl von Zahlungswiederholungen pro Tool-Aufruf |
| `on_payment_error` | `Optional[Callable]` | Nein | Bei fehlgeschlagener Zahlung wird die Rückruffunktion aufgerufen |
| `on_payment_success` | `Optional[Callable]` | Nein | Die Rückruffunktion wurde bei erfolgreicher Zahlung aufgerufen |
| `on_payment_start` | `Optional[Callable]` | Nein | Die Rückruffunktion wird aufgerufen, bevor die Zahlungsabwicklung beginnt |
| `agent_name` | `Optional[str]` | Nein | Agentenname, der bei API-Aufrufen über den HTTP-Header weitergegeben wird |
| `endpoint_url` | `Optional[str]` | Nein | Benutzerdefinierte Endpunkt-URL für den AgentCore Zahlungsdienst |
### Built-in Tools für Agenten
Die Middleware registriert fünf Tools, mit denen Agenten Zahlungsinformationen zur Laufzeit abfragen und verwalten können:
| Tool | Description |
| --- | --- |
| `get_payment_instrument` | Rufen Sie Details zu einem bestimmten Zahlungsinstrument ab |
| `list_payment_instruments` | Listet alle Zahlungsinstrumente für einen Benutzer auf |
| `get_payment_session` | Rufen Sie Details zu einer Zahlungssitzung ab (Budget, Status, Ablauf) |
| `get_payment_balance` | Rufen Sie den aktuellen Saldo eines Zahlungsinstruments ab |
| `list_payment_sessions` | Listet alle Zahlungssitzungen für einen Benutzer auf |
### 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.