# AgentCore avvio rapido dei pagamenti Questo tutorial illustra la configurazione AgentCore dei pagamenti e l'elaborazione della prima microtransazione. Alla fine, il tuo agente pagherà una risorsa utilizzando il protocollo x402 su una rete di prova. Puoi impostare i pagamenti in due modi: + [Utilizzo della funzionalità AgentCore Pagamenti](#payments-getting-started-skill): un'esperienza di configurazione automatizzata che fornisce tutte le risorse attraverso una conversazione guidata con agenti di codifica AI come Kiro, Claude Code o Codex. L'abilità gestisce i comandi CLI, gli script SDK e il cablaggio del framework per te. + [Utilizzo di CLI, SDK o Boto3](#payments-getting-started-manual): una configurazione manuale dettagliata che utilizza direttamente CLI, SDK o CLI AgentCore . AWS AWS ## Utilizzo AgentCore dell'abilità Pagamenti L'abilità AgentCore Pagamenti automatizza l'intero processo di configurazione attraverso un'esperienza interattiva e guidata. Fornisce le seguenti risorse: + **PaymentCredentialProvider**— Memorizza le credenziali del fornitore di servizi di pagamento in AgentCore Identity. + **Payment Manager**: la risorsa di primo livello che coordina le operazioni di pagamento. + **Payment Connector**: collega il gestore alle tue credenziali tramite la AgentCore CLI. + **Strumento di pagamento**: un portafoglio crittografico che il tuo agente utilizza per pagare i commercianti per conto di un utente. + **Sessione di pagamento**: un contesto temporale con limiti di spesa. L'abilità trasferisce anche i pagamenti al tuo agente con uno strumento indipendente dal framework, quindi funziona con Strands, LangGraph OpenAI Agents SDK o qualsiasi framework Python. ### Prerequisiti Prima di iniziare, assicurati di avere: + ** AWS Account** con credenziali configurate () `aws configure` + **Una AWS regione in cui sono disponibili AgentCore i pagamenti**: us-east-1, us-west-2, eu-central-1 o ap-southeast-2. [AWS Vedi Regioni](agentcore-regions.md) supportate. + **Node.js 20\+** installati (la skill installa automaticamente la CLI AgentCore ) + **Un agente che accede a un endpoint a pagamento**: la skill consente all'agente di pagare per API protette x402. Per i test, puoi utilizzare l'endpoint sandbox. `https://sandbox.node4all.com/v1/x402-test` + **Il AWS`aws-agents` plug-in [Agent Toolkit for](https://github.com/aws/agent-toolkit-for-aws)** installato nel tuo agente di codifica AI: **Example** ------ #### [ Claude Code ] ``` /plugin marketplace add aws/agent-toolkit-for-aws /plugin install aws-agents@agent-toolkit-for-aws ``` ------ #### [ Codex ] Il plug-in viene rilevato automaticamente dal manifesto del marketplace. Per aggiungere il marketplace, esegui il seguente comando: ``` codex plugin marketplace add aws/agent-toolkit-for-aws ``` ------ ### Invoca l'abilità L'abilità di pagamento fa parte dell'`agents-build`abilità di [Agent Toolkit for](https://github.com/aws/agent-toolkit-for-aws). AWS Per attivarla, descrivi il tuo intento nel tuo agente di codifica AI. Ad esempio: + «Aggiungi pagamenti al mio agente utilizzando il plugin `agents-build` skill in`aws-agents`» + «Configura le microtransazioni per il mio agente utilizzando il `aws-agents` plugin `agents-build` skill in» + «Devo gestire 402 risposte a Payment Required utilizzando `agents-build` skill in `aws-agents` plugin» + «Invia una email al mio agente per pagare le API protette da x402 utilizzando il plugin skill in» `agents-build` `aws-agents` La skill rileva l'intenzione relativa al pagamento e carica automaticamente il flusso di lavoro dei pagamenti. ### A cosa serve l'abilità La skill esegue un processo automatizzato che fornisce l'infrastruttura di pagamento dall'inizio alla fine. L'abilità esegue automaticamente la maggior parte dei passaggi e si interrompe due volte per l'immissione dell'utente: 1. Verifica o installa la AgentCore CLI e configura il progetto 1. Crea il gestore dei pagamenti 1. **Pause**: corri `agentcore add payment-connector` a inserire i segreti del tuo provider (credenziali Coinbase CDP o Stripe Privy) 1. Distribuisce risorse sul tuo account () AWS `agentcore deploy -y` 1. Collega al tuo agente uno strumento di pagamento indipendente dal framework () `x402_payment_tool.py` 1. Crea un portafoglio (strumento) per utente e una sessione con budget limitato tramite l'SDK 1. **Pause**[: autorizzi il portafoglio (delega) e lo fondi con testnet USDC dal sito web Circle faucet](https://faucet.circle.com/) 1. Imposta le variabili di ambiente ed esegue un pagamento di prova su un endpoint a pagamento Prima di eseguire il comando connector, richiedi le credenziali al tuo provider: + **Coinbase CDP**: API Key ID, API Key Secret e Wallet Secret dal sito web della [Coinbase Developer Platform](https://portal.cdp.coinbase.com/) (con firma delegata abilitata). + **Stripe Privy**[: App ID, App Secret, Authorization ID e Authorization Private Key dal sito web della dashboard di Privy.](https://dashboard.privy.io/) In caso di esecuzione riuscita, l'agente chiama`x402_fetch`, rileva un pagamento`402`, salda il pagamento tramite l' AgentCore SDK e riprova a restituire i contenuti a pagamento. `200` ## Utilizzo di CLI, SDK o Boto3 Questa sezione illustra manualmente ogni passaggio utilizzando CLI, AgentCore AWS CLI o AWS SDK (Boto3). ### Prerequisiti Prima di iniziare, assicurati di avere: + ** AWS Account** con credenziali configurate () `aws configure` + **Python 3.10\+ installato** + **Una AWS regione in cui sono disponibili AgentCore i pagamenti**: us-east-1, us-west-2, eu-central-1 o ap-southeast-2. [AWS Vedi Regioni](agentcore-regions.md) supportate. Installa i pacchetti richiesti: ``` pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools ``` Verifica che le tue credenziali siano configurate: ``` aws sts get-caller-identity ``` **Suggerimento** Se hai installato la AgentCore CLI v0.19.0 o versione successiva, puoi utilizzare i comandi CLI come alternativa all'SDK nei passaggi 2, 3, 5 e 6. Ogni passaggio seguente mostra entrambe le opzioni. ### Passaggio 1: ottenere le credenziali del fornitore di servizi di pagamento AgentCore payments si connette a un fornitore di servizi di pagamento esterno per le operazioni di portafoglio. Prima di procedere, sono necessarie le credenziali di uno dei provider supportati. **Example** 1. Accedi alla [piattaforma per sviluppatori Coinbase](https://docs.cdp.coinbase.com/api-reference/v2/authentication) e crea o seleziona un progetto. 1. Genera una chiave API e annota l'**ID della chiave API**, l'**API Key Secret** e il **Wallet Secret**. 1. In **Progetto** > **Portafogli** > **Non-custodial Portafoglio** > **Sicurezza**, abilita la firma **delegata.** Utilizzerai questi tre valori nel passaggio successivo: | Credential | Description | | --- | --- | | `API Key ID` | Identificatore pubblico per il tuo progetto CDP | | `API Key Secret` | Segreto privato per la firma delle richieste API | | `Wallet Secret` | Segreto per le operazioni di portafogli crittografici (derivazione di indirizzi, firma di transazioni) | 1. [Crea un'app Privy **dedicata su dashboard.privy.io**.](https://dashboard.privy.io/) Non riutilizzare app per altri scopi. 1. Copia l'**ID dell'app** e **l'app Secret** dalle impostazioni dell'app. 1. Passa a **Wallet Infrastructure** > **Autorizzazione** e scegli **Nuova chiave** per generare una coppia di P-256 chiavi. Utilizzerai questi quattro valori nel passaggio successivo: | Credential | Description | | --- | --- | | `App ID` | L'identificatore della tua applicazione Privy | | `App Secret` | Segreto per l'autenticazione di base da server a server | | `Authorization ID` | Identificatore di chiave pubblica della coppia di P-256 chiavi | | `Authorization Private Key` | Chiave privata della coppia di P-256 chiavi | Per tutti i dettagli, tra cui le migliori pratiche di sicurezza e la rotazione delle credenziali, consulta [Prerequisiti](payments-prerequisites.md). ### Fase 2: Archivia le credenziali in Identity AgentCore Memorizza le credenziali del tuo fornitore di servizi di pagamento come file. PaymentCredentialProvider Ciò mantiene AWS segreti in Secrets Manager anziché nel codice dell'applicazione. **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}") ``` Per lo schema completo di richiesta e risposta, [CreatePaymentCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentCredentialProvider.html)consulta l'API Reference. #### Alternativa CLI: memorizza le credenziali Con la AgentCore CLI, l'archiviazione delle credenziali avviene automaticamente quando si aggiunge un connettore di pagamento (Fase 3). Salta questo passaggio se prevedi di utilizzare il percorso CLI. ### Passaggio 3: Creare un gestore dei pagamenti e un connettore Un Payment Manager è la risorsa di primo livello che coordina le operazioni di pagamento. Un Payment Connector collega il gestore alle credenziali del fornitore dei pagamenti. Prima di creare queste risorse, configura i ruoli IAM richiesti come descritto in Ruoli [IAM per i AgentCore pagamenti](payments-iam-roles.md). **Example** Per la procedura dettagliata completa sulla console, che include l'autorizzazione JWT e le dichiarazioni personalizzate, consulta [Create a Payment Manager](payments-create-manager.md) and Connector. 1. Apri la [ AgentCore console Amazon Bedrock](https://console.aws.amazon.com/bedrock-agentcore/). 1. Nel pannello di navigazione, in **Crea**, scegli **Pagamenti**. 1. Scegli **Crea gestore di pagamenti**. 1. Inserisci un **nome** per il tuo gestore dei pagamenti. 1. In **Autorizzazioni**, scegli **Crea e usa un nuovo ruolo di servizio** (o seleziona un ruolo esistente). 1. In **Inbound Auth**, scegli **Usa nome utente IAM per l'autorizzazione IAM**. 1. (Facoltativo) Nella sezione **Connettore di pagamento**, scegli un nome per il connettore e seleziona un'autenticazione in uscita esistente o creane una nuova selezionando il tuo provider (Coinbase o Stripe Privy) e inserendo le tue credenziali. 1. **Scegli Crea gestore dei pagamenti.** La CLI crea il fornitore di credenziali, Payment Manager e Payment Connector in un unico flusso. Dalla directory AgentCore del progetto, aggiungi insieme un gestore dei pagamenti e un connettore. **Procedura guidata interattiva:** ``` agentcore add payment-manager ``` La procedura guidata richiede il nome del gestore, lo schema (intercettore), l'interruttore di pagamento automatico e il limite di spesa predefinito. Chiede quindi se aggiungere un connettore e illustra la selezione del provider e l'immissione delle credenziali. **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 (Privato):** ``` 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 ``` Dopo l'aggiunta, implementa per fornire l'infrastruttura di pagamento: ``` agentcore deploy ``` La fase di implementazione crea ruoli IAM, archivia le credenziali in AgentCore Identity ed effettua il provisioning di Payment Manager e Connector. Nell'output vedrai «Creazione di un'infrastruttura di pagamento...». L' AgentCore SDK crea il Payment Manager, il fornitore di credenziali e il connettore in un'unica chiamata. ``` 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}") ``` Per Stripe Privy, sostituisci le credenziali Privy `payment_credential_provider_config` con `credential_provider_vendor: "StripePrivy"` e le corrispondenti credenziali Privy. Crea il Payment Manager: ``` aws bedrock-agentcore-control create-payment-manager \ --name "my-first-payment-manager" \ --authorizer-type AWS_IAM \ --role-arn "" \ --region us-west-2 ``` Dopo che il gestore ha raggiunto `READY` lo stato, crea un fornitore di credenziali e un connettore. Vedi [Creare un gestore di pagamenti e un connettore](payments-create-manager.md) per il flusso di lavoro AWS CLI completo. Innanzitutto, crea il Payment Manager (lo stesso per entrambi i provider): ``` 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) ``` Quindi crea il Payment Connector per il tuo provider: **Coinbase CDP:** ``` 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}") ``` **Privato:** ``` 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 non disponi di un ruolo di servizio, consulta [IAM roles for AgentCore payments per](payments-iam-roles.md) istruzioni su come crearne uno. La console può anche creare un ruolo per tuo conto. Per gli schemi completi di richiesta e risposta, consulta [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)nell'API Reference. ### Fase 4: Creare uno strumento di pagamento Uno strumento di pagamento è un portafoglio crittografico incorporato che il tuo agente utilizza per pagare i commercianti per conto di un utente. Ogni strumento è associato a una rete blockchain specifica. **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 ``` Salva l'`paymentInstrumentId`e `redirectUrl` dalla risposta. ``` 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}") ``` Per lo schema completo di richiesta e risposta, [CreatePaymentInstrument](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentInstrument.html)consulta l'API Reference. #### Finanzia il portafoglio e concedi le autorizzazioni Prima che l'agente possa effettuare transazioni, l'utente finale deve finanziare il portafoglio e concedere le autorizzazioni di firma. Apri la risposta `redirectUrl` dalla risposta precedente in un browser. Dall'hub del portafoglio, l'utente può: + Ricarica il portafoglio utilizzando Crypto Transfer, credit/debit Card, Apple Pay, Google Pay o ACH + Concedi all'agente il permesso di firmare le transazioni per suo conto Per un ambiente di test, finanzia il portafoglio con testnet USDC. Dopo il finanziamento, verifica lo stato dello strumento finché non diventa: `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) ``` Per maggiori dettagli sui flussi di finanziamento per fornitore, consulta [Finanziamento del portafoglio](payments-how-it-works.md#payments-how-it-works-funding-wallet). ### Passaggio 5: Creare una sessione di pagamento Una sessione di pagamento è un contesto temporale con limiti di spesa opzionali. Quando la sessione scade o il budget è esaurito, l'agente non può effettuare ulteriori pagamenti nell'ambito di quella sessione. **Example** Quando si utilizza la CLI, non è necessario creare una sessione manualmente. Passa `--auto-session` a `agentcore invoke` e la CLI crea o riutilizza una sessione con il limite di spesa predefinito configurato nel gestore dei pagamenti. ``` agentcore invoke \ --prompt "your prompt here" \ --payment-instrument-id \ --auto-session \ --payment-user-id test-user-123 ``` Per utilizzare una sessione specifica che hai creato tramite l'SDK, passa `--payment-session-id` invece di. `--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)") ``` Per lo schema completo di richiesta e risposta, consulta [CreatePaymentSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentSession.html)l'API Reference. ### Passaggio 6: Elaborazione di un pagamento con un agente Strands Con tutte le risorse disponibili, crea un agente Strands che gestisca automaticamente i pagamenti x402. Quando l'agente chiama un endpoint a pagamento e riceve una risposta HTTP 402, il plugin per i pagamenti firma la transazione e riprova la richiesta. **Example** Richiama il tuo agente distribuito con il contesto dei pagamenti. La CLI trasmette lo strumento di pagamento e la sessione all'agente in fase di esecuzione e l'intercettore x402 dell'agente gestisce automaticamente il pagamento. ``` 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 ``` Per passare una sessione esplicita invece di crearne una 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 ``` Usa la `PaymentManager` classe per generare intestazioni di pagamento quando ricevi una risposta 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`contiene l'intestazione della prova di pagamento. Includi questa intestazione quando ritenti la richiesta verso l'endpoint a pagamento. Chiama `process-payment` direttamente con un payload x402 (utilizzato quando gestisci tu stesso l'orchestrazione dei pagamenti): ``` 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 ``` Per lo schema completo di richiesta e risposta, consulta [ProcessPayment](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)l'API Reference. ``` 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) ``` Per lo schema completo di richiesta e risposta della chiamata API sottostante, consulta [ProcessPayment](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)l'API Reference. ### Verifica il pagamento Dopo che l'agente ha elaborato un pagamento, controlla la sessione per confermare che la transazione è stata registrata: **Example** ``` session = manager.get_payment_session( user_id="test-user-123", payment_session_id=SESSION_ID ) print(f"Status: {session['status']}, Remaining: {session['remainingAmount']}") ``` Puoi anche controllare il saldo dello strumento: ``` 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") ``` Puoi anche controllare il saldo dello strumento: ``` balance = dp_client.get_payment_instrument_balance( paymentManagerArn=PAYMENT_MANAGER_ARN, paymentInstrumentId=INSTRUMENT_ID ) print(f"Remaining balance: {balance['amount']} {balance['currency']}") ``` ## Risoluzione dei problemi I seguenti problemi si applicano sia al percorso di configurazione basato sulle abilità che a quello manuale. | Problema | Soluzione | | --- | --- | | Payment Manager si è bloccato nella creazione | Attendi fino a 2 minuti. Se passa a CREATE\_FAILED, verifica che l'ARN e le autorizzazioni del ruolo di servizio siano corretti. | | «non attivo» PaymentInstrument | L'utente finale deve finanziare il portafoglio e concedere le autorizzazioni di firma tramite l'URL di reindirizzamento prima che l'agente possa effettuare la transazione. | | «Sessione scaduta o budget superato» | Crea una nuova sessione di pagamento con una scadenza più lunga o un limite di spesa più elevato. | | «CredentialProvider non trovato» | Verifica che l'ARN del provider di credenziali corrisponda a quello creato nel passaggio 2. Assicurati che la regione sia coerente in tutte le chiamate. | | ProcessPayment restituisce FALLITO | Verifica che il portafoglio abbia un saldo USDC sufficiente per l'importo della transazione più le commissioni sul gas. | ## Pulizia Elimina le risorse che hai creato durante questo 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 ``` I `remove` comandi aggiornano la configurazione locale. Il follow-up `deploy` distrugge l'infrastruttura di pagamento del tuo account. ``` 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.") ``` ## Cosa hai costruito Attraverso questo tutorial, hai creato: + **PaymentCredentialProvider**— Credenziali del fornitore di servizi di pagamento memorizzate in Identity AgentCore + **PaymentManager**— Top-level risorse per il coordinamento delle operazioni di pagamento + **PaymentConnector**— Integrazione tra il gestore e il fornitore di pagamenti esterno + **PaymentInstrument**— Un portafoglio crittografico integrato, finanziato e autorizzato dall'utente finale + **PaymentSession**— Un contesto di pagamento limitato nel tempo e con un budget limitato + **Strands Agent: un agente** di intelligenza artificiale che gestisce automaticamente i pagamenti x402 ## Fasi successive + [Connect a Coinbase x402 Bazaar per scoprire oltre 10.000 strumenti MCP](payments-connect-bazaar.md) a pagamento. + [Integra con Browser Tool per accedere ai siti web protetti da paywall.](payments-browser.md) + [Abilita l'osservabilità](payments-observability.md) per monitorare le operazioni di pagamento in. CloudWatch + [Rivedi i ruoli IAM](payments-iam-roles.md) per configurare l'accesso con privilegi minimi per la produzione.