Problembehandlung bei der direkten Codebereitstellung

Häufige Probleme und Lösungen bei den ersten Schritten mit der Bereitstellung von Amazon Bedrock AgentCore Direct Code. Weitere Informationen zur Fehlerbehebung finden Sie unter Problembehandlung bei Amazon Bedrock AgentCore Runtime.

AccessDenied: Unzureichende S3-Berechtigungen

In diesem Fall: Während der Agentenerstellung oder Aktualisierung mit komprimiertem Artefakt in S3 über Konsole, SDK oder CLI

Warum das passiert: Die zum Aufrufen verwendete Rolle Create/UpdateAgentRuntime hat keine s3: GetObject -Berechtigungen für die S3-URI, die in der API-Eingabe übergeben wurden.

Lösung: Fügen Sie der Rolle, die zum Aufrufen der Agentcore create/update Runtime-API verwendet wird, die GetObject Berechtigung s3: hinzu.

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

AccessDenied: CMK-verschlüsselter S3-Objektzugriff

In diesem Fall: Während der Agentenerstellung mit CMK-encrypted S3-Objekten, wenn der Ausführungsrolle die KMS-Entschlüsselungsberechtigungen fehlen.

Warum das passiert: Die zum Aufrufen verwendete Rolle Create/UpdateAgentRuntime hat keine kms:Decrypt-Berechtigungen für den CMK, der zum Verschlüsseln des S3-Objekts verwendet wird, das den Agentencode enthält.

Lösung: Fügen Sie der Rolle für den spezifischen CMK die Berechtigung kms:Decrypt hinzu:

{
"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: Kompatibilität des Codepakets

In diesem Fall: Während der Agentenerstellung oder Aktualisierung mit inkompatiblen Codepaketen (falsche Architektur, Sprachversion oder falsches Paketformat).

Warum das passiert: Die hochgeladene ZIP-Datei enthält Binärdateien, die für eine falsche Architektur (ARM64 oder x86_64), eine inkompatible Sprachversion oder eine falsche Paketstruktur kompiliert wurden, die nicht den Runtime-Anforderungen entspricht. AgentCore

Lösung:

So beheben Sie dieses Problem

Fehlerindikatoren:

Inkompatibilität mit ARM64-Binärdateien

In diesem Fall: Während der Agentenerstellung, wenn Ihre ZIP-Datei native Binärdateien enthält, die für eine Architektur außerhalb von ARM64 kompiliert wurden.

Warum das passiert: AgentCore Runtime unterstützt nur die arm64-Befehlssatzarchitektur. Der Dienst scannt alle nativen Binärdateien in Ihrem Bereitstellungspaket — .so Dateien für Python .so und beide sowie .node Dateien für Node.js — und validiert ihre ELF-Header auf ARM64-Kompatibilität. Wenn eine Binärdatei für x86_64, macOS (Mach-O) oder eine andere Architektur kompiliert wurde, schlägt die Validierung fehl.

Lösung:

Fehlerindikator: "Your artifact contains binary files that are incompatible with Linux ARM64."

Fehlender Einstiegspunkt

In diesem Fall: Während der Agentenerstellung, wenn die angegebene Einstiegspunktdatei nicht in Ihrer ZIP-Datei vorhanden ist.

Warum das passiert: Der Einstiegspunkt-Dateipfad, den Sie in der entryPoint Konfiguration angegeben haben, stimmt mit keiner Datei im Bereitstellungspaket überein. Dies kann passieren, wenn die Datei nicht in der ZIP-Datei enthalten war, der Pfad falsch geschrieben ist oder die ZIP-Struktur von Ihren Erwartungen abweicht.

Lösung:

Fehlerindikator: "The specified entrypoint could not be found or accessed in your artifact."

Node.js Inkompatible Engines.node-Deklaration

In diesem Fall: Während der Node.js Agentenerstellung, wenn Ihre package.json oder eine gemeinsame Abhängigkeit einen engines.node Bereich deklariert, der die Zielversion ausschließt. Node.js

Warum das passiert: AgentCore Runtime überprüft das engines.node Feld in Ihrem Stammverzeichnis package.json und in allgemeinen Abhängigkeiten. Wenn der Versionsbereich die Node.js Zielversion ausschließt (z. B. <18 oder >=14 <18 bei der Bereitstellung auf Version Node.js 22), schlägt die Agentenerstellung fehl.

Lösung:

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

Node.js Fehlendes OTEL-Paket

Wenn das passiert: Während der Node.js Agentenerstellung, wenn Sie opentelemetry-instrument im Einstiegspunkt angeben, aber das ADOT-Paket nicht in der ZIP-Datei enthalten ist.

Warum das passiert: Wenn Sie verwenden"entryPoint": ["opentelemetry-instrument", "app.js"], erwartet AgentCore Runtime, dass das @aws/aws-distro-opentelemetry-node-autoinstrumentation npm-Paket node_modules/ in Ihrem Bereitstellungspaket enthalten ist.

Lösung:

Installieren Sie das ADOT-Paket, bevor Sie Ihre ZIP-Datei packen:

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

Alternativ können Sie das opentelemetry-instrument Präfix von Ihrem Einstiegspunkt entfernen, wenn Sie keine automatische Instrumentierung benötigen.

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