Solución de problemas de implementación directa de código

Problemas y soluciones habituales al empezar con la implementación AgentCore directa de código en Amazon Bedrock. Para obtener más información sobre solución de problemas, consulte Solución de problemas de Amazon Bedrock Runtime AgentCore .

AccessDenied: Permisos de S3 insuficientes

Cuando esto ocurre: durante la creación del agente o la actualización con un artefacto comprimido en S3 mediante la consola, el SDK o la CLI

Por qué sucede esto: el rol utilizado para llamar Create/UpdateAgentRuntime no tiene s3: GetObject los permisos en el URI de S3 se transfieren a la entrada de la API.

Solución: agregue s3: GetObject permiso en el rol utilizado para llamar a la API Agentcore Runtime create/update .

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

AccessDenied: Acceso a objetos S3 cifrado por CMK

Cuando esto ocurre: durante la creación del agente con objetos CMK-encrypted S3, cuando la función de ejecución carece de permisos de descifrado del KMS.

Por qué ocurre esto: el rol utilizado para llamar Create/UpdateAgentRuntime no tiene permisos de KMS:Decrypt en la CMK utilizada para cifrar el objeto de S3 que contiene el código del agente.

Solución: añada el permiso KMS:Decrypt al rol de la 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: compatibilidad de paquetes de códigos

Cuando esto ocurre: durante la creación o actualización del agente con paquetes de códigos incompatibles (arquitectura, versión de idioma o formato de paquete incorrectos).

Por qué sucede esto: el archivo ZIP cargado contiene binarios compilados con una arquitectura incorrecta (ARM64 frente a x86_64), una versión de idioma incompatible o una estructura de paquete incorrecta que no cumple con los requisitos de tiempo de ejecución. AgentCore

Solución:

Para resolver este problema, siga estos pasos:

Indicadores de error:

Incompatibilidad binaria ARM64

Cuando esto ocurre: durante la creación del agente, cuando el ZIP contiene binarios nativos compilados para una arquitectura que no es ARM64.

Por qué sucede esto: AgentCore Runtime solo es compatible con la arquitectura del conjunto de instrucciones arm64. El servicio escanea todos los archivos binarios nativos del paquete de despliegue (.soarchivos para Python y ambos y .node archivos para Node.js ) .so y valida sus encabezados ELF para garantizar la compatibilidad con ARM64. Si se compila algún binario para x86_64, macOS (Mach-O) u otra arquitectura, se produce un error en la validación.

Solución:

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

Falta el punto de entrada

Cuando esto ocurre: durante la creación del agente, cuando el archivo de punto de entrada especificado no existe en el ZIP.

Por qué ocurre esto: la ruta del archivo de punto de entrada que especificó en la entryPoint configuración no coincide con ningún archivo del paquete de despliegue. Esto puede ocurrir si el archivo no estaba incluido en el ZIP, si la ruta está mal escrita o si la estructura del ZIP es diferente de lo esperado.

Solución:

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

Node.js Declaración de engines.node incompatible

Cuando esto ocurre: durante la creación del Node.js agente, cuando su dependencia package.json o una dependencia común declara un engines.node rango que excluye la versión de destino. Node.js

Por qué sucede esto: AgentCore Runtime comprueba el engines.node campo en la raíz package.json y en las dependencias comunes. Si el rango de versiones excluye la versión de destino (por ejemplo, <18 o si >=14 <18 se implementa en la Node.js versión Node.js 22), se produce un error al crear el agente.

Solución:

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

Node.js Falta el paquete OTEL

Cuando esto ocurre: durante la creación del Node.js agente, cuando se especifica opentelemetry-instrument en el punto de entrada, pero el paquete ADOT no está incluido en el ZIP.

Por qué sucede esto: cuando lo usas"entryPoint": ["opentelemetry-instrument", "app.js"], AgentCore Runtime espera que el paquete @aws/aws-distro-opentelemetry-node-autoinstrumentation npm esté presente node_modules/ en tu paquete de despliegue.

Solución:

Instale el paquete ADOT antes de empaquetar el ZIP:

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

Como alternativa, elimina el opentelemetry-instrument prefijo de tu punto de entrada si no necesitas la instrumentación automática.

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