As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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. Ao seguir essas soluções, você pode diagnosticar e corrigir problemas rapidamente com os tempos de execução do seu agente.

As invocações do meu 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 versão 2). O serviço rejeita invocações direcionadas a tempos de execução sem definição ou com metadataConfiguration definido como ou. requireMMDSV2 false null

Solução: Ligue UpdateAgentRuntime com requireMMDSV2 set to true inmetadataConfiguration:

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.

As invocações do meu 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 de base do Python

Quando isso ocorre: Durante docker build ou docker run ao usar imagens public.ecr.aws de base

Por que isso acontece: Problemas de autenticação pública do ECR — 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 “Serviço desconhecido: '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 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 corretamente 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 a implantação do Amazon Bedrock AgentCore

Por que isso acontece: Construindo contêineres ARM64 em sistemas x86 sem a configuração adequada entre 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. Para obter um exemplo de código, consulte os AgentCore exemplos do Amazon Bedrock.

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 execução com o Amazon Bedrock AgentCore Runtime para obter detalhes 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 elegível para inatividade e seu tempo de inatividade é 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 Bedrock AgentCore SDK, 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,ServiceQuotaExceededException//maxVmserros 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 inativa do 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 definir time_of_last_update 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. Em seguida, as sessões ficam MaxLifetime ativas até esgotar sua cota de sessões.

Solução: atualize time_of_last_update somente quando status realmente mudar ou omita totalmente para que a plataforma acompanhe as mudanças de status sozinha:

{"status": "Healthy"}

Se você estiver usando o Bedrock AgentCore SDK, atualize para a versão mais recente, na qual a resposta do 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-a a partir da solicitação recebida e use-a para marcação, correlação ou propagação posterior.

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

Tenho RuntimeClientError (403) problemas

Problema

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

Causas

Esse erro normalmente 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êiner

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 problemas com agentes do protocolo MCP

Para agentes do 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 MCP Inspector

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:

Verificar a configuração do endpoint

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

Teste localmente com complexidade incremental

Comece com um teste local simples antes de implantar:

Problemas de autenticação

Verifique a configuração de autenticação para 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 um 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é que a sessão seja encerrada, mesmo quando os ativos do código são atualizados como parte da execução da UpdateAgentRuntime operação.

Solução

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

Os intervalos estão ausentes quando meu tempo de execução é invocado a partir de uma função do Lambda

Quando isso ocorre: ao invocar o AgentCore Runtime a partir de uma função do 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 de span para essa invocação.

Solução:

Meus arquivos S3 ou montagem do EFS falham 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 do 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 só precisa de acesso de leitura.

Meus arquivos S3 ou 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 o ponto de acesso foi excluído após a criação do agente ou os IDs estão incorretos.

Solução:

Meus arquivos S3 ou montagem EFS atingem o tempo limite

Quando isso ocorre: Durante a invocação de um agente com arquivos S3 ou armazenamento EFS configurado. A invocação pode levar mais tempo 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” quando escrevo no meu sistema de arquivos montado

Quando isso ocorre: a invocação do agente é bem-sucedida e o agente pode ler 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 definido durante a criação do ponto de acesso não permitem gravações para o usuário do agente.

Solução:

Meu contêiner falha ao iniciar com o erro HTTP 424 em imagens de alta camada

Quando isso ocorre: suas InvokeAgentRuntime chamadas retornam HTTP 424 (dependência com falha) e os registros do seu agente são exibidos. Failed to mount overlay: No such file or directory Isso ocorre quando sua imagem de 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 várias camadas combinadas com diretivas USER não numéricas podem causar falhas na inicialização.

Solução: use uma das seguintes soluções alternativas:

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

Meu provedor de capacidade está no estado CREATE_FAILED

Quando isso ocorre: depois que você chama o tipo CreateCapacityProvider de computação Instances, o provedor de capacidade não alcança ACTIVE e, em vez disso, entraCREATE_FAILED.

Por que isso acontece: um provedor de capacidade depende de vários recursos (como um modelo de lançamento e um grupo de Auto Scaling) que a função de operador do provedor de capacidade deve ser capaz de criar. A falta de permissões nessa função leva a uma falha na criação.

Solução: chame a GetCapacityProvider API para recuperar o motivo da falha no statusReason campo. O statusReason identifica os recursos que falharam na criação. Conceda à função de operador do provedor de capacidade as permissões necessárias para criar esses recursos e, em seguida, crie o provedor de capacidade novamente. Para obter mais informações sobre a função do operador, consulte Modelo de segurança e permissões para instâncias de tempo de execução.

Meus agentes nas Instâncias não têm acesso às suas credenciais

Quando isso ocorre: um agente em execução em uma sessão de instâncias não consegue obter as credenciais necessárias para ligar para os AWS serviços.

Por que isso acontece: A função de execução de tempo de execução está ausente ou não pode ser assumida por AgentCore.

Solução: Certifique-se de que a função de execução que você configurou para seu tempo de execução exista e permita bedrock-agentcore.amazonaws.com a chamadasts:AssumeRole. Para obter mais informações, consulte permissões para a função de execução do Amazon Bedrock AgentCore Runtime.

Práticas recomendadas

Habilite o registro abrangente

Implemente um registro completo em seu agente:

Use o tratamento estruturado de erros

Implemente relatórios de erros claros:

Teste mudanças incrementais

Siga uma abordagem metódica de teste:

Monitore o desempenho

Configure o monitoramento para seu agente: