Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Risolvi i problemi relativi AgentCore a Runtime

Questo argomento sulla risoluzione dei problemi consente di identificare e risolvere i problemi più comuni quando si lavora con Runtime. AgentCore Seguendo queste soluzioni, è possibile diagnosticare e risolvere rapidamente i problemi relativi ai tempi di esecuzione degli agenti.

Le mie chiamate all'agente hanno esito negativo con il messaggio «Questo runtime non è» MMDSv2-enabled ValidationException

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

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

Soluzione: chiama UpdateAgentRuntime con 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 non riescono con errori 504 Gateway Timeout

Quando ciò si verifica: durante l'invocazione dell'agente tramite SDK o console

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

Questo può essere causato da diversi fattori:

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

Quando ciò accade: durante docker build o docker run quando si utilizzano immagini di base public.ecr.aws

Perché ciò accade: Problemi di autenticazione pubblica ECR: l'autenticazione scaduta o mancante è un problema comune.

Soluzione: accedi a ECR Public o esci 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

Quando utilizzo boto3, ricevo l'errore «Servizio sconosciuto: 'bedrock-agent-core-runtime'»

Quando ciò si verifica: quando si richiamano le API Amazon Bedrock utilizzando l'SDK boto3 AgentCore

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

Soluzione: 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 provo a creare un Amazon Bedrock Runtime AgentCore

Quando ciò si verifica: durante la creazione dell'agente tramite console, SDK o CLI

Perché ciò accade: o 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 Docker non riesce con «exec/bin/sh: exec format error»

Quando ciò si verifica: quando si creano contenitori per la distribuzione di Amazon Bedrock AgentCore

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

Soluzione: creare 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 AgentCore Bedrock Runtime?

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

In sintesi, il tuo contenitore Docker deve soddisfare questi requisiti:

Il mio strumento di lunga durata si interrompe dopo 15 minuti

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

Quando ciò si verifica: durante operazioni con agenti di lunga durata o flussi di lavoro complessi

Perché ciò accade: Amazon Bedrock termina 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 tempo di inattività viene misurato a partire dall'statusultima modifica (vedi il campo sottostante). time_of_last_update

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

{"status": "HealthyBusy"}

Se si utilizza 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ò accade: il numero di sessioni aumenta continuamente sotto carico e le sessioni non vengono rilasciate dopo il timeout di inattività (ad esempio, ServiceQuotaExceededException maxVms /errors 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 nel time_of_last_update campo della /ping risposta, indicando la data dell'ultima modifica. status Se il gestore di ping imposta l'ora corrente time_of_last_update per ogni ping, il tempo di inattività riportato continua a essere ripristinato, impedendo l'attivazione del timeout di inattività. Le sessioni sono quindi attive fino MaxLifetime all'esaurimento della quota di sessioni consentita.

Soluzione: aggiorna time_of_last_update solo quando viene status effettivamente modificato o omettilo completamente in modo che la piattaforma tenga traccia delle modifiche di stato da sola:

{"status": "Healthy"}

Se stai utilizzando Bedrock AgentCore SDK, esegui l'aggiornamento alla versione più recente, in cui la risposta al ping viene gestita correttamente. Come soluzione provvisoria, la chiamata StopRuntimeSession libera le sessioni bloccate.

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

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

Soluzioni:

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

@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 con runtime personalizzati

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

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

Ho (403) problemi RuntimeClientError

Problema

Riceverai un 403 "RuntimeClientError" quando tenti 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 accesso pertinente CloudWatch.

Soluzione

Prova questi approcci per diagnosticare il problema:

Ho problemi con il formato del payload

Problema

L'invocazione del runtime dell'agente non riesce 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 capire 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 il debug sistematico 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 container:

Pull and run localmente

Testa 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 log dei contenitori

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, segui questi passaggi specifici per la risoluzione dei problemi:

Verifica il percorso dell'endpoint

I server MCP dovrebbero essere in ascolto 0.0.0.0:8000/mcp/

Usa MCP Inspector

Esegui il test con lo strumento MCP Inspector:

Problemi di autenticazione

Controlla la configurazione dell'autenticazione:

Ho bisogno di aiuto per risolvere i problemi dello 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 essere eseguiti sulla porta 8080 e gestire le WebSocket connessioni sul percorso /ws

Esegui test localmente con complessità incrementale

Inizia con semplici test locali prima dell'implementazione:

Problemi di autenticazione

Controlla la configurazione dell'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) che sono state 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 del codice vengono aggiornate durante l'esecuzione dell'operazione. UpdateAgentRuntime

Soluzione

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

Gli intervalli mancano quando il mio runtime viene richiamato da una funzione Lambda

Quando ciò accade: quando si richiama AgentCore Runtime da una funzione Lambda

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

Soluzione::

Il montaggio dei miei file S3 o EFS non riesce con «Accesso negato»

Quando ciò si verifica: durante l'invocazione di un agente con file S3 o storage EFS configurato

Perché ciò accade: al ruolo di esecuzione mancano le autorizzazioni necessarie per il file system. 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 non riesce con "» ResourceNotFound

Quando ciò si verifica: durante l'invocazione di un agente con file S3 o storage EFS configurato

Perché ciò accade: il filesystem o il punto di accesso è stato eliminato dopo la creazione dell'agente oppure gli ID non sono corretti.

Soluzione::

Il timeout dei miei file S3 o EFS

Quando ciò si verifica: durante l'invocazione di un agente con file S3 o storage EFS configurato. L'invocazione 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 «Autorizzazione negata» quando scrivo sul mio filesystem montato

Quando ciò accade: l'invocazione dell'agente ha esito positivo e l'agente può leggere i file dal montaggio, ma la scrittura non riesce 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 la scrittura per l'utente dell'agente.

Soluzione::

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

In questo caso: le InvokeAgentRuntime chiamate restituiscono HTTP 424 (Failed Dependency) e vengono visualizzati i log degli agenti. 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, USER myuser invece di). USER 1000

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

Soluzione: utilizzare una di queste soluzioni alternative:

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

Il mio fornitore di capacità è nello stato CREATE_FAILED

Quando ciò si verifica: dopo aver richiesto il tipo CreateCapacityProvider di calcolo Instances, il fornitore di capacità non lo raggiunge ed entra invece. ACTIVE CREATE_FAILED

Perché ciò accade: un fornitore di capacità si affida a più risorse (come un modello di avvio e un gruppo Auto Scaling) che il ruolo di operatore del fornitore di capacità deve essere in grado di creare. La mancanza delle autorizzazioni per quel ruolo comporta un errore di creazione.

Soluzione: richiama l'GetCapacityProviderAPI per recuperare il motivo dell'errore nel statusReason campo. statusReasonIdentifica le risorse che non sono state create. Concedi al ruolo di operatore del fornitore di capacità le autorizzazioni necessarie per creare tali risorse, quindi crea nuovamente il fornitore di capacità. Per ulteriori informazioni sul ruolo dell'operatore, consulta Modello di sicurezza e autorizzazioni per le istanze di runtime.

I miei agenti sulle istanze non hanno accesso alle proprie credenziali

Quando ciò accade: un agente in esecuzione su una sessione Instances non può ottenere le credenziali necessarie per chiamare i servizi. AWS

Perché ciò accade: il ruolo di esecuzione in fase di esecuzione è assente o non può essere assunto da. AgentCore

Soluzione: assicurati che il ruolo di esecuzione che hai configurato per il tuo runtime esista e bedrock-agentcore.amazonaws.com consenta la chiamatasts:AssumeRole. Per ulteriori informazioni, consulta le autorizzazioni per il ruolo di esecuzione di Amazon Bedrock AgentCore Runtime.

Best practice

Abilita una registrazione completa

Implementa una registrazione completa del tuo agente:

Utilizza una gestione strutturata degli errori

Implementa una chiara segnalazione degli errori:

Verifica le modifiche incrementali

Segui un approccio metodico ai test:

Monitora le prestazioni

Configura il monitoraggio per il tuo agente: