Risoluzione dei problemi relativi AgentCore al runtime

Questo argomento sulla risoluzione dei problemi consente di identificare e risolvere i problemi più comuni relativi all'utilizzo di Runtime. AgentCore Seguendo queste soluzioni, è possibile diagnosticare e risolvere rapidamente i problemi relativi ai runtime degli agenti.

Le chiamate del mio agente falliscono con «This runtime is not» MMDSv2-enabled ValidationException

Quando ciò si verifica: quando si richiama il runtime di un agente tramiteInvokeAgentRuntime,,ExecuteCommand, o InvokeAgentRuntimeWithWebSocketStream InvokeAgentRuntimeCommandShell GetAgentCard

Perché questo accade: a partire dal 30 giugno 2026, Amazon Bedrock AgentCore Runtime richiede che tutti i runtime degli agenti utilizzino MMDSv2 (MicroVM Metadata Service versione 2). Il servizio rifiuta le chiamate destinate a runtime senza set o con set to o. metadataConfiguration requireMMDSV2 false null

Soluzione: chiama UpdateAgentRuntimecon set to in: requireMMDSV2 true metadataConfiguration

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

Dopo l'aggiornamento, le nuove chiamate avranno esito positivo. Le sessioni esistenti non sono interessate.

Le chiamate del mio agente falliscono con errori 504 Gateway Timeout

Quando ciò si verifica: durante la chiamata dell'agente tramite SDK o console

Perché ciò accade: diversi fattori possono impedire all'agente di rispondere entro il periodo di timeout

Ciò può essere causato da diversi fattori:

La mia build Docker fallisce con «403 Forbidden» quando estraggo immagini di base Python

Quando ciò accade: durante docker build o docker run durante l'utilizzo di immagini di base public.ecr.aws

Perché questo accade: problemi di autenticazione ECR Public: l'autenticazione scaduta o mancante è un problema comune.

Soluzione: accedi a ECR Public o disconnettiti completamente:

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

Ricevo l'errore «Unknown service: 'bedrock-agent-core-runtime'» quando uso boto3

In questo caso: quando si richiamano le AgentCore API Amazon Bedrock utilizzando l'SDK boto3

Perché ciò accade: libreria boto3 obsoleta, problema comune in quanto la maggior parte delle installazioni non dispone dell'SDK più recente

Soluzione: esegui l'aggiornamento alle versioni più recenti di boto3 e botocore:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Ricevo "AccessDeniedException" quando cerco di creare un Amazon Bedrock Runtime AgentCore

In questo caso: durante la creazione dell'agente tramite console, SDK o CLI

Perché questo accade: l'utente non dispone delle autorizzazioni o il ruolo di esecuzione non è configurato correttamente per Amazon Bedrock AgentCore

Soluzione: diversi fattori possono causare questo problema:

La mia build di Docker fallisce con «exec/bin/sh: exec format error»

In questo caso: durante la creazione di contenitori per la distribuzione di Amazon Bedrock AgentCore

Perché questo accade: creazione di contenitori ARM64 su sistemi x86 senza un'adeguata configurazione multipiattaforma

Soluzione: crea contenitori compatibili con ARM64. Puoi prendere in considerazione l'utilizzo di buildx per build multipiattaforma. In alternativa, puoi usare. CodeBuild Per esempio di codice, consulta Amazon Bedrock AgentCore Samples.

Quali sono i requisiti per i contenitori Docker utilizzati con Amazon Bedrock Runtime AgentCore ?

Consulta i requisiti di Amazon Bedrock AgentCore Runtime per tutti i dettagli.

In sintesi, il contenitore Docker deve soddisfare questi requisiti:

Il mio utensile a lunga durata si interrompe dopo 15 minuti

Per informazioni complete, consulta Gestire agenti asincroni e di lunga durata con Amazon Bedrock Amazon Bedrock Runtime AgentCore .

Quando ciò si verifica: durante operazioni a esecuzione prolungata degli agenti o flussi di lavoro complessi

Perché questo accade: Amazon Bedrock interrompe AgentCore automaticamente le sessioni dopo 15 minuti di inattività. La piattaforma determina l'attività in base alla /ping risposta: un report di sessione HealthyBusy viene mantenuto attivo, mentre un report di sessione Healthy viene considerato idoneo all'inattività e il relativo tempo di inattività viene misurato a partire dall'statusultima modifica (vedi il campo seguente). time_of_last_update

Soluzione: assicurati che l'/pingendpoint venga ripristinato HealthyBusy mentre è in corso il lavoro in background:

{"status": "HealthyBusy"}

Se utilizzi Bedrock AgentCore SDK, la risposta al ping viene gestita automaticamente. Per le implementazioni personalizzate, assicurati che il gestore del ping ritorni durante l'elaborazione. HealthyBusy

Le mie sessioni inattive non vengono rilasciate e sto esaurendo la mia quota di sessioni

Quando ciò si verifica: il numero di sessioni aumenta continuamente sotto carico e le sessioni non vengono rilasciate dopo il timeout di inattività (ad esempio, maxVms erroriServiceQuotaExceededException/durante una serie di chiamate), anche se ogni sessione è inattiva.

Perché ciò accade: quando una sessione viene segnalataHealthy, la piattaforma misura per quanto tempo è rimasta inattiva dal time_of_last_update campo della /ping risposta, il che deve indicare la data dell'ultima modifica. status Se il gestore del ping imposta l'ora corrente time_of_last_update per ogni ping, il tempo di inattività segnalato continua a essere ripristinato, il che impedisce l'attivazione del timeout di inattività. Le sessioni resteranno attive fino MaxLifetime a esaurimento della quota di sessioni.

Soluzione: esegui l'aggiornamento time_of_last_update solo quando status effettivamente cambia o omettilo completamente in modo che la piattaforma tenga traccia dei cambiamenti di stato da sola:

{"status": "Healthy"}

Se utilizzi Bedrock AgentCore SDK, esegui l'upgrade alla versione più recente, in cui la risposta al ping viene gestita correttamente. Come soluzione provvisoria, le chiamate StopRuntimeSession rilasciano sessioni bloccate.

Come posso accedere al runtime SessionId del codice del mio agente per etichettare o raggruppare le risorse?

In tal caso: si desidera raggruppare, etichettare o tracciare le risorse (ad esempio, oggetti S3, registri) in base alla sessione di runtime dell'agente corrente.

Soluzioni:

Soluzione 1: per gli agenti che utilizzano l' AgentCore SDK Amazon Bedrock di Bedrock, utilizzalo context.session_id dal punto di accesso dell'agente

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

Soluzione 2: per server HTTP di runtime personalizzati

L'ID della sessione di runtime viene passato in questa intestazione HTTP. Analizzalo dalla richiesta in entrata e usalo per l'etichettatura, la correlazione o la propagazione a valle.

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

Ho (403) problemi RuntimeClientError

Problema

Si riceve un 403 "RuntimeClientError" quando si tenta di richiamare il runtime dell'agente.

Cause

Questo errore si verifica in genere a causa di:

Resolution (Risoluzione)

Segui questi passaggi per risolvere il problema:

Ho dei log mancanti o vuoti CloudWatch

Problema

Si verificano errori ma non viene visualizzato alcun log in pertinente. CloudWatch

Soluzione

Prova questi approcci per diagnosticare il problema:

Ho problemi con il formato del payload

Problema

La chiamata al runtime dell'agente fallisce anche se il contenitore viene avviato correttamente.

Resolution (Risoluzione)

Segui questi passaggi per risolvere i problemi relativi al formato del payload:

Ho bisogno di aiuto per comprendere i codici di errore HTTP

Problema

Il tuo agente restituisce codici di errore HTTP difficili da interpretare.

Esempio di messaggio di errore

Potresti visualizzare un errore del tipo:

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

Resolution (Risoluzione)

Ecco i codici di errore più comuni e il loro significato:

Ho bisogno di consigli per testare il mio agente

Per eseguire sistematicamente il debug dei problemi di runtime dell'agente:

Esegui prima il test localmente

Prima della distribuzione su AgentCore Runtime:

Confronta i payload

Garantisci la coerenza tra gli ambienti:

Ho bisogno di aiuto per risolvere i problemi relativi ai container

Se sospetti problemi relativi ai contenitori:

Estrai ed esegui localmente

Prova l'immagine del contenitore sul tuo computer locale:

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

Prova con curl

Invia richieste di test al tuo contenitore locale:

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

Controlla i registri del contenitore

Esamina l'output del contenitore per individuare eventuali errori:

docker logs <container-id>

Ho bisogno di aiuto per la risoluzione dei problemi relativi agli agenti del protocollo MCP

Per gli agenti del protocollo MCP, seguite questi passaggi specifici per la risoluzione dei problemi:

Verifica il percorso dell'endpoint

I server MCP devono ascoltare 0.0.0.0:8000/mcp/

Usa MCP Inspector

Prova con lo strumento MCP Inspector:

Problemi di autenticazione

Verifica la configurazione dell'autenticazione:

Ho bisogno di aiuto per la risoluzione dei problemi relativi allo streaming bidirezionale utilizzando WebSocket

Per lo streaming bidirezionale tramite WebSocket agenti, segui questi passaggi specifici per la risoluzione dei problemi:

Verifica la configurazione degli endpoint

WebSocket gli agenti devono funzionare sulla porta 8080 e servire le WebSocket connessioni sul percorso /ws

Esegui il test localmente con complessità incrementale

Inizia con semplici test locali prima di implementare:

Problemi di autenticazione

Verifica la configurazione di autenticazione per gli agenti distribuiti:

Problemi di connessione comuni

Risolvi i problemi di WebSocket connessione più comuni:

Le mie modifiche al codice non si riflettono nelle sessioni esistenti

Problema

Hai aggiornato il runtime dell'agente con un nuovo codice, ma le sessioni esistenti continuano a utilizzare la vecchia versione.

Perché questo accade

Ogni sessione MicroVM viene creata con le risorse di codice (agentRuntimeArtifact) distribuite al momento della creazione della sessione. Una volta stabilita, una sessione continua a utilizzare quella versione del codice fino al termine della sessione, anche quando le risorse di codice vengono aggiornate durante l'esecuzione dell'operazione. UpdateAgentRuntime

Soluzione

Per accedere al codice aggiornato, utilizza un nuovo ID di sessione.

Mancano gli intervalli quando il mio runtime viene richiamato da una funzione Lambda

In questo caso: quando si richiama AgentCore Runtime da una funzione Lambda

Perché questo accade: Lambda genera la propria X-Amzn-Trace-Id intestazione. Se la traccia Lambda lo haSampled=0, questo contesto non campionato si propaga a AgentCore Runtime e il runtime salta la generazione dello span per quella chiamata.

Soluzione::

Il montaggio di My S3 Files o EFS fallisce con «Accesso negato»

In questo caso: durante la chiamata di un agente con S3 Files o storage EFS configurato

Perché ciò accade: al ruolo di esecuzione mancano le autorizzazioni richieste per il filesystem. Per ulteriori informazioni sulla configurazione dell'archiviazione persistente, consulta Configurazioni del file system per Runtime. AgentCore

Soluzione::

Per i file S3, assicurati che il tuo ruolo di esecuzione abbia:

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Per EFS, assicurati che il tuo ruolo di esecuzione abbia:

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Ometti s3files:ClientWrite o elasticfilesystem:ClientWrite se il tuo agente necessita solo dell'accesso in lettura.

Il montaggio dei miei file S3 o EFS fallisce con "» ResourceNotFound

In questo caso: durante la chiamata di un agente con S3 Files o storage EFS configurato

Perché questo accade: il filesystem o il punto di accesso sono stati eliminati dopo la creazione dell'agente oppure gli ID non sono corretti.

Soluzione::

Timeout del montaggio di My S3 Files o EFS

In questo caso: durante la chiamata di un agente con S3 Files o storage EFS configurato. La chiamata potrebbe richiedere più tempo del solito prima di fallire.

Perché ciò accade: la configurazione di rete VPC blocca il traffico NFS (porta 2049) tra l'elaborazione dell'agente e le destinazioni di montaggio del file system.

Soluzione::

Ricevo il messaggio «Autorizzazione negata» quando scrivo sul mio filesystem montato

Quando ciò si verifica: la chiamata dell'agente ha esito positivo e l'agente può leggere i file dal mount, ma la scrittura fallisce con «Autorizzazione negata»

Perché ciò accade: o al ruolo IAM mancano le autorizzazioni di scrittura oppure le autorizzazioni POSIX sulla directory impostata durante la creazione del punto di accesso non consentono le scritture per l'utente dell'agente.

Soluzione::

Il mio contenitore non si avvia con l'errore HTTP 424 su immagini di alto livello

In questo caso: le InvokeAgentRuntime chiamate restituiscono HTTP 424 (Failed Dependency) e vengono visualizzati i log dell'agente. Failed to mount overlay: No such file or directory Ciò si verifica quando l'immagine del contenitore ha più di 53 livelli E utilizza una direttiva USER non numerica (ad esempio, invece di). USER myuser USER 1000

Perché ciò accade: le immagini del contenitore con molti livelli combinate con direttive USER non numeriche possono causare errori di inizializzazione.

Soluzione: utilizzate una di queste soluzioni alternative:

docker inspect <image> | jq '.[0].RootFS.Layers | length'

Best practice

Abilita la registrazione completa

Implementa una registrazione completa nel tuo agente:

Utilizza la gestione strutturata degli errori

Implementa una chiara segnalazione degli errori:

Verifica le modifiche incrementali

Segui un approccio metodico di test:

Monitora le prestazioni

Configura il monitoraggio per il tuo agente: