Erros de permissão negada Acesso ao modelo negado Tempo limite da sessão do navegador A gravação não aparece no Amazon S3 Erros de conexão do dramaturgo O agente não pode progredir devido às verificações de CAPTCHA Erros de CORS ao integrar com aplicativos de navegador O Session Replay e o Web Bot Auth não funcionam em novas janelas ou contextos do navegador Problemas com extensões do navegador Problemas com o perfil do navegador Solução de problemas da Autoridade Certificadora Raiz Solução de problemas de proxies de navegador Solução de problemas de ações do InvokeBrowser SO

Solucionar problemas do navegador AgentCore

Esta seção fornece soluções para problemas comuns que você pode encontrar ao usar o AgentCore navegador Amazon Bedrock.

Erros de permissão negada

Sintoma: Erros mencionando acesso negado ou permissões insuficientes.

Solução:

Verifique se seu usuário ou função do IAM tem as permissões de navegador necessárias
Verifique suas AWS credenciais: aws sts get-caller-identity
Para gravação: verifique se a função de execução tem permissões de gravação no Amazon S3
Para gravação: Confirme se a política de confiança bedrock-agentcore.amazonaws.com permite assumir a função

Acesso ao modelo negado

Sintoma: Erros sobre o acesso ou autorização do modelo ao executar agentes.

Solução:

Navegue até o console Amazon Bedrock
Vá para Acesso ao modelo na navegação à esquerda
Ative o Anthropic Claude Sonnet 4
Verifique se você está na região correta (corresponda à região em seu código)

Tempo limite da sessão do navegador

Sintoma: as sessões do navegador terminam inesperadamente ou ocorrem erros de tempo limite.

Solução:

Verifique o sessionTimeoutSeconds parâmetro ao iniciar as sessões
O tempo limite padrão é 900 segundos (15 minutos)
Aumente o tempo limite para sessões mais longas: sessionTimeoutSeconds=1800
As sessões são interrompidas automaticamente após o período de tempo limite

A gravação não aparece no Amazon S3

Sintoma: Não há arquivos de gravação em seu bucket do Amazon S3 após a conclusão da sessão.

Solução:

Verifique se a função de execução tem as permissões corretas do Amazon S3
Confirme se o nome e o prefixo do bucket do Amazon S3 estão corretos
Verifique se a política de confiança da função de execução inclui o serviço Bedrock-agentcore
Revise CloudWatch os registros de erros de upload do Amazon S3
Certifique-se de que a sessão foi executada por pelo menos alguns segundos (sessões muito curtas podem não gerar gravações)

Erros de conexão do dramaturgo

Sintoma: Não é possível conectar-se ao navegador com o Playwright ou WebSocket com erros.

Solução:

Verifique se você instalou o dramaturgo: pip install playwright
Confirme se a sessão do navegador foi iniciada com sucesso antes de se conectar
Verifique se a sessão ainda está ativa (não atingiu o tempo limite)
Verifique se sua rede permite WebSocket conexões

O agente não pode progredir devido às verificações de CAPTCHA

Problema: seu agente é bloqueado pela verificação CAPTCHA ao usar a ferramenta do navegador para interagir com sites.

Causa: Anti-bot medidas em sites populares detectam navegação automatizada e exigem verificação humana.

Solução: estruture seu agente para evitar mecanismos de pesquisa e implemente o seguinte padrão de arquitetura:

Use a ferramenta Navegador somente para ações específicas da página, não para pesquisas gerais na web
Use ferramentas MCP que não sejam do navegador, como a pesquisa Tavily, para operações gerais de pesquisa na web
Considere adicionar um recurso de visualização ao vivo ao seu aplicativo de agente que permita que os usuários finais assumam o controle e resolvam CAPTCHAs quando necessário.

Erros de CORS ao integrar com aplicativos de navegador

Problema: erros Cross-Origin de compartilhamento de recursos (CORS) ocorrem ao criar aplicativos web baseados em navegador que chamam um servidor de tempo de execução personalizado do Amazon Bedrock AgentCore .

Causa: as políticas de segurança do navegador bloqueiam solicitações de origem cruzada para seu servidor de tempo de execução durante o desenvolvimento local ou a implantação auto-hospedada.

Solução: adicione o middleware CORS ao seu para lidar com solicitações de origem cruzada do seu BedrockAgentCoreApp front-end:


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

Em ambientes de produção, substitua allow_origins= ["*"] por origens de domínio específicas para maior segurança.

O Session Replay e o Web Bot Auth não funcionam em novas janelas ou contextos do navegador

Problema: os recursos Session Replay e Web Bot Auth não estão disponíveis quando seu código de automação cria novas janelas ou contextos do navegador.

Causa: Esses recursos dependem de extensões de navegador que só funcionam no contexto padrão do navegador fornecido pelo Amazon Bedrock AgentCore. Quando você cria um novo contexto usando métodos como browser.new_context() no Playwright, as extensões não estão disponíveis.

Solução: use o contexto padrão do navegador fornecido ao se conectar à sessão do navegador. Evite criar novos contextos ou janelas se precisar da funcionalidade Session Replay ou 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()

Problemas com extensões do navegador

O download da extensão falha com o acesso negado

Sintoma: Falha ao iniciar a sessão com erros relacionados ao acesso ao Amazon S3 ao usar extensões.

Solução:

Verifique se seu usuário ou função do IAM tem s3:GetObject s3:GetObjectHead permissão no bucket de extensões
Confirme se o bucket do Amazon S3 pertence à mesma AWS conta que está fazendo a chamada de API
Verifique se o nome e o prefixo do bucket (chave do objeto) estão corretos
Se estiver usando buckets versionados, verifique se você tem permissão s3:GetObjectVersion

Extensão rejeitada devido a um formato inválido

Sintoma: Falha ao iniciar a sessão com erros de validação sobre o formato do arquivo de extensão.

Solução:

Verifique se o arquivo de extensão está no formato ZIP
Verifique se o arquivo ZIP contém uma estrutura de extensão válida do Chrome com um manifest.json arquivo válido
Verifique se a extensão segue as diretrizes de extensão do Chrome
Verifique se o ZIP foi criado a partir do conteúdo do diretório de extensão, não da pasta principal

Problemas com o perfil do navegador

Falha ao salvar o perfil da sessão do navegador devido à operação simultânea no perfil

Sintoma: SaveBrowserSessionProfile arremessos. ConflictException

Solução:

Tente novamente SaveBrowserSessionProfile mais tarde
Use o recuo exponencial com instabilidade se estiver tentando novamente a partir do agente ou do código

Falha ao salvar o perfil da sessão do navegador devido à operação simultânea na sessão

Sintoma: SaveBrowserSessionProfile arremessos. ConflictException

Solução:

Tente novamente SaveBrowserSessionProfile mais tarde
Use o recuo exponencial com instabilidade se estiver tentando novamente a partir do agente ou do código

A autenticação falha ao carregar um perfil de navegador salvo

Sintoma: Uma sessão do navegador carregada de um perfil salvo requer reautenticação, mesmo que o perfil tenha sido salvo com cookies de autenticação válidos.

Causa: Os cookies armazenados no perfil do navegador expiraram. Os sites definem prazos de expiração dos cookies (como tokens de autenticação), e o navegador remove automaticamente os cookies expirados de acordo com essas datas de expiração. Quando você carrega um perfil, os cookies que expiraram desde que o perfil foi salvo não estarão disponíveis.

Solução:

Re-authenticate na sessão do navegador para obter novos cookies
Salve o perfil novamente após a reautenticação para atualizá-lo com novos cookies
Para fluxos de trabalho que exigem autenticação de longo prazo, considere a vida útil típica dos cookies de seus sites de destino ao planejar o uso do perfil
Implemente a reautenticação periódica em seu fluxo de trabalho de automação se a expiração do cookie for esperada
Salve perfis com mais frequência para estados críticos de autenticação para minimizar o tempo entre o salvamento e o uso subsequente

nota

Os prazos de expiração dos cookies são definidos pelos sites e não podem ser modificados pelos perfis do navegador. Os cookies de sessão normalmente expiram quando a sessão do navegador termina, enquanto os cookies persistentes expiram com base em seus atributos Max-Age ou Expires.

Solução de problemas da Autoridade Certificadora Raiz

A tabela a seguir descreve erros comuns e suas resoluções ao configurar certificados CA raiz para o Amazon Bedrock AgentCore Browser.

Erro	Causa	Resolução
O segredo do certificado não foi encontrado no Secrets Manager	O ARN secreto não existe ou o segredo foi excluído.	Verifique se o ARN secreto está correto e se o segredo existe na região especificada.
Acesso negado ao certificado secreto no Secrets Manager	O chamador não tem `secretsmanager:GetSecretValue` permissão sobre o segredo.	Adicione a `secretsmanager:GetSecretValue` permissão à sua política do IAM para o ARN secreto especificado.
O conteúdo do certificado não é um PEM/X.509 formato válido	O valor secreto não é um PEM-encoded X.509 certificado válido.	Certifique-se de que o segredo contenha um certificado PEM formatado corretamente, começando com `-----BEGIN CERTIFICATE-----` e terminando com. `-----END CERTIFICATE-----`
O certificado expirou	A `notAfter` data do certificado está no passado.	Substitua o certificado expirado por um válido no AWS Secrets Manager e tente novamente.
O certificado ainda não é válido.	A `notBefore` data do certificado está no futuro.	Espere até que o período de validade do certificado comece ou use um certificado que seja válido no momento.
O número de certificados excede o máximo permitido	Mais de 10 certificados foram fornecidos no nível da sessão ou da ferramenta.	Reduza o número de certificados para 10 ou menos por sessão e 10 ou menos por ferramenta.
A localização do certificado é obrigatória	Uma entrada de certificado foi fornecida sem um local.	Certifique-se de que cada certificado na matriz inclua um `location` com uma `secretsManager` entrada contendo um válido`secretArn`.
A configuração de certificados não está habilitada	O recurso de certificados não está habilitado para sua conta.	Entre em contato com o AWS Support para ativar o recurso de certificados em sua conta.

Solução de problemas de proxies de navegador

Erros ao iniciar uma sessão com proxy

Sintoma: StartBrowserSession retorna um erro HTTP 400 com uma mensagem começando comFailed to set up browser proxy:.

Causa: A configuração do proxy ou o segredo das credenciais são inválidos.

Solução:

Proxy credentials secret not found in Secrets Manager— O ARN secreto não corresponde a nenhum segredo na conta e região de destino. Verifique se o ARN está correto e se o segredo não foi excluído ou programado para exclusão.
Invalid proxy credentials secret configuration (check encryption key for cross-account access)— O segredo existe, mas não pode ser acessado. Certifique-se de que a identidade da chamada tenha secretsmanager:GetSecretValue permissão. Para segredos entre contas, consulte acesso Cross-account secreto.
Proxy credentials secret must be a JSON object with username and password fields— Atualize o valor secreto para um objeto JSON válido:{"username": "…", "password": "…"}.
Failed to parse proxy credentials from secret— O valor secreto não pôde ser lido como credenciais de proxy. Verifique se o segredo contém uma string JSON simples (não binária) com password campos username e.
Field 'username' is missing or empty in secretou Field 'password' is missing or empty in secret — Certifique-se de que ambos username password estejam presentes e não vazios no segredo.
Field 'username' contains invalid charactersou Field 'password' contains invalid characters — Use somente os caracteres listados na mensagem de erro. Consulte a Etapa 1: Crie um segredo de credenciais (se estiver usando autenticação) para os caracteres permitidos.
Field 'username' exceeds maximum length of 256 charactersou Field 'password' exceeds maximum length of 256 characters — Reduza a credencial para 256 caracteres ou menos.

Erros de conexão de proxy no navegador

Sintoma: uma sessão do navegador é iniciada com êxito, mas a navegação da página falha em domínios proxy com erros HTTP 502 ou. net::ERR_INVALID_AUTH_CREDENTIALS

Causa: O navegador não consegue se conectar ao servidor proxy ou o servidor proxy rejeita as credenciais fornecidas. Esses são erros de rede do Chromium, não erros de AWS API.

Solução:

HTTP 502 em páginas com proxy — Verifique o nome do host do proxy, a porta e se o servidor está em execução e pode ser acessado pela Internet pública (ou pela VPC, se estiver usando a configuração da VPC).
net::ERR_INVALID_AUTH_CREDENTIALS— Atualize o segredo no Secrets Manager com credenciais válidas para o servidor proxy.
Use GetBrowserSession para confirmar as configurações de proxy ativas. As credenciais nunca são retornadas na resposta.

nota

Esses erros são visíveis no Live View e por meio da API de automação.

Solução de problemas de ações do InvokeBrowser SO

A tabela a seguir descreve erros comuns ao usar a InvokeBrowser API para ações OS-level do navegador.

Exceção	Código HTTP	Description
`ValidationException`	400	Entrada inválida. Para ações baseadas em coordenadas (`mouseClick`,,,`mouseScroll`) `mouseMovemouseDrag`, as coordenadas devem estar estritamente dentro dos limites da janela de visualização da sessão (1 < x < viewportWidth-2, 1 < y < viewport). Height-2 O tamanho padrão da janela de visualização é 1456 × 819 pixels. Também retornado para ações desativadas ou valores de parâmetros inválidos.
`AccessDeniedException`	403	Permissões ou ações insuficientes não permitidas para a sessão.
`ResourceNotFoundException`	404	Inválido `browserIdentifier` ou`sessionId`.
`ServiceQuotaExceededException`	402	A cota de serviço foi excedida.
`ThrottlingException`	429	Limite de taxa excedido.
`InternalServerException`	500	Falha inesperada na execução.

Solução:

Verifique se os valores das coordenadas estão dentro das dimensões da janela de exibição da sessão. Use a screenshot ação para capturar a tela atual e confirmar a área visível.
Verifique se a sessão do navegador ainda está ativa e não atingiu o tempo limite.
Certifique-se de que sua identidade do IAM tenha a bedrock-agentcore:InvokeBrowser permissão.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Ação do sistema operacional do navegador

AgentCore Observabilidade: observe seus agentes e recursos