Résolution des problèmes liés au déploiement direct du code

Problèmes courants et solutions lors de la prise en main du déploiement AgentCore direct du code Amazon Bedrock. Pour plus d'informations sur le dépannage, consultez Résoudre les problèmes liés à Amazon Bedrock Runtime AgentCore .

AccessDenied: autorisations S3 insuffisantes

Lorsque cela se produit : lors de la création ou de la mise à jour de l'agent avec un artefact compressé dans S3 via une console, un SDK ou une CLI

Pourquoi cela se produit : le rôle utilisé pour appeler Create/UpdateAgentRuntime ne dispose pas des GetObject autorisations s3 : sur l'uri S3 transmis dans l'entrée de l'API.

Solution : ajoutez l'GetObject autorisation s3 : dans le rôle utilisé pour appeler l' create/update API Agentcore Runtime.

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

AccessDenied: accès aux objets S3 chiffré par CMK

Lorsque cela se produit : lors de la création de l'agent avec des objets CMK-encrypted S3 lorsque le rôle d'exécution ne dispose pas des autorisations de déchiffrement KMS.

Pourquoi cela se produit : le rôle utilisé pour appeler Create/UpdateAgentRuntime ne dispose pas des autorisations KMS:Decrypt sur le CMK utilisé pour chiffrer l'objet S3 contenant le code de l'agent.

Solution : ajoutez l'autorisation KMS:Decrypt au rôle pour le CMK spécifique :

{
"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 : compatibilité des packages de code

Lorsque cela se produit : lors de la création ou de la mise à jour de l'agent avec des packages de code incompatibles (architecture, version linguistique ou format de package incorrects).

Pourquoi cela se produit : le fichier ZIP téléchargé contient des fichiers binaires compilés pour une architecture incorrecte (ARM64 contre x86_64), une version linguistique incompatible ou une structure de package incorrecte qui ne correspond pas aux exigences d'exécution. AgentCore

Solution :

Pour résoudre ce problème :

Indicateurs d'erreur :

Incompatibilité binaire ARM64

Quand cela se produit : lors de la création de l'agent, lorsque votre fichier ZIP contient des fichiers binaires natifs compilés pour une architecture autre que ARM64.

Pourquoi cela se produit : AgentCore Runtime ne prend en charge que l'architecture du jeu d'instructions arm64. Le service analyse tous les fichiers binaires natifs de votre package de déploiement (.sofichiers pour Python et les deux .so et .node fichiers pour Node.js ) et valide leurs en-têtes ELF pour vérifier leur compatibilité avec ARM64. Si un binaire est compilé pour x86_64, macOS (Mach-O) ou une autre architecture, la validation échoue.

Solution :

Indicateur d'erreur : "Your artifact contains binary files that are incompatible with Linux ARM64."

Point d'entrée manquant

Lorsque cela se produit : lors de la création de l'agent, lorsque le fichier de point d'entrée spécifié n'existe pas dans votre fichier ZIP.

Pourquoi cela se produit : Le chemin du fichier du point d'entrée que vous avez spécifié dans la entryPoint configuration ne correspond à aucun fichier du package de déploiement. Cela peut se produire si le fichier n'a pas été inclus dans le fichier ZIP, si le chemin est mal orthographié ou si la structure du fichier ZIP est différente de ce que vous attendiez.

Solution :

Indicateur d'erreur : "The specified entrypoint could not be found or accessed in your artifact."

Node.js Déclaration engines.node incompatible

Lorsque cela se produit : lors de la création de l' Node.js agent, lorsque votre dépendance package.json ou une dépendance commune déclare une engines.node plage excluant la Node.js version cible.

Pourquoi cela se produit : AgentCore Runtime vérifie le engines.node champ dans votre racine package.json et dans les dépendances courantes. Si la plage de versions exclut la Node.js version cible (par exemple, <18 ou >=14 <18 lors du déploiement vers Node.js 22), la création de l'agent échoue.

Solution :

Indicateur d'erreur : "Your artifact contains dependencies with engines.node declarations incompatible with the target Node.js version."

Node.js Package OTEL manquant

Lorsque cela se produit : lors de la création de Node.js l'agent, lorsque vous spécifiez opentelemetry-instrument dans le point d'entrée mais que le package ADOT n'est pas inclus dans le fichier ZIP.

Pourquoi cela se produit : lorsque vous utilisez"entryPoint": ["opentelemetry-instrument", "app.js"], AgentCore Runtime s'attend à ce que le package @aws/aws-distro-opentelemetry-node-autoinstrumentation npm soit présent node_modules/ dans votre package de déploiement.

Solution :

Installez le package ADOT avant d'emballer votre ZIP :

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

Vous pouvez également supprimer le opentelemetry-instrument préfixe de votre point d'entrée si vous n'avez pas besoin d'une instrumentation automatique.

Indicateur d'erreur : "OpenTelemetry instrumentation executable not found. The ZIP file requires open-telemetry dependencies, but none are present."