View a markdown version of this page

Risoluzione dei problemi relativi AgentCore al browser - Fondamento Amazon AgentCore
Errori di autorizzazione negataAccesso al modello negatoTimeout della sessione del browserLa registrazione non viene visualizzata in Amazon S3Errori di connessione di PlaywrightL'agente non può fare progressi a causa dei controlli CAPTCHAErrori CORS durante l'integrazione con le applicazioni browserSession Replay e Web Bot Auth non funzionano in nuove finestre o contesti del browserProblemi con le estensioni del browserProblemi relativi al profilo del browserRisoluzione dei problemi relativi alla Root Certificate AuthorityRisoluzione dei problemi relativi ai proxy del browserRisoluzione dei problemi relativi alle azioni del InvokeBrowser sistema operativo

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Risoluzione dei problemi relativi AgentCore al browser

Questa sezione fornisce soluzioni ai problemi più comuni che potresti riscontrare durante l'utilizzo di Amazon AgentCore Bedrock Browser.

Errori di autorizzazione negata

Sintomo: errori che indicano l'accesso negato o le autorizzazioni insufficienti.

Soluzione::

  • Verifica che l'utente o il ruolo IAM disponga delle autorizzazioni del browser richieste

  • Controlla le tue AWS credenziali: aws sts get-caller-identity

  • Per la registrazione: verifica che il ruolo di esecuzione disponga delle autorizzazioni di scrittura di Amazon S3

  • Per la registrazione: conferma che la politica di fiducia bedrock-agentcore.amazonaws.com consenta di assumere il ruolo

Accesso al modello negato

Sintomo: errori relativi all'accesso o all'autorizzazione del modello durante l'esecuzione degli agenti.

Soluzione::

  • Accedi alla console Amazon Bedrock

  • Vai a Model access nella barra di navigazione a sinistra

  • Abilita Anthropic Claude Sonnet 4

  • Verifica di trovarti nella regione corretta (abbina la regione indicata nel tuo codice)

Timeout della sessione del browser

Sintomo: le sessioni del browser terminano in modo imprevisto o si verificano errori di timeout.

Soluzione::

  • Controlla il sessionTimeoutSeconds parametro all'avvio delle sessioni

  • Il timeout predefinito è 900 secondi (15 minuti)

  • Aumenta il timeout per sessioni più lunghe: sessionTimeoutSeconds=1800

  • Le sessioni si interrompono automaticamente dopo il periodo di timeout

La registrazione non viene visualizzata in Amazon S3

Sintomo: nessuna registrazione di file nel bucket Amazon S3 al termine della sessione.

Soluzione::

  • Verifica che il ruolo di esecuzione disponga delle autorizzazioni Amazon S3 corrette

  • Verifica che il nome e il prefisso del bucket Amazon S3 siano corretti

  • Verifica che la politica di affidabilità del ruolo di esecuzione includa il servizio bedrock-agentcore

  • Esamina i CloudWatch log per gli errori di caricamento di Amazon S3

  • Assicurati che la sessione sia durata almeno alcuni secondi (sessioni molto brevi potrebbero non generare registrazioni)

Errori di connessione di Playwright

Sintomo: impossibile connettersi al browser con Playwright o errori. WebSocket

Soluzione::

  • Verifica di aver installato playwright: pip install playwright

  • Conferma che la sessione del browser sia iniziata correttamente prima di connetterti

  • Verifica che la sessione sia ancora attiva (non scaduta)

  • Verifica che la tua rete WebSocket consenta le connessioni

L'agente non può fare progressi a causa dei controlli CAPTCHA

Problema: il tuo agente viene bloccato dalla verifica CAPTCHA quando utilizza lo strumento Browser per interagire con i siti web.

Causa: Anti-bot le misure sui siti Web più diffusi rilevano la navigazione automatica e richiedono una verifica umana.

Soluzione: struttura il tuo agente in modo da evitare i motori di ricerca e implementa il seguente modello di architettura:

  • Utilizzate lo strumento Browser solo per azioni specifiche sulla pagina, non per ricerche generiche sul Web

  • Usa strumenti MCP diversi dal browser come Tavily Search per operazioni di ricerca web generali

  • Valuta la possibilità di aggiungere una funzionalità di visualizzazione live all'applicazione agente che consenta agli utenti finali di assumere il controllo e risolvere i CAPTCHA quando necessario

Errori CORS durante l'integrazione con le applicazioni browser

Problema: gli errori di condivisione Cross-Origin delle risorse (CORS) si verificano quando si creano applicazioni Web basate su browser che richiamano un server di runtime Amazon Bedrock personalizzato. AgentCore

Causa: le politiche di sicurezza del browser bloccano le richieste tra origini diverse inviate al server di runtime durante lo sviluppo locale o la distribuzione self-hosted.

Soluzione: aggiungete il middleware CORS al vostro sistema per gestire le richieste provenienti da più origini provenienti BedrockAgentCoreApp dal frontend:

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from fastapi.middleware.cors import CORSMiddleware

app = BedrockAgentCoreApp()

# Add CORS middleware to allow browser requests
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],           # Customize in production
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Handle browser preflight requests to /invocations
@app.options("/invocations")
async def options_handler():
    return {"message": "OK"}

@app.entrypoint
def my_agent(payload):
    return {"response": "Hello from agent"}
Importante

Negli ambienti di produzione, sostituisci allow_origins= ["*"] con origini di dominio specifiche per una maggiore sicurezza.

Session Replay e Web Bot Auth non funzionano in nuove finestre o contesti del browser

Problema: le funzionalità Session Replay e Web Bot Auth non sono disponibili quando il codice di automazione crea nuove finestre o contesti del browser.

Causa: queste funzionalità si basano su estensioni del browser che funzionano solo nel contesto predefinito del browser fornito da Amazon Bedrock. AgentCore Quando crei un nuovo contesto utilizzando metodi come browser.new_context() in Playwright, le estensioni non sono disponibili.

Soluzione: utilizza il contesto predefinito del browser fornito quando ti connetti alla sessione del browser. Evita di creare nuovi contesti o finestre se hai bisogno della funzionalità Session Replay o Web Bot Auth.

# ✓ Use the existing default context
context = browser.contexts[0]
page = context.pages[0]

# ✗ Don't create new contexts - Session Replay and Web Bot Auth won't work
# context = browser.new_context()

Problemi con le estensioni del browser

Il download dell'estensione non riesce con accesso negato

Sintomo: la sessione non inizia con errori relativi all'accesso ad Amazon S3 quando si utilizzano le estensioni.

Soluzione::

  • Verifica che il tuo utente o ruolo IAM s3:GetObject disponga delle s3:GetObjectHead autorizzazioni sul bucket di estensione

  • Verifica che il bucket Amazon S3 sia di proprietà dello stesso AWS account che effettua la chiamata API

  • Verifica che il nome e il prefisso del bucket (chiave oggetto) siano corretti

  • Se utilizzi bucket con versioni, assicurati di avere l'autorizzazione s3:GetObjectVersion

Estensione rifiutata a causa di un formato non valido

Sintomo: la sessione non inizia con errori di convalida relativi al formato del file di estensione.

Soluzione::

  • Assicurati che il file di estensione sia in formato ZIP

  • Verifica che il file ZIP contenga una struttura di estensione di Chrome valida con un manifest.json file valido

  • Verifica che l'estensione segua le linee guida per le estensioni di Chrome

  • Assicurati che lo ZIP sia stato creato dal contenuto della directory dell'estensione, non dalla cartella principale

Problemi relativi al profilo del browser

Impossibile salvare il profilo della sessione del browser a causa di un'operazione simultanea sul profilo

Sintomo: SaveBrowserSessionProfile ConflictException lanci.

Soluzione::

  • Riprova SaveBrowserSessionProfile in un secondo momento

  • Usa il backoff esponenziale con jitter se riprovi dall'agente o dal codice

Impossibile salvare il profilo della sessione del browser a causa di un'operazione simultanea nella sessione

Sintomo: SaveBrowserSessionProfile ConflictException lanci.

Soluzione::

  • Riprova SaveBrowserSessionProfile in un secondo momento

  • Usa il backoff esponenziale con jitter se riprovi dall'agente o dal codice

L'autenticazione non riesce quando si carica un profilo del browser salvato

Sintomo: una sessione del browser caricata da un profilo salvato richiede una nuova autenticazione anche se il profilo è stato salvato con cookie di autenticazione validi.

Causa: i cookie memorizzati nel profilo del browser sono scaduti. I siti Web impostano le date di scadenza dei cookie (ad esempio i token di autenticazione) e il browser rimuove automaticamente i cookie scaduti in base a tali date di scadenza. Quando si carica un profilo, tutti i cookie scaduti da quando il profilo è stato salvato non saranno disponibili.

Soluzione::

  • Re-authenticate nella sessione del browser per ottenere nuovi cookie

  • Salva nuovamente il profilo dopo una nuova autenticazione per aggiornarlo con nuovi cookie

  • Per i flussi di lavoro che richiedono l'autenticazione a lungo termine, considera la durata tipica dei cookie dei siti Web di destinazione quando pianifichi l'utilizzo del profilo

  • Implementa la riautenticazione periodica nel flusso di lavoro di automazione se è prevista la scadenza dei cookie

  • Salva i profili più frequentemente per gli stati di autenticazione critici per ridurre al minimo il tempo che intercorre tra il salvataggio e il successivo utilizzo

Nota

I tempi di scadenza dei cookie sono impostati dai siti Web e non possono essere modificati dai profili del browser. I cookie di sessione scadono in genere quando termina la sessione del browser, mentre i cookie persistenti scadono in base ai relativi attributi Max-Age o Expires.

Risoluzione dei problemi relativi alla Root Certificate Authority

La tabella seguente descrive gli errori più comuni e le relative risoluzioni durante la configurazione dei certificati CA root per Amazon Bedrock Browser. AgentCore

Errore Causa Risoluzione

Certificato segreto non trovato in Secrets Manager

L'ARN segreto non esiste o il segreto è stato eliminato.

Verifica che l'ARN segreto sia corretto e che il segreto esista nella regione specificata.

Accesso negato al certificato segreto in Secrets Manager

Il chiamante non dispone secretsmanager:GetSecretValue dell'autorizzazione sulla segretezza.

Aggiungi l'secretsmanager:GetSecretValueautorizzazione alla tua policy IAM per l'ARN segreto specificato.

Il contenuto del certificato non è un formato valido PEM/X.509

Il valore segreto non è un PEM-encoded X.509 certificato valido.

Assicurati che il segreto contenga un certificato PEM formattato correttamente che inizia con -----BEGIN CERTIFICATE----- e termina con. -----END CERTIFICATE-----

Il certificato è scaduto

La notAfter data del certificato è passata.

Sostituisci il certificato scaduto con uno valido in AWS Secrets Manager e riprova.

Il certificato non è ancora valido

La notBefore data del certificato è futura.

Attendi l'inizio del periodo di validità del certificato o utilizza un certificato attualmente valido.

Il numero di certificati supera il numero massimo consentito

Sono stati forniti più di 10 certificati a livello di sessione o di strumento.

Riduci il numero di certificati a 10 o meno per sessione e 10 o meno per strumento.

L'ubicazione del certificato è obbligatoria

La registrazione del certificato è stata fornita senza una posizione.

Assicurati che ogni certificato nell'array includa una location secretsManager voce contenente una voce validasecretArn.

La configurazione dei certificati non è abilitata

La funzionalità dei certificati non è abilitata per il tuo account.

Contatta l' AWS assistenza per abilitare la funzionalità dei certificati per il tuo account.

Risoluzione dei problemi relativi ai proxy del browser

Errori all'avvio di una sessione con il proxy

Sintomo: StartBrowserSession restituisce un errore HTTP 400 con un messaggio che inizia conFailed to set up browser proxy:.

Causa: la configurazione del proxy o il segreto delle credenziali non sono validi.

Soluzione::

  • Proxy credentials secret not found in Secrets Manager— L'ARN segreto non corrisponde a nessun segreto nell'account e nella regione di destinazione. Verifica che l'ARN sia corretto e che il segreto non sia stato eliminato o pianificato per l'eliminazione.

  • Invalid proxy credentials secret configuration (check encryption key for cross-account access)— Il segreto esiste ma non è accessibile. Assicurati che l'identità chiamante sia secretsmanager:GetSecretValue autorizzata. Per informazioni segrete su più account, vedi Accesso Cross-account segreto.

  • Proxy credentials secret must be a JSON object with username and password fields— Aggiorna il valore segreto in un oggetto JSON valido:. {"username": "…​", "password": "…​"}

  • Failed to parse proxy credentials from secret— Il valore segreto non può essere letto come credenziali proxy. Verifica che il segreto contenga una semplice stringa JSON (non binaria) con campi username epassword.

  • Field 'username' is missing or empty in secretoppureField 'password' is missing or empty in secret: assicurati che entrambi username password siano presenti e non vuoti nel segreto.

  • Field 'username' contains invalid charactersoppureField 'password' contains invalid characters: utilizza solo i caratteri elencati nel messaggio di errore. Vedi Passaggio 1: creazione di credenziali segrete (se si utilizza l'autenticazione) per i caratteri consentiti.

  • Field 'username' exceeds maximum length of 256 charactersoppureField 'password' exceeds maximum length of 256 characters: riduci la credenziale a 256 caratteri o meno.

Errori di connessione proxy nel browser

Sintomo: una sessione del browser viene avviata correttamente, ma la navigazione della pagina non riesce per i domini proxy con errori HTTP 502 o. net::ERR_INVALID_AUTH_CREDENTIALS

Causa: il browser non è in grado di connettersi al server proxy oppure il server proxy rifiuta le credenziali fornite. Si tratta di errori di rete di Chromium, non di errori API. AWS

Soluzione::

  • HTTP 502 nelle pagine proxy: verifica il nome host e la porta del proxy e che il server sia funzionante e raggiungibile dalla rete Internet pubblica (o dal tuo VPC se utilizzi la configurazione VPC).

  • net::ERR_INVALID_AUTH_CREDENTIALS— Aggiorna il segreto in Secrets Manager con credenziali valide per il server proxy.

  • GetBrowserSessionUsalo per confermare le impostazioni del proxy attivo. Le credenziali non vengono mai restituite nella risposta.

Nota

Questi errori sono visibili in Live View e tramite l'API di automazione.

Risoluzione dei problemi relativi alle azioni del InvokeBrowser sistema operativo

La tabella seguente descrive gli errori più comuni quando si utilizza l' InvokeBrowser API per le azioni OS-level del browser.

Eccezione Codice HTTP Description

ValidationException

400

Input non valido. Per le azioni basate sulle coordinate (mouseClick,,,mouseScroll) mouseMovemouseDrag, le coordinate devono rientrare rigorosamente nei limiti della finestra della sessione (1 < x < viewportWidth-2, 1 < y < viewport). Height-2 La dimensione predefinita della finestra è 1456×819 pixel. Viene restituita anche per azioni disattivate o valori di parametro non validi.

AccessDeniedException

403

Autorizzazioni insufficienti o azione non consentita per la sessione.

ResourceNotFoundException

404

Non valido obrowserIdentifier. sessionId

ServiceQuotaExceededException

402

La quota di servizio è stata superata.

ThrottlingException

429

Limite di tariffa superato.

InternalServerException

500

Errore imprevisto nell'esecuzione.

Soluzione::

  • Verificate che i valori delle coordinate rientrino nelle dimensioni della finestra della sessione. Utilizzate l'screenshotazione per catturare la schermata corrente e confermare l'area visibile.

  • Verifica che la sessione del browser sia ancora attiva e non sia scaduta.

  • Assicurati che la tua identità IAM disponga dell'bedrock-agentcore:InvokeBrowserautorizzazione.