Risoluzione dei problemi relativi alla distribuzione diretta del codice

Problemi e soluzioni comuni per iniziare a usare la distribuzione AgentCore diretta del codice di Amazon Bedrock. Per ulteriori informazioni sulla risoluzione dei problemi, consulta Risoluzione dei problemi di Amazon AgentCore Bedrock Runtime.

AccessDenied: autorizzazioni S3 insufficienti

In questo caso: durante la creazione o l'aggiornamento dell'agente con artefatto compresso in S3 tramite console, SDK o CLI

Perché ciò accade: il ruolo utilizzato per la chiamata Create/UpdateAgentRuntime non dispone di GetObject autorizzazioni s3: su S3 uri trasmesse nell'input dell'API.

Soluzione: aggiungi s3: GetObject autorizzazione nel ruolo utilizzata per chiamare l'API Agentcore Runtime. create/update

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

AccessDenied: accesso agli oggetti S3 crittografati con CMK

Quando ciò si verifica: durante la creazione di agenti con oggetti CMK-encrypted S3, quando il ruolo di esecuzione non dispone delle autorizzazioni di decrittografia KMS.

Perché ciò accade: il ruolo usato per chiamare Create/UpdateAgentRuntime non dispone delle autorizzazioni KMS:Decrypt sulla CMK utilizzata per crittografare l'oggetto S3 contenente il codice dell'agente.

Soluzione: aggiungi l'autorizzazione KMS:Decrypt al ruolo per la CMK specifica:

{
"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à del pacchetto di codice

In questo caso: durante la creazione o l'aggiornamento dell'agente con pacchetti di codice incompatibili (architettura, versione della lingua o formato del pacchetto errati).

Perché ciò accade: il file ZIP caricato contiene file binari compilati per un'architettura errata (ARM64 vs x86_64), una versione linguistica incompatibile o una struttura di pacchetto errata che non soddisfa i requisiti di Runtime. AgentCore

Soluzione::

Per risolvere il problema:

Indicatori di errore:

Incompatibilità binaria ARM64

Quando ciò si verifica: durante la creazione dell'agente, quando lo ZIP contiene file binari nativi compilati per un'architettura non ARM64.

Perché ciò accade: AgentCore Runtime supporta solo l'architettura del set di istruzioni arm64. Il servizio esegue la scansione di tutti i file binari nativi del pacchetto di distribuzione (.sofile per Python e .so entrambi .node e file per) e convalida le relative intestazioni ELF Node.js per la compatibilità con ARM64. Se viene compilato un file binario per x86_64, macOS (Mach-O) o un'altra architettura, la convalida fallisce.

Soluzione::

Indicatore di errore: "Your artifact contains binary files that are incompatible with Linux ARM64."

Punto di ingresso mancante

In questo caso: durante la creazione dell'agente quando il file del punto di ingresso specificato non esiste nel file ZIP.

Perché ciò accade: il percorso del file del punto di ingresso specificato nella entryPoint configurazione non corrisponde a nessun file nel pacchetto di distribuzione. Ciò può accadere se il file non è stato incluso nello ZIP, se il percorso è digitato in modo errato o se la struttura ZIP è diversa da quella prevista.

Soluzione::

Indicatore di errore: "The specified entrypoint could not be found or accessed in your artifact."

Node.js Dichiarazione engines.node incompatibile

Quando ciò si verifica: durante la creazione Node.js dell'agente, quando la tua package.json o una dipendenza comune dichiara un engines.node intervallo che esclude la versione di destinazione. Node.js

Perché questo accade: AgentCore Runtime controlla il engines.node campo nella directory principale package.json e nelle dipendenze comuni. Se l'intervallo di versioni esclude la Node.js versione di destinazione (ad esempio, <18 o >=14 <18 quando si esegue la distribuzione su Node.js 22), la creazione dell'agente non riesce.

Soluzione::

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

Node.js Pacchetto OTEL mancante

In questo caso: durante la creazione Node.js dell'agente, quando si specifica opentelemetry-instrument nel punto di ingresso, ma il pacchetto ADOT non è incluso nello ZIP.

Perché ciò accade: quando si utilizza"entryPoint": ["opentelemetry-instrument", "app.js"], AgentCore Runtime si aspetta che il pacchetto @aws/aws-distro-opentelemetry-node-autoinstrumentation npm sia presente node_modules/ all'interno del pacchetto di distribuzione.

Soluzione::

Installa il pacchetto ADOT prima di impacchettare il tuo ZIP:

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

In alternativa, rimuovi il opentelemetry-instrument prefisso dal punto di ingresso se non hai bisogno della strumentazione automatica.

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