# 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](#payments-framework-strands)** — Plugin-based integração usando ganchos
+ **[LangGraph](#payments-framework-langgraph)**— Middleware-based integração que envolve chamadas de ferramentas
## Strands Agents
O plug-in de AgentCore pagamentos fornece processamento automatizado de pagamentos para Strands Agents. Ele suporta o protocolo [x402 Payment Required](https://www.x402.org/), 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:
| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Sim | ARN do recurso Bedrock Payment Manager AgentCore |
| `user_id` | `str` | Sim | Identificador exclusivo para o usuário |
| `payment_instrument_id` | `Optional[str]` | Não | ID do instrumento de pagamento. Pode ser configurado posteriormente via `update_payment_instrument_id()` |
| `payment_session_id` | `Optional[str]` | Não | ID da sessão de pagamento. Pode ser configurado posteriormente via `update_payment_session_id()` |
| `region` | `Optional[str]` | Não | AWS região para o gerente de pagamento |
| `network_preferences_config` | `Optional[list[str]]` | Não | Lista de CAIP-2 identificadores de rede em ordem de preferência |
| `auto_payment` | `bool` | Não (padrão: `True`) | Se os requisitos de pagamento 402 devem ser processados automaticamente |
| `max_interrupt_retries` | `int` | Não (padrão: `5`) | Máximo de tentativas de interrupção por uso da ferramenta. Defina como 0 para desativar as interrupções |
| `agent_name` | `Optional[str]` | Não | Nome do agente propagado via cabeçalho HTTP em chamadas de API |
### 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:
| Ferramenta | Description |
| --- | --- |
| `get_payment_instrument` | Recuperar detalhes sobre um instrumento de pagamento específico |
| `list_payment_instruments` | Listar todos os instrumentos de pagamento de um usuário |
| `get_payment_session` | Recuperar detalhes sobre uma sessão de pagamento (orçamento, status, prazo de validade) |
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](https://strandsagents.com/latest/).
## LangGraph
O middleware de AgentCore pagamentos fornece processamento automatizado de pagamentos para LangGraph agentes. Ele suporta o protocolo [x402 Payment Required](https://www.x402.org/), 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:
1. O agente faz uma chamada de ferramenta que resulta em uma solicitação HTTP para um endpoint pago.
1. O endpoint responde com HTTP 402 Payment Required e uma carga de pagamento x402.
1. O middleware intercepta a resposta 402 e extrai os requisitos de pagamento.
1. O middleware faz chamadas `ProcessPayment` com o instrumento de pagamento e a sessão para gerar prova criptográfica.
1. O middleware repete a solicitação original com o cabeçalho do comprovante de pagamento anexado.
1. O endpoint valida a prova e retorna o conteúdo solicitado ao agente.
### 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:
| Valor | Comportamento |
| --- | --- |
| `RETRY` | Repita o pagamento com a configuração atual |
| `STOP` | Pare o processamento e devolva o erro ao agente |
| `SKIP` | Ignore o pagamento e continue sem o conteúdo pago |
### 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:
| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `payment_manager_arn` | `str` | Sim | ARN do recurso Bedrock Payment Manager AgentCore |
| `user_id` | `str` | Sim | Identificador exclusivo para o usuário |
| `payment_instrument_id` | `Optional[str]` | Não | ID do instrumento de pagamento |
| `payment_session_id` | `Optional[str]` | Não | ID da sessão de pagamento. Não é necessário quando `auto_session` é `True` |
| `region` | `Optional[str]` | Não | AWS região para o gerente de pagamento |
| `auto_session` | `bool` | Não (padrão: `False`) | Crie ou reutilize automaticamente uma sessão de pagamento |
| `auto_session_expiry_minutes` | `int` | Não (padrão: `60`) | Tempo de expiração das sessões criadas automaticamente em minutos |
| `auto_session_max_spend` | `str` | Não (padrão: `"5.00"`) | Valor máximo de gastos para sessões criadas automaticamente |
| `auto_session_currency` | `str` | Não (padrão: `"USD"`) | Moeda para limites de gastos de sessão criados automaticamente |
| `auto_payment` | `bool` | Não (padrão: `True`) | Se os requisitos de pagamento 402 devem ser processados automaticamente |
| `network_preferences_config` | `Optional[list[str]]` | Não | Lista de CAIP-2 identificadores de rede em ordem de preferência |
| `tool_allowlist` | `Optional[list[str]]` | Não | Lista de nomes de ferramentas que podem acionar pagamentos automáticos. Se não estiver definida, todas as ferramentas podem acionar pagamentos |
| `max_retries` | `int` | Não (padrão: `3`) | Número máximo de tentativas de pagamento por chamada de ferramenta |
| `on_payment_error` | `Optional[Callable]` | Não | Função de retorno de chamada invocada em caso de falha no pagamento |
| `on_payment_success` | `Optional[Callable]` | Não | Função de retorno de chamada invocada em caso de pagamento bem-sucedido |
| `on_payment_start` | `Optional[Callable]` | Não | Função de retorno de chamada invocada antes do início do processamento do pagamento |
| `agent_name` | `Optional[str]` | Não | Nome do agente propagado via cabeçalho HTTP em chamadas de API |
| `endpoint_url` | `Optional[str]` | Não | URL de endpoint personalizado para o serviço de AgentCore pagamentos |
### 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:
| Ferramenta | Description |
| --- | --- |
| `get_payment_instrument` | Recuperar detalhes sobre um instrumento de pagamento específico |
| `list_payment_instruments` | Listar todos os instrumentos de pagamento de um usuário |
| `get_payment_session` | Recuperar detalhes sobre uma sessão de pagamento (orçamento, status, prazo de validade) |
| `get_payment_balance` | Recuperar o saldo atual de um instrumento de pagamento |
| `list_payment_sessions` | Listar todas as sessões de pagamento de um usuário |
### 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.