Solução de problemas de implantação direta de código

Problemas e soluções comuns ao começar a usar a implantação AgentCore direta de código do Amazon Bedrock. Para obter mais informações sobre solução de problemas, consulte Solucionar problemas do Amazon Bedrock AgentCore Runtime.

AccessDenied: Permissões S3 insuficientes

Quando isso ocorre: durante a criação ou atualização do agente com artefato compactado no S3 via console, SDK ou CLI

Por que isso acontece: a função usada para chamar Create/UpdateAgentRuntime não tem GetObject permissões s3: no uri do S3 transmitidas na entrada da API.

Solução: adicione a GetObject permissão s3: na função usada para chamar a API Agentcore Runtime. create/update

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

AccessDenied: acesso a objetos S3 criptografados por CMK

Quando isso ocorre: durante a criação do agente com objetos do CMK-encrypted S3, quando a função de execução não tem permissões de descriptografia do KMS.

Por que isso acontece: a função usada para chamar Create/UpdateAgentRuntime não tem permissões kms:Decrypt na CMK usada para criptografar o objeto S3 que contém o código do agente.

Solução: adicione a permissão kms:Decrypt à função da CMK específica:

{
"Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": [
            "s3:GetObject",
            "kms:Decrypt"
        ],
        "Resource": [
            "arn:aws:s3:::your-bucket-name/*",
            "arn:aws:kms:us-west-2:your-account:key/your-cmk-key-id"
        ]
    }
  ]
}

CREATE_FAILED: compatibilidade de pacotes de código

Quando isso ocorre: durante a criação ou atualização do agente com pacotes de código incompatíveis (arquitetura, versão do idioma ou formato do pacote incorretos).

Por que isso acontece: o arquivo ZIP carregado contém binários compilados para arquitetura incorreta (ARM64 versus x86_64), versão de linguagem incompatível ou estrutura de pacote incorreta que não atende aos requisitos do Runtime. AgentCore

Solução:

Para resolver esse problema:

1. Certifique-se de que o código seja compilado para arm64.

2. Use a versão de idioma compatível (marque Versões suportadas pelo AgentCore Runtime).

3. Verifique se a estrutura ZIP contém pontos de entrada e dependências adequados.

4. Reconstrua pacotes em um ambiente de tempo de execução compatível.

Indicadores de erro:

• Status do agente: CREATE_FAILED ou erros de tempo de execução

• Importe erros ou mensagens de “não é possível executar o arquivo binário” nos logs do cloudwatch

• Erros de incompatibilidade de arquitetura quando você obtémAgentRuntimeEndpoint.

Incompatibilidade binária ARM64

Quando isso ocorre: durante a criação do agente, quando seu ZIP contém binários nativos compilados para uma arquitetura não ARM64.

Por que isso acontece: o AgentCore Runtime suporta apenas a arquitetura do conjunto de instruções arm64. O serviço verifica todos os arquivos binários nativos em seu pacote de implantação — .so arquivos para Python e .so ambos .node e arquivos para — e valida seus cabeçalhos ELF Node.js para compatibilidade com ARM64. Se algum binário for compilado para x86_64, macOS (Mach-O) ou outra arquitetura, a validação falhará.

Solução:

• Python: use uv pip install --python-platform aarch64-manylinux2014 --only-binary=:all: para baixar rodas compatíveis com arm64.

• Node.js: instale módulos nativos em uma máquina arm64 ou usenpm install --arch=arm64 --platform=linux.

• Como alternativa, crie suas dependências em uma instância do AWS Graviton-based Amazon EC2 para garantir a compatibilidade com arm64.

Indicador de erro: "Your artifact contains binary files that are incompatible with Linux ARM64."

Ponto de entrada ausente

Quando isso ocorre: durante a criação do agente, quando o arquivo do ponto de entrada especificado não existe em seu ZIP.

Por que isso acontece: O caminho do arquivo do ponto de entrada que você especificou na entryPoint configuração não corresponde a nenhum arquivo no pacote de implantação. Isso pode acontecer se o arquivo não tiver sido incluído no ZIP, se o caminho estiver escrito incorretamente ou se a estrutura do ZIP for diferente do esperado.

Solução:

• Verifique se o arquivo do ponto de entrada existe no seu ZIP: unzip -l deployment_package.zip | grep app.js

• Certifique-se de que o caminho de entryPoint entrada corresponda ao caminho do arquivo dentro do ZIP (incluindo quaisquer subdiretórios como src/app.js ou) dist/index.js

• Para agentes Python, o ponto de entrada deve terminar com.py; para Node.js agentes, deve terminar com .js

Indicador de erro: "The specified entrypoint could not be found or accessed in your artifact."

Node.js Declaração de engines.node incompatíveis

Quando isso ocorre: durante a criação do Node.js agente, quando sua dependência package.json ou uma dependência comum declara um engines.node intervalo que exclui a versão de destino. Node.js

Por que isso acontece: o AgentCore Runtime verifica o engines.node campo na raiz package.json e nas dependências comuns. Se o intervalo de versões excluir a Node.js versão de destino (por exemplo, <18 ou >=14 <18 ao implantar até Node.js 22), a criação do agente falhará.

Solução:

• Atualize o engines.node campo em seu package.json para incluir a Node.js versão de destino (por exemplo,">=18")

• Atualize todas as dependências incompatíveis para uma versão compatível com a versão de destino Node.js

• Remova o engines campo se não for necessário

Indicador de erro: "Your artifact contains dependencies with engines.node declarations incompatible with the target Node.js version."

Node.js Pacote OTEL ausente

Quando isso ocorre: durante a criação do Node.js agente, quando você especifica opentelemetry-instrument no ponto de entrada, mas o pacote ADOT não está incluído no ZIP.

Por que isso acontece: Quando você usa"entryPoint": ["opentelemetry-instrument", "app.js"], o AgentCore Runtime espera que o pacote @aws/aws-distro-opentelemetry-node-autoinstrumentation npm esteja presente node_modules/ em seu pacote de implantação.

Solução:

Instale o pacote ADOT antes de empacotar seu ZIP:

npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
zip -r deployment_package.zip app.js node_modules/ package.json

Como alternativa, remova o opentelemetry-instrument prefixo do seu ponto de entrada se você não precisar de instrumentação automática.

Indicador de erro: "OpenTelemetry instrumentation executable not found. The ZIP file requires open-telemetry dependencies, but none are present."