Fehlerbehebung bei AgentCore Runtime

Dieses Thema zur Fehlerbehebung hilft Ihnen dabei, häufig auftretende Probleme bei der Arbeit mit AgentCore Runtime zu identifizieren und zu lösen. Wenn Sie sich an diese Lösungen halten, können Sie Probleme mit den Laufzeiten Ihrer Agenten schnell diagnostizieren und beheben.

Meine Agentenaufrufe schlagen mit der Meldung „Diese Laufzeit ist nicht“ fehl MMDSv2-enabled ValidationException

Wenn das passiert: Beim Aufrufen einer Agenten-Laufzeit überInvokeAgentRuntime,,ExecuteCommand, oder InvokeAgentRuntimeWithWebSocketStream InvokeAgentRuntimeCommandShell GetAgentCard

Warum das passiert: Ab dem 30. Juni 2026 verlangt Amazon Bedrock AgentCore Runtime, dass alle Agentenlaufzeiten MMDSv2 (MicroVM Metadata Service Version 2) verwenden. Der Service lehnt Aufrufe ab, die auf Laufzeiten ohne Einstellung oder mit Einstellung auf oder abzielen. metadataConfiguration requireMMDSV2 false null

Lösung: Rufen Sie UpdateAgentRuntimemit requireMMDSV2 der Einstellung „In“ auf: an 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}")

Nach der Aktualisierung werden neue Aufrufe erfolgreich sein. Bestehende Sitzungen sind nicht betroffen.

Meine Agentenaufrufe schlagen mit 504 Gateway Timeout-Fehlern fehl

Wenn das passiert: Während des Agentenaufrufs über das SDK oder die Konsole

Warum das passiert: Es gibt mehrere Faktoren, die verhindern können, dass Ihr Agent innerhalb des Timeouts reagiert

Dies kann durch mehrere Faktoren verursacht werden:

Mein Docker-Build schlägt beim Abrufen von Python-Basisimages mit „403 Forbidden“ fehl

Wenn das passiert: Während docker build oder docker run bei der Verwendung von public.ecr.aws Basisimages

Warum das passiert: Probleme mit der öffentlichen ECR Authentifizierung — eine abgelaufene oder fehlende Authentifizierung ist ein häufiges Problem.

Lösung: Melden Sie sich entweder bei ECR Public an oder melden Sie sich vollständig ab:

# 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

Ich erhalte die Fehlermeldung „Unknown service: 'bedrock-agent-core-runtime'“, wenn ich boto3 verwende

Wenn das passiert: Beim Aufrufen von Amazon Bedrock AgentCore APIs mit dem boto3 SDK

Warum das passiert: Veraltete Boto3-Bibliothek — häufiges Problem, da die meisten Installationen nicht über das neueste SDK verfügen

Lösung: Update auf die neuesten Boto3- und Botocore-Versionen:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Ich erhalte "AccessDeniedException", wenn ich versuche, eine Amazon Bedrock AgentCore Runtime zu erstellen

In diesem Fall: Während der Agentenerstellung über die Konsole, das SDK oder die CLI

Warum das passiert: Entweder fehlen Ihrem Benutzer die erforderlichen Berechtigungen, oder die Ausführungsrolle ist für Amazon Bedrock nicht richtig konfiguriert AgentCore

Lösung: Dies kann durch mehrere Faktoren verursacht werden:

Mein Docker-Build schlägt mit der Meldung „exec/bin/sh: exec format error“ fehl

Wann das passiert: Beim Erstellen von Containern für die Bereitstellung von Amazon Bedrock AgentCore

Warum das passiert: Erstellung von ARM64-Containern auf x86-Systemen ohne korrekte plattformübergreifende Einrichtung

Lösung: Erstellen Sie ARM64-kompatible Container. Sie können erwägen, buildx für plattformübergreifende Builds zu verwenden. Alternativ können Sie verwenden. CodeBuild Beispielcode finden Sie in den Amazon AgentCore Bedrock-Beispielen.

Was sind die Anforderungen für Docker-Container, die mit Amazon Bedrock AgentCore Runtime verwendet werden?

Vollständige Informationen finden Sie in den Amazon Bedrock AgentCore Runtime-Anforderungen.

Zusammenfassend muss Ihr Docker-Container die folgenden Anforderungen erfüllen:

Mein Tool mit langer Laufzeit wird nach 15 Minuten unterbrochen

Weitere Informationen finden Sie unter Umgang mit asynchronen und lang laufenden Agenten mit Amazon Bedrock Amazon Bedrock AgentCore Runtime für weitere Informationen.

Wenn dies der Fall ist: Während lang andauernder Agentenoperationen oder komplexer Workflows

Warum das passiert: Amazon Bedrock beendet Sitzungen AgentCore automatisch nach 15 Minuten Inaktivität. Die Plattform bestimmt die Aktivität anhand der /ping Antwort: Ein Sitzungsbericht HealthyBusy bleibt bestehen, während ein Sitzungsbericht als inaktiv Healthy eingestuft wird und die Leerlaufzeit ab dem Zeitpunkt der status letzten Änderung gemessen wird (siehe Feld unten). time_of_last_update

Lösung: Stellen Sie sicher, dass Ihr /ping Endpunkt wieder HealthyBusy verfügbar ist, während im Hintergrund gearbeitet wird:

{"status": "HealthyBusy"}

Wenn Sie das Bedrock AgentCore SDK verwenden, wird die Ping-Antwort automatisch verarbeitet. Stellen Sie bei benutzerdefinierten Implementierungen sicher, dass Ihr Ping-Handler HealthyBusy während der Verarbeitung zurückkehrt.

Meine inaktiven Sitzungen werden nicht veröffentlicht und ich habe mein Sitzungskontingent ausgeschöpft

In diesem Fall steigt die Anzahl der Sitzungen unter Last kontinuierlich und Sitzungen werden nach Ablauf des Leerlaufzeitlimits nicht wieder freigegeben (z. B. ServiceQuotaExceededException maxVms /-Fehler während einer Reihe von Aufrufen), obwohl sich jede Sitzung im Leerlauf befindet.

Warum das passiert: Wenn eine Sitzung gemeldet wirdHealthy, misst die Plattform anhand des time_of_last_update Felds in Ihrer /ping Antwort, wie lange sie inaktiv war. Dabei muss berücksichtigt werden, wann sich die letzte Änderung geändert hat. status Wenn Ihr Ping-Handler bei jedem Ping time_of_last_update auf die aktuelle Uhrzeit setzt, wird die gemeldete Leerlaufzeit ständig zurückgesetzt, wodurch verhindert wird, dass das Leerlauf-Timeout ausgelöst wird. Die Sitzungen dauern dann so lange, bis Ihr Sitzungskontingent ausgeschöpft ist, MaxLifetime und können es sein.

Lösung: Aktualisieren Sie time_of_last_update nur, wenn sich das status tatsächlich ändert, oder lassen Sie es ganz weg, sodass die Plattform Statusänderungen selbst verfolgt:

{"status": "Healthy"}

Wenn Sie das Bedrock AgentCore SDK verwenden, führen Sie ein Upgrade auf die neueste Version durch, bei der die Ping-Antwort korrekt verarbeitet wird. Als Notlösung werden beim Aufrufen festgefahrene Sitzungen StopRuntimeSession wieder freigegeben.

Wie greife ich auf die Runtime SessionId in meinem Agentencode zu, um Ressourcen zu taggen oder zu gruppieren?

Wenn dies zutrifft: Sie möchten Ressourcen (z. B. S3-Objekte, Protokolle) nach der aktuellen Agenten-Runtime-Sitzung gruppieren, taggen oder verfolgen.

Lösungen:

Lösung 1: Für Agenten, die das Bedrock Amazon Bedrock AgentCore SDK verwenden, verwenden Sie es context.session_id von Ihrem Agenten-Einstiegspunkt aus

@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

Lösung 2: Für benutzerdefinierte Runtime-HTTP-Server

Die Runtime-Sitzungs-ID wird in diesem HTTP-Header übergeben. Analysieren Sie sie anhand der eingehenden Anfrage und verwenden Sie sie für Tagging, Korrelation oder Downstream-Propagierung.

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

Ich habe RuntimeClientError (403) Probleme

Problem

Sie erhalten eine 403 "RuntimeClientError", wenn Sie versuchen, Ihre Agenten-Laufzeit aufzurufen.

Ursachen

Dieser Fehler tritt in der Regel auf aufgrund von:

Resolution (Auflösung)

Gehen Sie wie folgt vor, um das Problem zu beheben:

Ich habe fehlende oder leere Logs CloudWatch

Problem

Sie stoßen auf Fehler, aber es werden keine relevanten Logs angezeigt CloudWatch.

Lösung

Probieren Sie die folgenden Methoden aus, um das Problem zu diagnostizieren:

Ich habe Probleme mit dem Payload-Format

Problem

Ihr Agenten-Laufzeitaufruf schlägt fehl, obwohl der Container erfolgreich gestartet wurde.

Resolution (Auflösung)

Gehen Sie wie folgt vor, um Probleme mit dem Payload-Format zu beheben:

Ich benötige Hilfe beim Verständnis von HTTP-Fehlercodes

Problem

Ihr Agent gibt HTTP-Fehlercodes zurück, die schwer zu interpretieren sind.

Beispiel für eine Fehlermeldung

Möglicherweise wird ein Fehler wie der folgende angezeigt:

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 (Auflösung)

Hier sind die häufigsten Fehlercodes und ihre Bedeutung:

Ich benötige Empfehlungen zum Testen meines Agenten

So debuggen Sie Probleme mit der Agenten-Laufzeit systematisch:

Testen Sie zuerst lokal

Vor der Bereitstellung in AgentCore Runtime:

Nutzlasten vergleichen

Stellen Sie die Konsistenz zwischen den Umgebungen sicher:

Ich benötige Hilfe beim Debuggen von Container-Problemen

Wenn Sie Probleme im Zusammenhang mit Containern vermuten:

Lokal abrufen und ausführen

Testen Sie Ihr Container-Image auf Ihrem lokalen Computer:

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

Testen Sie mit curl

Senden Sie Testanfragen an Ihren lokalen Container:

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

Überprüfen Sie die Container-Protokolle

Untersuchen Sie die Ausgabe des Containers auf Fehler:

docker logs <container-id>

Ich benötige Hilfe bei der Fehlerbehebung bei MCP-Protokollagenten

Gehen Sie bei MCP-Protokollagenten wie folgt vor:

Überprüfen Sie den Endpunktpfad

MCP-Server sollten mithören 0.0.0.0:8000/mcp/

Verwenden Sie MCP Inspector

Testen Sie mit dem MCP Inspector Tool:

Probleme bei der Authentifizierung

Überprüfen Sie die Authentifizierungskonfiguration:

Ich benötige Hilfe bei der Fehlerbehebung beim bidirektionalen Streaming mit WebSocket

Gehen Sie bei bidirektionalem Streaming mithilfe von WebSocket Agenten wie folgt vor:

Überprüfen Sie die Endpunktkonfiguration

WebSocket Die Agenten müssen auf Port 8080 ausgeführt werden und WebSocket Verbindungen über den Pfad bereitstellen /ws

Testen Sie lokal mit inkrementeller Komplexität

Beginnen Sie vor der Bereitstellung mit einfachen lokalen Tests:

Probleme bei der Authentifizierung

Überprüfen Sie die Authentifizierungskonfiguration für die bereitgestellten Agenten:

Häufige Verbindungsprobleme

Beheben Sie häufig auftretende WebSocket Verbindungsprobleme:

Meine Codeänderungen spiegeln sich nicht in bestehenden Sitzungen wider

Problem

Sie haben Ihre Agenten-Laufzeit mit neuem Code aktualisiert, aber in bestehenden Sitzungen wird weiterhin die alte Version verwendet.

Warum passiert das

Jede MicroVM-Sitzung wird mit den Code-Assets (agentRuntimeArtifact) erstellt, die zum Zeitpunkt der Sitzungserstellung bereitgestellt wurden. Sobald eine Sitzung eingerichtet ist, verwendet sie diese Version des Codes weiter, bis die Sitzung beendet wird, auch wenn Code-Ressourcen im Rahmen der Ausführung des UpdateAgentRuntimeVorgangs aktualisiert werden.

Lösung

Verwenden Sie eine neue Sitzungs-ID, um auf Ihren aktualisierten Code zuzugreifen.

Spans fehlen, wenn meine Laufzeit von einer Lambda-Funktion aufgerufen wird

Wenn das passiert: Beim Aufrufen von AgentCore Runtime aus einer Lambda-Funktion

Warum das passiert: Lambda generiert seinen eigenen X-Amzn-Trace-Id Header. Wenn der Lambda-Trace dies getan hatSampled=0, wird dieser Kontext ohne Stichprobe an Runtime weitergegeben und die AgentCore Runtime überspringt die Span-Generierung für diesen Aufruf.

Lösung:

Mein S3-Dateien- oder EFS-Mount schlägt mit „Zugriff verweigert“ fehl

In diesem Fall: Während des Aufrufs eines Agenten mit konfiguriertem S3-Dateien- oder EFS-Speicher

Warum das passiert: Für die Ausführungsrolle fehlen die erforderlichen Dateisystemberechtigungen. Weitere Informationen zur Konfiguration von persistentem Speicher finden Sie unter Dateisystemkonfigurationen für AgentCore Runtime.

Lösung:

Stellen Sie für S3-Dateien sicher, dass Ihre Ausführungsrolle Folgendes hat:

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

Stellen Sie für EFS sicher, dass Ihre Ausführungsrolle Folgendes hat:

{
  "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>"
    }
  }
}

Lassen Sie s3files:ClientWrite oder wegelasticfilesystem:ClientWrite, wenn Ihr Agent nur Lesezugriff benötigt.

Mein S3-Dateien- oder EFS-Mount schlägt fehl mit "ResourceNotFound“

In diesem Fall: Während des Aufrufs eines Agenten mit konfiguriertem S3-Dateien- oder EFS-Speicher

Warum das passiert: Das Dateisystem oder der Access Point wurde gelöscht, nachdem der Agent erstellt wurde, oder die IDs sind falsch.

Lösung:

Bei meinen S3-Dateien oder beim EFS-Mount kommt es zu einem Timeout

In diesem Fall: Während des Aufrufs eines Agenten mit konfiguriertem S3 Files- oder EFS-Speicher. Der Aufruf kann länger als gewöhnlich dauern, bevor er fehlschlägt.

Warum das passiert: Die VPC-Netzwerkkonfiguration blockiert den NFS-Verkehr (Port 2049) zwischen dem Computer des Agenten und den Mount-Zielen des Dateisystems.

Lösung:

Ich erhalte die Meldung „Permission Denied“, wenn ich in mein gemountetes Dateisystem schreibe

Wenn das passiert: Der Agentenaufruf ist erfolgreich und der Agent kann Dateien aus dem Mount lesen, aber das Schreiben schlägt mit der Meldung „Permission denied“ fehl

Warum das passiert: Entweder fehlen der IAM-Rolle Schreibberechtigungen, oder die POSIX-Berechtigungen für das Verzeichnis, das bei der Erstellung des Access Points festgelegt wurde, erlauben keine Schreibvorgänge für den Benutzer des Agenten.

Lösung:

Mein Container startet bei High-Layer-Bildern nicht mit dem HTTP 424-Fehler

Wenn das passiert: Ihre InvokeAgentRuntime Anrufe geben HTTP 424 (Failed Dependency) zurück und Ihre Agentenprotokolle werden angezeigt. Failed to mount overlay: No such file or directory Dies ist der Fall, wenn Ihr Container-Image mehr als 53 Ebenen hat UND eine nicht numerische USER-Direktive verwendet (z. B. USER myuser stattUSER 1000).

Warum das passiert: Container-Images mit vielen Ebenen in Kombination mit nichtnumerischen USER-Direktiven können zu Initialisierungsfehlern führen.

Lösung: Verwenden Sie eine der folgenden Problemumgehungen:

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

Bewährte Methoden

Ermöglichen Sie eine umfassende Protokollierung

Implementieren Sie eine gründliche Protokollierung in Ihrem Agenten:

Verwenden Sie eine strukturierte Fehlerbehandlung

Implementieren Sie eine klare Fehlerberichterstattung:

Testen Sie inkrementelle Änderungen

Folgen Sie einem methodischen Testansatz:

Überwachen Sie die Leistung

Richten Sie die Überwachung für Ihren Agenten ein: