# AgentCore início rápido de pagamentos Este tutorial explica como configurar AgentCore pagamentos e processar sua primeira microtransação. Ao final, seu agente pagará por um recurso usando o protocolo x402 em uma rede de teste. Você pode configurar pagamentos de duas formas: + [Usando a habilidade de AgentCore pagamentos](#payments-getting-started-skill) — uma experiência de configuração automatizada que provisiona todos os recursos por meio de uma conversa guiada com agentes de codificação de IA, como Kiro, Claude Code ou Codex. A habilidade lida com comandos de CLI, scripts de SDK e cabeamento de estrutura para você. + [Usando CLI, SDK ou Boto3](#payments-getting-started-manual) — Uma configuração manual passo a passo usando a CLI, o SDK ou a CLI diretamente AgentCore . AWS AWS ## Usando a habilidade de AgentCore pagamentos A habilidade de AgentCore pagamentos automatiza todo o processo de configuração por meio de uma experiência interativa e guiada. Ele fornece os seguintes recursos: + **PaymentCredentialProvider**— Armazena as credenciais do provedor de pagamento no AgentCore Identity. + **Gerenciador de pagamentos** — O recurso de alto nível que coordena as operações de pagamento. + **Conector de pagamento** — vincula o gerente às suas credenciais por meio da AgentCore CLI. + **Instrumento de pagamento** — Uma carteira criptográfica que seu agente usa para pagar comerciantes em nome de um usuário. + **Sessão de pagamento** — Um contexto limitado por tempo com limites de gastos. A habilidade também conecta pagamentos ao seu agente com uma ferramenta independente de estrutura, então funciona com Strands, LangGraph OpenAI Agents SDK ou qualquer estrutura Python. ### Pré-requisitos Antes de começar, verifique se você tem: + ** AWS Conta** com credenciais configuradas () `aws configure` + **Uma AWS região em que AgentCore os pagamentos estão disponíveis** — us-east-1, us-west-2, eu-central-1 ou ap-southeast-2. Consulte [AWS Regiões suportadas](agentcore-regions.md). + **Node.js Mais de 20** instalados (a habilidade instala a CLI automaticamente AgentCore ) + **Um agente que acessa um endpoint pago** — A habilidade permite que seu agente pague por APIs protegidas por x402. Para testar, você pode usar o endpoint `https://sandbox.node4all.com/v1/x402-test` sandbox. + **O [kit de ferramentas do agente para AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-agents` plug-in** instalado em seu agente de codificação de IA: **Example** ------ #### [ Claude Code ] ``` /plugin marketplace add aws/agent-toolkit-for-aws /plugin install aws-agents@agent-toolkit-for-aws ``` ------ #### [ Codex ] O plug-in é descoberto automaticamente no manifesto do mercado. Para adicionar o marketplace, execute o seguinte comando: ``` codex plugin marketplace add aws/agent-toolkit-for-aws ``` ------ ### Invoque a habilidade A habilidade de pagamentos faz parte da `agents-build` habilidade do [kit de ferramentas do agente para AWS](https://github.com/aws/agent-toolkit-for-aws). Para acioná-lo, descreva sua intenção em seu agente de codificação de IA. Por exemplo: + “Adicionar pagamentos ao meu agente usando a `agents-build` habilidade no `aws-agents` plugin” + “Configurar microtransações para meu agente usando o `aws-agents` plugin `agents-build` skill in” + “Preciso lidar com 402 respostas obrigatórias de pagamento usando o `agents-build` skill in `aws-agents` plugin” + “Contratar meu agente para pagar por APIs protegidas por x402 usando `agents-build` o skill in plugin” `aws-agents` A habilidade detecta a intenção relacionada ao pagamento e carrega o fluxo de trabalho de pagamentos automaticamente. ### O que a habilidade faz A habilidade executa um processo automatizado que provisiona sua infraestrutura de pagamento de ponta a ponta. A habilidade executa a maioria das etapas automaticamente e faz uma pausa duas vezes para sua entrada: 1. Verifica ou instala a AgentCore CLI e configura o projeto 1. Cria o gerenciador de pagamentos 1. **Pausas** — Você corre `agentcore add payment-connector` para inserir os segredos do seu provedor (credenciais Coinbase CDP ou Stripe Privy) 1. Implanta recursos em sua AWS conta () `agentcore deploy -y` 1. Conecta uma ferramenta de pagamento independente da estrutura () `x402_payment_tool.py` ao seu agente 1. Cria uma carteira por usuário (instrumento) e uma sessão com orçamento limitado por meio do SDK 1. **Pausas** [— Você autoriza a carteira (delegação) e a financia com o testnet USDC do site Circle faucet](https://faucet.circle.com/) 1. Define variáveis de ambiente e executa um pagamento de teste em um endpoint pago Antes de executar o comando do conector, obtenha as credenciais do seu provedor: + **CDP da Coinbase** — ID da chave da API, segredo da chave da API e segredo da carteira do site da [Coinbase Developer Platform](https://portal.cdp.coinbase.com/) (com a assinatura delegada ativada). + **Stripe Privy** — ID do aplicativo, segredo do aplicativo, ID de autorização e chave privada de autorização do site do painel [Privy.](https://dashboard.privy.io/) Uma execução bem-sucedida mostra o agente ligando`x402_fetch`, detectando um`402`, liquidando o pagamento por meio do AgentCore SDK e a tentativa retornando `200` com conteúdo pago. ## Usando CLI, SDK ou Boto3 Esta seção mostra cada etapa manualmente usando a AgentCore CLI, a AWS CLI ou o AWS SDK (Boto3). ### Pré-requisitos Antes de começar, verifique se você tem: + ** AWS Conta** com credenciais configuradas () `aws configure` + **Python 3.10\+ instalado** + **Uma AWS região em que AgentCore os pagamentos estão disponíveis** — us-east-1, us-west-2, eu-central-1 ou ap-southeast-2. Consulte [AWS Regiões suportadas](agentcore-regions.md). Instale os pacotes obrigatórios: ``` pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools ``` Verifique se suas credenciais estão configuradas: ``` aws sts get-caller-identity ``` **dica** Se você tiver a AgentCore CLI v0.19.0 ou posterior instalada, poderá usar os comandos da CLI como alternativa ao SDK nas etapas 2, 3, 5 e 6. Cada etapa abaixo mostra as duas opções. ### Etapa 1: Obter credenciais do provedor de pagamento AgentCore os pagamentos se conectam a um provedor de pagamento externo para operações de carteira. Você precisa de credenciais de um dos provedores compatíveis antes de continuar. **Example** 1. Faça login na [Coinbase Developer Platform](https://docs.cdp.coinbase.com/api-reference/v2/authentication) e crie ou selecione um projeto. 1. Gere uma chave de API e anote o **ID da chave** da **API, o segredo da chave da API** e o **segredo da carteira**. 1. Em **Projeto** > **Carteiras** > **Non-custodial Carteira** > **Segurança**, ative a Assinatura **delegada.** Você usará esses três valores na próxima etapa: | Credencial | Description | | --- | --- | | `API Key ID` | Identificador público para seu projeto CDP | | `API Key Secret` | Segredo privado para assinar solicitações de API | | `Wallet Secret` | Segredo para operações de carteira criptográfica (derivação de endereços, assinatura de transações) | 1. Crie um aplicativo Privy **dedicado** em [dashboard.privy.io](https://dashboard.privy.io/). Não reutilize aplicativos que tenham outras finalidades. 1. Copie o **ID do aplicativo** **e o segredo** do aplicativo das configurações do seu aplicativo. 1. Navegue até **Wallet Infrastructure** > **Authorization** e escolha **New Key** para gerar um par de P-256 chaves. Você usará esses quatro valores na próxima etapa: | Credencial | Description | | --- | --- | | `App ID` | Seu identificador de aplicativo Privy | | `App Secret` | Segredo da autenticação básica de servidor para servidor | | `Authorization ID` | Identificador de chave pública do par de P-256 chaves | | `Authorization Private Key` | Chave privada do par de P-256 chaves | Para obter detalhes completos, incluindo as melhores práticas de segurança e rotação de credenciais, consulte [Pré-requisitos](payments-prerequisites.md). ### Etapa 2: armazenar credenciais no Identity AgentCore Armazene suas credenciais de provedor de pagamento como um PaymentCredentialProvider. Isso mantém AWS segredos no Secrets Manager e não no código do seu aplicativo. **Example** ``` import boto3 client = boto3.client("bedrock-agentcore-control", region_name="us-west-2") credential_provider = client.create_payment_credential_provider( name="my-coinbase-credentials", credentialProviderVendor="CoinbaseCDP", coinbaseCdpConfig={ "apiKeyId": "", "apiKeySecret": "", "walletSecret": "" } ) CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"] print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}") ``` ``` import boto3 client = boto3.client("bedrock-agentcore-control", region_name="us-west-2") credential_provider = client.create_payment_credential_provider( name="my-privy-credentials", credentialProviderVendor="StripePrivy", stripePrivyConfig={ "appId": "", "appSecret": "", "authorizationId": "", "authorizationPrivateKey": "" } ) CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"] print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}") ``` Para ver o esquema completo de solicitações e respostas, consulte [CreatePaymentCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentCredentialProvider.html)a Referência da API. #### Alternativa de CLI: armazenar credenciais Com a AgentCore CLI, o armazenamento de credenciais acontece automaticamente quando você adiciona um conector de pagamento (Etapa 3). Ignore esta etapa se você planeja usar o caminho da CLI. ### Etapa 3: criar um gerenciador de pagamentos e um conector Um gerente de pagamentos é o recurso de alto nível que coordena as operações de pagamento. Um conector de pagamento vincula o gerente às suas credenciais de provedor de pagamento. Antes de criar esses recursos, configure as funções necessárias do IAM conforme descrito em [Funções do IAM para AgentCore pagamentos](payments-iam-roles.md). **Example** Para ver o passo a passo completo do console, incluindo autorização do JWT e declarações personalizadas, consulte [Criar um gerenciador e conector de pagamentos](payments-create-manager.md). 1. Abra o [ AgentCore console Amazon Bedrock](https://console.aws.amazon.com/bedrock-agentcore/). 1. No painel de navegação, em **Criar**, escolha **Pagamentos**. 1. Escolha **Criar gerenciador de pagamentos**. 1. Insira um **nome** para seu gerente de pagamentos. 1. Em **Permissões**, escolha **Criar e usar uma nova função de serviço** (ou selecione uma função existente). 1. Em **Autenticação de entrada**, escolha **Usar nome de usuário do IAM** para autorização do IAM. 1. (Opcional) Na seção **Conector de pagamento**, escolha um nome para o conector e selecione uma autenticação de saída existente ou crie uma nova selecionando seu provedor (Coinbase ou Stripe Privy) e inserindo suas credenciais. 1. Escolha **Criar gerenciador de pagamentos**. A CLI cria o provedor de credenciais, o Payment Manager e o Payment Connector em um único fluxo. No diretório do seu AgentCore projeto, adicione um gerenciador de pagamentos e um conector juntos. **Assistente interativo:** ``` agentcore add payment-manager ``` O assistente solicita o nome do gerente, o padrão (interceptor), a opção de pagamento automático e o limite de gastos padrão. Em seguida, ele pergunta se deseja adicionar um conector e analisa a seleção do provedor e a entrada de credenciais. **Non-interactive (Coinbase CDP):** ``` agentcore add payment-manager \ --name my-payment-manager \ --auto-payment \ --default-spend-limit 5.00 agentcore add payment-connector \ --manager my-payment-manager \ --name my-coinbase-connector \ --provider CoinbaseCDP \ --api-key-id \ --api-key-secret \ --wallet-secret ``` **Non-interactive (Privado):** ``` agentcore add payment-manager \ --name my-payment-manager \ --auto-payment \ --default-spend-limit 5.00 agentcore add payment-connector \ --manager my-payment-manager \ --name my-privy-connector \ --provider StripePrivy \ --app-id \ --app-secret \ --authorization-id \ --authorization-private-key ``` Depois de adicionar, implante para provisionar a infraestrutura de pagamento: ``` agentcore deploy ``` A etapa de implantação cria funções do IAM, armazena credenciais no AgentCore Identity e provisiona o Payment Manager e o Connector. Você verá “Criando infraestrutura de pagamento...” na saída. O AgentCore SDK cria o Payment Manager, o provedor de credenciais e o conector em uma única chamada. ``` from bedrock_agentcore.payments import PaymentClient payment_client = PaymentClient(region_name="us-west-2") response = payment_client.create_payment_manager_with_connector( payment_manager_name="my-first-payment-manager", payment_manager_description="Payment manager for my agent.", authorizer_type="AWS_IAM", role_arn="", payment_connector_config={ "name": "my-coinbase-connector", "description": "Coinbase CDP connector", "payment_credential_provider_config": { "name": "my-coinbase-provider", "credential_provider_vendor": "CoinbaseCDP", "credentials": { "api_key_id": "", "api_key_secret": "", "wallet_secret": "", }, }, }, wait_for_ready=True, max_wait=300, poll_interval=5, ) PAYMENT_MANAGER_ARN = response["paymentManager"]["paymentManagerArn"] PAYMENT_CONNECTOR_ID = response["paymentConnector"]["paymentConnectorId"] print(f"Payment Manager ARN: {PAYMENT_MANAGER_ARN}") print(f"Connector ID: {PAYMENT_CONNECTOR_ID}") ``` Para o Stripe Privy, substitua a por `credential_provider_vendor: "StripePrivy"` e `payment_credential_provider_config` as credenciais correspondentes do Privy. Crie o Gerenciador de Pagamentos: ``` aws bedrock-agentcore-control create-payment-manager \ --name "my-first-payment-manager" \ --authorizer-type AWS_IAM \ --role-arn "" \ --region us-west-2 ``` Depois que o gerente atingir o `READY` status, crie um provedor e um conector de credenciais. Consulte [Criar um gerenciador e conector de pagamentos](payments-create-manager.md) para ver o fluxo de trabalho completo da AWS CLI. Primeiro, crie o Gerenciador de Pagamentos (o mesmo para os dois provedores): ``` import time manager = client.create_payment_manager( name="my-first-payment-manager", authorizerType="AWS_IAM", roleArn="" ) PAYMENT_MANAGER_ARN = manager["paymentManagerArn"] print(f"Payment Manager created: {PAYMENT_MANAGER_ARN}") # Wait for the manager to reach READY state while True: status = client.get_payment_manager(paymentManagerArn=PAYMENT_MANAGER_ARN) if status["status"] == "READY": break print(f"Status: {status['status']}... waiting") time.sleep(5) ``` Em seguida, crie o Conector de Pagamento para seu provedor: **CDP da Coinbase:** ``` connector = client.create_payment_connector( paymentManagerArn=PAYMENT_MANAGER_ARN, name="my-coinbase-connector", paymentConnectorType="CoinbaseCDP", credentialProviderArn=CREDENTIAL_PROVIDER_ARN ) PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"] print(f"Connector created: {PAYMENT_CONNECTOR_ID}") ``` **Privado:** ``` connector = client.create_payment_connector( paymentManagerArn=PAYMENT_MANAGER_ARN, name="my-privy-connector", paymentConnectorType="StripePrivy", credentialProviderArn=CREDENTIAL_PROVIDER_ARN ) PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"] print(f"Connector created: {PAYMENT_CONNECTOR_ID}") ``` Se você não tiver uma função de serviço, consulte [Funções do IAM para AgentCore pagamentos](payments-iam-roles.md) para obter instruções sobre como criar uma. O console também pode criar uma função em seu nome. Para ver os esquemas completos de solicitação e resposta, consulte [CreatePaymentManager](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentManager.html)e [CreatePaymentConnector](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentConnector.html)na Referência da API. ### Etapa 4: criar um instrumento de pagamento Um instrumento de pagamento é uma carteira criptográfica incorporada que seu agente usa para pagar comerciantes em nome de um usuário. Cada instrumento está associado a uma rede blockchain específica. **Example** ``` from bedrock_agentcore.payments import PaymentManager manager = PaymentManager( payment_manager_arn=PAYMENT_MANAGER_ARN, region_name="us-west-2" ) instrument = manager.create_payment_instrument( user_id="test-user-123", payment_connector_id=PAYMENT_CONNECTOR_ID, payment_instrument_type="EMBEDDED_CRYPTO_WALLET", payment_instrument_details={ "embeddedCryptoWallet": { "network": "ETHEREUM", "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}] } }, ) INSTRUMENT_ID = instrument["paymentInstrumentId"] REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"] print(f"Instrument created: {INSTRUMENT_ID}") print(f"Fund the wallet at: {REDIRECT_URL}") ``` ``` aws bedrock-agentcore create-payment-instrument \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-connector-id "$PAYMENT_CONNECTOR_ID" \ --user-id "test-user-123" \ --payment-instrument-type "EMBEDDED_CRYPTO_WALLET" \ --payment-instrument-details '{ "embeddedCryptoWallet": { "network": "ETHEREUM", "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}] } }' \ --client-token "$(uuidgen)" \ --region us-west-2 ``` Salve a `paymentInstrumentId` e `redirectUrl` da resposta. ``` import uuid dp_client = boto3.client("bedrock-agentcore", region_name="us-west-2", endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com") instrument = dp_client.create_payment_instrument( userId="test-user-123", paymentManagerArn=PAYMENT_MANAGER_ARN, paymentConnectorId=PAYMENT_CONNECTOR_ID, paymentInstrumentType="EMBEDDED_CRYPTO_WALLET", paymentInstrumentDetails={ "embeddedCryptoWallet": { "network": "ETHEREUM", "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}] } }, clientToken=str(uuid.uuid4()), ) INSTRUMENT_ID = instrument["paymentInstrumentId"] REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"] print(f"Instrument created: {INSTRUMENT_ID}") print(f"Fund the wallet at: {REDIRECT_URL}") ``` Para ver o esquema completo de solicitações e respostas, consulte [CreatePaymentInstrument](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentInstrument.html)a Referência da API. #### Financie a carteira e conceda permissões Antes que o agente possa realizar transações, o usuário final deve financiar a carteira e conceder permissões de assinatura. Abra `redirectUrl` a resposta acima em um navegador. No hub da carteira, o usuário pode: + Recarregue a carteira usando transferência criptográfica, credit/debit cartão, Apple Pay, Google Pay ou ACH + Conceda permissão ao agente para assinar transações em seu nome Para um ambiente de teste, financie a carteira com testnet USDC. Após o financiamento, pesquise o status do instrumento até que ele se torne`ACTIVE`: **Example** ``` instrument = manager.get_payment_instrument( user_id="test-user-123", payment_instrument_id=INSTRUMENT_ID ) print(f"Status: {instrument['status']}") ``` ``` aws bedrock-agentcore get-payment-instrument \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-instrument-id "$INSTRUMENT_ID" \ --region us-west-2 ``` ``` while True: inst_status = dp_client.get_payment_instrument( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentInstrumentId=INSTRUMENT_ID ) if inst_status["status"] == "ACTIVE": print("Instrument is active and funded.") break print(f"Instrument status: {inst_status['status']}... waiting for funding") time.sleep(10) ``` Para obter mais detalhes sobre fluxos de financiamento por provedor, consulte [Financiamento da carteira](payments-how-it-works.md#payments-how-it-works-funding-wallet). ### Etapa 5: criar uma sessão de pagamento Uma sessão de pagamento é um contexto limitado por tempo com limites de gastos opcionais. Quando a sessão expira ou o orçamento está esgotado, o agente não pode fazer pagamentos adicionais dentro dessa sessão. **Example** Ao usar a CLI, você não precisa criar uma sessão manualmente. Passe `--auto-session` para `agentcore invoke` e a CLI criará ou reutilizará uma sessão com o limite de gastos padrão que você configurou no gerenciador de pagamentos. ``` agentcore invoke \ --prompt "your prompt here" \ --payment-instrument-id \ --auto-session \ --payment-user-id test-user-123 ``` Para usar uma sessão específica que você criou por meio do SDK, passe `--payment-session-id` em vez de`--auto-session`. ``` from bedrock_agentcore.payments import PaymentManager manager = PaymentManager( payment_manager_arn=PAYMENT_MANAGER_ARN, region_name="us-west-2" ) session = manager.create_payment_session( user_id="test-user-123", limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}}, expiry_time_in_minutes=60 ) SESSION_ID = session["paymentSessionId"] print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)") ``` ``` aws bedrock-agentcore create-payment-session \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --user-id "test-user-123" \ --expiry-time-in-minutes 60 \ --limits '{"maxSpendAmount": {"value": "5.00", "currency": "USD"}}' \ --client-token "$(uuidgen)" \ --region us-west-2 ``` ``` session = dp_client.create_payment_session( userId="test-user-123", paymentManagerArn=PAYMENT_MANAGER_ARN, expiryTimeInMinutes=60, limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}}, clientToken=str(uuid.uuid4()), ) SESSION_ID = session["paymentSessionId"] print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)") ``` Para ver o esquema completo de solicitações e respostas, consulte [CreatePaymentSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentSession.html)a Referência da API. ### Etapa 6: Processar um pagamento com um agente da Strands Com todos os recursos disponíveis, crie um agente Strands que gerencie pagamentos x402 automaticamente. Quando o agente liga para um endpoint pago e recebe uma resposta HTTP 402, o plug-in de pagamentos assina a transação e repete a solicitação. **Example** Invoque seu agente implantado com contexto de pagamento. A CLI passa o instrumento de pagamento e a sessão para o agente em tempo de execução, e o interceptor x402 do agente processa o pagamento automaticamente. ``` agentcore invoke \ --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \ --payment-instrument-id \ --auto-session \ --payment-user-id test-user-123 ``` Para passar por uma sessão explícita em vez de criar uma automaticamente: ``` agentcore invoke \ --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \ --payment-instrument-id \ --payment-session-id \ --payment-user-id test-user-123 ``` Use a `PaymentManager` classe para gerar cabeçalhos de pagamento ao receber uma resposta HTTP 402: ``` import uuid from bedrock_agentcore.payments import PaymentManager manager = PaymentManager( payment_manager_arn=PAYMENT_MANAGER_ARN, region_name="us-west-2" ) # When you receive a 402 response, generate payment proof payment_required_request = { "statusCode": 402, "headers": payment_required["headers"], "body": payment_required["body"], } payment_proof_headers = manager.generate_payment_header( user_id="test-user-123", payment_instrument_id=INSTRUMENT_ID, payment_session_id=SESSION_ID, payment_required_request=payment_required_request, client_token=str(uuid.uuid4()), ) ``` `payment_proof_headers`contém o cabeçalho do comprovante de pagamento. Inclua esse cabeçalho ao repetir a solicitação no endpoint pago. Ligue `process-payment` diretamente com uma carga x402 (usada quando você mesmo gerencia a orquestração de pagamentos): ``` aws bedrock-agentcore process-payment \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-session-id "$SESSION_ID" \ --payment-instrument-id "$INSTRUMENT_ID" \ --payment-type "CRYPTO_X402" \ --payment-input '{ "cryptoX402": { "version": "2", "payload": { "scheme": "exact", "network": "eip155:84532", "amount": "100000", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "payTo": "0xMERCHANT_ADDRESS", "maxTimeoutSeconds": 300, "extra": {"name": "USDC", "version": "2"} } } }' \ --client-token "$(uuidgen)" \ --region us-west-2 ``` Para ver o esquema completo de solicitações e respostas, consulte [ProcessPayment](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)a Referência da API. ``` 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 config = AgentCorePaymentsPluginConfig( payment_manager_arn=PAYMENT_MANAGER_ARN, user_id="test-user-123", payment_instrument_id=INSTRUMENT_ID, payment_session_id=SESSION_ID, region="us-west-2", ) plugin = AgentCorePaymentsPlugin(config=config) agent = Agent( system_prompt="You are a helpful assistant that can access paid APIs.", tools=[http_request], plugins=[plugin], ) # The agent handles 402 responses automatically response = agent("Access the premium endpoint at https://example-x402-merchant.com/paid-api") print(response) ``` Para ver o esquema completo de solicitação e resposta da chamada de API subjacente, consulte [ProcessPayment](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)a Referência da API. ### Verifique o pagamento Depois que o agente processar um pagamento, verifique a sessão para confirmar se a transação foi registrada: **Example** ``` session = manager.get_payment_session( user_id="test-user-123", payment_session_id=SESSION_ID ) print(f"Status: {session['status']}, Remaining: {session['remainingAmount']}") ``` Você também pode verificar o saldo do instrumento: ``` balance = manager.get_payment_instrument_balance( user_id="test-user-123", payment_instrument_id=INSTRUMENT_ID ) print(f"Remaining balance: {balance['amount']} {balance['currency']}") ``` ``` aws bedrock-agentcore get-payment-session \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-session-id "$SESSION_ID" \ --region us-west-2 aws bedrock-agentcore get-payment-instrument-balance \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-instrument-id "$INSTRUMENT_ID" \ --region us-west-2 ``` ``` session_status = dp_client.get_payment_session( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentSessionId=SESSION_ID ) print(f"Session status: {session_status['status']}") print(f"Amount spent: {session_status.get('spentAmount', '0.00')} USD") ``` Você também pode verificar o saldo do instrumento: ``` balance = dp_client.get_payment_instrument_balance( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentInstrumentId=INSTRUMENT_ID ) print(f"Remaining balance: {balance['amount']} {balance['currency']}") ``` ## Solução de problemas Os problemas a seguir se aplicam aos caminhos de configuração manual e baseados em habilidades. | Problema | Solução | | --- | --- | | O gerente de pagamentos está preso em CREATING | Aguarde até 2 minutos. Se for movido para CREATE\_FAILED, verifique se o ARN e as permissões da função de serviço estão corretos. | | “PaymentInstrument não ativo” | O usuário final deve financiar a carteira e conceder permissões de assinatura por meio do URL de redirecionamento antes que o agente possa realizar a transação. | | “Sessão expirada ou orçamento excedido” | Crie uma nova sessão de pagamento com uma expiração mais longa ou um limite de gastos maior. | | “CredentialProvider não encontrado” | Verifique se o ARN do provedor de credenciais corresponde ao que você criou na Etapa 2. Garanta que a região seja consistente em todas as chamadas. | | ProcessPayment falha nas devoluções | Verifique se a carteira tem saldo suficiente em USDC para o valor da transação mais as taxas de gás. | ## Limpeza Exclua os recursos que você criou durante este tutorial: **Example** ``` agentcore remove payment-connector --manager my-payment-manager --name my-coinbase-connector --yes agentcore remove payment-manager --name my-payment-manager --yes agentcore deploy ``` Os `remove` comandos atualizam a configuração local. O acompanhamento `deploy` destrói a infraestrutura de pagamento em sua conta. ``` from bedrock_agentcore.payments import PaymentClient payment_client = PaymentClient(region_name="us-west-2") payment_client.delete_payment_manager( payment_manager_id="" ) print("Payment Manager deleted.") ``` ``` aws bedrock-agentcore delete-payment-instrument \ --payment-manager-arn "$PAYMENT_MANAGER_ARN" \ --payment-instrument-id "$INSTRUMENT_ID" \ --region us-west-2 aws bedrock-agentcore-control delete-payment-connector \ --payment-manager-id "$PAYMENT_MANAGER_ID" \ --payment-connector-id "$PAYMENT_CONNECTOR_ID" \ --region us-west-2 aws bedrock-agentcore-control delete-payment-manager \ --payment-manager-id "$PAYMENT_MANAGER_ID" \ --region us-west-2 ``` ``` # Delete payment instrument dp_client.delete_payment_instrument( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentInstrumentId=INSTRUMENT_ID ) # Delete payment connector client.delete_payment_connector( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentConnectorId=PAYMENT_CONNECTOR_ID ) # Delete payment manager client.delete_payment_manager( paymentManagerArn=PAYMENT_MANAGER_ARN ) print("All payment resources deleted.") ``` ## O que você construiu Por meio desse tutorial, você criou: + **PaymentCredentialProvider**— Credenciais do provedor de pagamento armazenadas no Identity AgentCore + **PaymentManager**— Top-level recursos que coordenam as operações de pagamento + **PaymentConnector**— Integração entre seu gerente e o provedor de pagamento externo + **PaymentInstrument**— Uma carteira criptográfica incorporada, financiada e autorizada pelo usuário final + **PaymentSession**— Um contexto de pagamento limitado no tempo e com orçamento limitado + **Strands Agent** — Um agente de IA que gerencia pagamentos x402 automaticamente ## Próximas etapas + [Conecte-se ao Coinbase x402 Bazaar](payments-connect-bazaar.md) para descobrir mais de 10.000 ferramentas MCP pagas. + [Integre com a Browser Tool](payments-browser.md) para acessar sites pagos. + [Permita a observabilidade](payments-observability.md) para monitorar as operações de pagamento em CloudWatch. + [Analise as funções do IAM](payments-iam-roles.md) para configurar o acesso com privilégios mínimos para produção.