Solucionar problemas de tempo de execução AgentCore

Este tópico de solução de problemas ajuda você a identificar e resolver problemas comuns ao trabalhar com o AgentCore Runtime. Seguindo essas soluções, você pode rapidamente diagnosticar e corrigir problemas com os tempos de execução do seu agente.

Minhas invocações de agente falham com “Este tempo de execução não é” MMDSv2-enabled ValidationException

Quando isso ocorre: ao invocar o tempo de execução de um agente por meio de InvokeAgentRuntimeExecuteCommand,InvokeAgentRuntimeWithWebSocketStream,InvokeAgentRuntimeCommandShell, ou GetAgentCard

Por que isso acontece: a partir de 30 de junho de 2026, o Amazon Bedrock AgentCore Runtime exige que todos os tempos de execução do agente usem o MMDSv2 (MicroVM Metadata Service Version 2). O serviço rejeita invocações direcionadas a tempos de execução sem metadataConfiguration set ou com set to ou. requireMMDSV2 false null

Solução: Ligue UpdateAgentRuntimecom requireMMDSV2 definido como true emmetadataConfiguration:

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

Depois da atualização, as novas invocações serão bem-sucedidas. As sessões existentes não são afetadas.

Minhas invocações de agente falham com erros 504 Gateway Timeout

Quando isso ocorre: durante a invocação do agente via SDK ou console

Por que isso acontece: vários fatores podem impedir que seu agente responda dentro do período de tempo limite

Vários fatores podem causar isso:

Minha compilação do Docker falha com “403 Forbidden” ao extrair imagens básicas do Python

Quando isso ocorre: durante docker build ou docker run ao usar imagens public.ecr.aws básicas

Por que isso acontece: Problemas de autenticação pública do ECR — a autenticação expirada ou ausente é um problema comum.

Solução: faça login no ECR Public ou saia completamente:

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

Eu recebo o erro “Unknown service: 'bedrock-agent-core-runtime'” ao usar o boto3

Quando isso ocorre: ao invocar as AgentCore APIs do Amazon Bedrock usando o SDK boto3

Por que isso acontece: Biblioteca boto3 desatualizada — problema comum, pois a maioria das instalações não tem o SDK mais recente

Solução: atualize para as versões mais recentes do boto3 e do botocore:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Eu recebo "AccessDeniedException" ao tentar criar um Amazon Bedrock AgentCore Runtime

Quando isso ocorre: durante a criação do agente via console, SDK ou CLI

Por que isso acontece: Ou seu usuário não tem permissões ou a função de execução não está configurada adequadamente para o Amazon Bedrock AgentCore

Solução: Vários fatores podem causar isso:

Minha compilação do Docker falha com “erro de formato exec/bin/sh: exec”

Quando isso ocorre: Ao criar contêineres para implantação do Amazon Bedrock AgentCore

Por que isso acontece: Construindo contêineres ARM64 em sistemas x86 sem a configuração adequada de várias plataformas

Solução: Crie contêineres compatíveis com ARM64. Você pode considerar o uso de buildx para compilações multiplataforma. Como alternativa, você pode usar CodeBuild. Por exemplo de código, consulte Amazon Bedrock AgentCore Samples.

Quais são os requisitos para contêineres Docker usados com o Amazon Bedrock AgentCore Runtime?

Consulte os requisitos do Amazon Bedrock AgentCore Runtime para obter detalhes completos.

Em resumo, seu contêiner Docker deve atender aos seguintes requisitos:

Minha ferramenta de longa duração é interrompida após 15 minutos

Para obter informações, consulte Gerenciar agentes assíncronos e de longa duração com o Amazon Bedrock Amazon Bedrock Runtime para obter detalhes AgentCore completos.

Quando isso ocorre: durante operações de agentes de longa duração ou fluxos de trabalho complexos

Por que isso acontece: o Amazon Bedrock encerra AgentCore automaticamente as sessões após 15 minutos de inatividade. A plataforma determina a atividade a partir da /ping resposta: um relatório de sessão HealthyBusy é mantido ativo, enquanto um relatório de sessão Healthy é tratado como inativo e seu tempo ocioso é medido a partir da status última alteração (veja o time_of_last_update campo abaixo).

Solução: garanta que seu /ping endpoint retorne HealthyBusy enquanto o trabalho em segundo plano estiver em andamento:

{"status": "HealthyBusy"}

Se você estiver usando o AgentCore SDK do Bedrock, a resposta do ping será tratada automaticamente. Para implementações personalizadas, garanta que seu manipulador de ping retorne HealthyBusy durante o processamento.

Minhas sessões inativas não estão sendo liberadas e estou esgotando minha cota de sessões

Quando isso ocorre: a contagem de sessões aumenta continuamente sob carga e as sessões não são liberadas após o tempo limite de inatividade (por exemplo, maxVms errosServiceQuotaExceededException/durante uma explosão de invocações), mesmo que cada sessão esteja ociosa.

Por que isso acontece: quando uma sessão relataHealthy, a plataforma mede por quanto tempo ela ficou ociosa no time_of_last_update campo em sua /ping resposta, o que deve refletir quando a status última alteração foi feita. Se seu manipulador de ping for definido time_of_last_update para a hora atual em cada ping, o tempo de inatividade relatado continuará sendo redefinido, o que evita que o tempo limite de inatividade seja acionado. As sessões então duram até MaxLifetime e podem esgotar sua cota de sessões.

Solução: atualize time_of_last_update somente quando o status status realmente mudar ou omita-o completamente para que a plataforma acompanhe as alterações de status sozinha:

{"status": "Healthy"}

Se você estiver usando o AgentCore SDK do Bedrock, atualize para a versão mais recente, na qual a resposta de ping é tratada corretamente. Como um paliativo, a chamada StopRuntimeSession libera sessões paralisadas.

Como faço para acessar o tempo de execução SessionId no código do meu agente para marcar ou agrupar recursos?

Quando isso se aplica: você deseja agrupar, marcar ou rastrear recursos (por exemplo, objetos do S3, registros) pela sessão de tempo de execução do agente atual.

Soluções:

Solução 1: Para agentes que usam o Bedrock Amazon Bedrock AgentCore SDK, use a context.session_id partir do ponto de entrada do seu agente

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

Solução 2: Para servidores HTTP de tempo de execução personalizados

O ID da sessão de tempo de execução é passado nesse cabeçalho HTTP. Analise-o a partir da solicitação recebida e use-o para marcação, correlação ou propagação posterior.

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

Eu tenho RuntimeClientError (403) problemas

Problema

Você recebe um erro 403 "RuntimeClientError" ao tentar invocar o tempo de execução do agente.

Causas

Esse erro geralmente ocorre devido a:

Resolução

Siga estas etapas para resolver o problema:

Tenho CloudWatch registros ausentes ou vazios

Problema

Você encontra erros, mas não vê nenhum login relevante CloudWatch.

Solução

Experimente estas abordagens para diagnosticar o problema:

Tenho problemas de formato de carga

Problema

A invocação do tempo de execução do agente falha mesmo que o contêiner seja iniciado com êxito.

Resolução

Siga estas etapas para resolver problemas de formato de carga útil:

Preciso de ajuda para entender os códigos de erro HTTP

Problema

Seu agente retorna códigos de erro HTTP que são difíceis de interpretar.

Exemplo de mensagem de erro

Você pode ver um erro como:

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

Resolução

Aqui estão os códigos de erro mais comuns e seus significados:

Preciso de recomendações para testar meu agente

Para depurar sistematicamente os problemas de tempo de execução do agente:

Teste localmente primeiro

Antes de implantar no AgentCore Runtime:

Compare cargas úteis

Garanta a consistência entre os ambientes:

Preciso de ajuda para depurar problemas de contêineres

Se você suspeitar de problemas relacionados ao contêiner:

Puxe e execute localmente

Teste a imagem do contêiner em sua máquina local:

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

Teste com curl

Envie solicitações de teste para seu contêiner local:

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

Verifique os registros do contêiner

Examine a saída do contêiner em busca de erros:

docker logs <container-id>

Preciso de ajuda para solucionar os agentes do protocolo MCP

Para agentes de protocolo MCP, siga estas etapas específicas de solução de problemas:

Verifique o caminho do endpoint

Os servidores MCP devem ouvir 0.0.0.0:8000/mcp/

Use o Inspector MCP

Teste com a ferramenta MCP Inspector:

Problemas de autenticação

Verifique a configuração de autenticação:

Preciso de ajuda para solucionar problemas de streaming bidirecional usando WebSocket

Para streaming bidirecional usando WebSocket agentes, siga estas etapas específicas de solução de problemas:

Verifique a configuração do endpoint

WebSocket os agentes devem ser executados na porta 8080 e atender WebSocket conexões no caminho /ws

Teste localmente com complexidade incremental

Comece com testes locais simples antes de implantar:

Problemas de autenticação

Verifique a configuração de autenticação dos agentes implantados:

Problemas comuns de conexão

Resolva problemas comuns de WebSocket conexão:

Minhas alterações de código não são refletidas nas sessões existentes

Problema

Você atualizou o tempo de execução do agente com o novo código, mas as sessões existentes continuam usando a versão antiga.

Por que isso acontece

Cada sessão de microVM é criada com os ativos de código (agentRuntimeArtifact) que foram implantados no momento da criação da sessão. Depois que uma sessão é estabelecida, ela continua usando essa versão do código até o término da sessão, mesmo quando os ativos do código são atualizados como parte da execução da UpdateAgentRuntimeoperação.

Solução

Para acessar seu código atualizado, use um novo ID de sessão.

Faltam extensões quando meu tempo de execução é invocado a partir de uma função Lambda

Quando isso ocorre: ao invocar o AgentCore Runtime a partir de uma função Lambda

Por que isso acontece: o Lambda gera seu próprio X-Amzn-Trace-Id cabeçalho. Se o rastreamento do Lambda tiverSampled=0, esse contexto sem amostra se propagará para o AgentCore Runtime e o tempo de execução ignorará a geração do intervalo para essa invocação.

Solução:

Minha montagem de arquivos S3 ou EFS falha com “Acesso negado”

Quando isso ocorre: Durante a invocação de um agente com arquivos S3 ou armazenamento EFS configurado

Por que isso acontece: A função de execução não tem as permissões necessárias do sistema de arquivos. Para obter mais informações sobre como configurar o armazenamento persistente, consulte Configurações do sistema de arquivos para AgentCore o Runtime.

Solução:

Para arquivos S3, certifique-se de que sua função de execução tenha:

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Para o EFS, certifique-se de que sua função de execução tenha:

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Omita s3files:ClientWrite ou elasticfilesystem:ClientWrite se seu agente precisar apenas de acesso de leitura.

Meus arquivos S3 ou a montagem do EFS falham com "” ResourceNotFound

Quando isso ocorre: Durante a invocação de um agente com arquivos S3 ou armazenamento EFS configurado

Por que isso acontece: o sistema de arquivos ou ponto de acesso foi excluído após a criação do agente ou as IDs estão incorretas.

Solução:

O tempo limite de montagem dos meus arquivos S3 ou EFS é esgotado

Quando isso ocorre: Durante a invocação de um agente com arquivos S3 ou armazenamento EFS configurado. A invocação pode demorar mais do que o normal antes de falhar.

Por que isso acontece: a configuração da rede VPC está bloqueando o tráfego NFS (porta 2049) entre a computação do agente e os destinos de montagem do sistema de arquivos.

Solução:

Eu recebo “Permissão negada” ao gravar no meu sistema de arquivos montado

Quando isso ocorre: a invocação do agente é bem-sucedida e o agente pode ler os arquivos da montagem, mas a gravação falha com “Permissão negada”

Por que isso acontece: Ou a função do IAM não tem permissões de gravação ou as permissões POSIX no diretório definidas durante a criação do ponto de acesso não permitem gravações para o usuário do agente.

Solução:

Meu contêiner não inicia com o erro HTTP 424 em imagens de alta camada

Quando isso ocorre: suas InvokeAgentRuntime chamadas retornam HTTP 424 (Falha na dependência) e os registros do seu agente são exibidos. Failed to mount overlay: No such file or directory Isso ocorre quando a imagem do contêiner tem mais de 53 camadas E usa uma diretiva USER não numérica (por exemplo, USER myuser em vez deUSER 1000).

Por que isso acontece: imagens de contêiner com muitas camadas combinadas com diretivas USER não numéricas podem causar falhas de inicialização.

Solução: use uma destas soluções alternativas:

docker inspect <image> | jq '.[0].RootFS.Layers | length'

Práticas recomendadas

Permita um registro abrangente

Implemente um login completo em seu agente:

Use tratamento estruturado de erros

Implemente um relatório claro de erros:

Teste mudanças incrementais

Siga uma abordagem de teste metódico:

Monitore o desempenho

Configure o monitoramento para seu agente: