# 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.
**Topics**
+ [Meine Agentenaufrufe schlagen mit der Meldung „Diese Laufzeit ist nicht“ fehl MMDSv2-enabled ValidationException](#troubleshoot-runtime-mmdsv2-validation)
+ [Meine Agentenaufrufe schlagen mit 504 Gateway Timeout-Fehlern fehl](#troubleshoot-runtime-timeout)
+ [Mein Docker-Build schlägt beim Abrufen von Python-Basisimages mit „403 Forbidden“ fehl](#troubleshoot-runtime-docker-403)
+ [Ich erhalte die Fehlermeldung „Unknown service: 'bedrock-agent-core-runtime'“, wenn ich boto3 verwende](#troubleshoot-runtime-boto3)
+ [Ich erhalte "AccessDeniedException", wenn ich versuche, eine Amazon Bedrock AgentCore Runtime zu erstellen](#troubleshoot-runtime-access-denied)
+ [Mein Docker-Build schlägt mit der Meldung „exec/bin/sh: exec format error“ fehl](#troubleshoot-runtime-exec-format)
+ [Was sind die Anforderungen für Docker-Container, die mit Amazon Bedrock AgentCore Runtime verwendet werden?](#troubleshoot-runtime-requirements)
+ [Mein Tool mit langer Laufzeit wird nach 15 Minuten unterbrochen](#troubleshoot-runtime-long-running)
+ [Meine inaktiven Sitzungen werden nicht veröffentlicht und ich habe mein Sitzungskontingent ausgeschöpft](#troubleshoot-runtime-idle-not-releasing)
+ [Wie greife ich auf die Runtime SessionId in meinem Agentencode zu, um Ressourcen zu taggen oder zu gruppieren?](#troubleshoot-runtime-session-id)
+ [Ich habe RuntimeClientError (403) Probleme](#runtime-client-error)
+ [Ich habe fehlende oder leere Logs CloudWatch](#missing-cloudwatch-logs)
+ [Ich habe Probleme mit dem Payload-Format](#payload-format-issues)
+ [Ich benötige Hilfe beim Verständnis von HTTP-Fehlercodes](#common-error-codes)
+ [Ich benötige Empfehlungen zum Testen meines Agenten](#testing-recommendations)
+ [Ich benötige Hilfe beim Debuggen von Container-Problemen](#debugging-container-issues)
+ [Ich benötige Hilfe bei der Fehlerbehebung bei MCP-Protokollagenten](#troubleshooting-mcp-protocol)
+ [Ich benötige Hilfe bei der Fehlerbehebung beim bidirektionalen Streaming mit WebSocket](#troubleshooting-websocket-protocol)
+ [Meine Codeänderungen spiegeln sich nicht in bestehenden Sitzungen wider](#troubleshoot-code-updates)
+ [Spans fehlen, wenn meine Laufzeit von einer Lambda-Funktion aufgerufen wird](#troubleshoot-runtime-lambda-missing-spans)
+ [Mein S3-Dateien- oder EFS-Mount schlägt mit „Zugriff verweigert“ fehl](#troubleshoot-byo-storage-access-denied)
+ [Mein S3-Dateien- oder EFS-Mount schlägt fehl mit "ResourceNotFound“](#troubleshoot-byo-storage-resource-not-found)
+ [Bei meinen S3-Dateien oder beim EFS-Mount kommt es zu einem Timeout](#troubleshoot-byo-storage-mount-timeout)
+ [Ich erhalte die Meldung „Permission Denied“, wenn ich in mein gemountetes Dateisystem schreibe](#troubleshoot-byo-storage-write-permission-denied)
+ [Mein Container startet bei High-Layer-Bildern nicht mit dem HTTP 424-Fehler](#troubleshoot-runtime-overlay-mount-failure)
+ [Bewährte Methoden](#best-practices)
## Meine Agentenaufrufe schlagen mit der Meldung „Diese Laufzeit ist nicht“ fehl MMDSv2-enabled ValidationException
**Wenn das passiert:** Beim Aufrufen einer Agenten-Laufzeit über`InvokeAgentRuntime`,,`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 [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html)mit `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:
+ **Container-Probleme:** Stellen Sie sicher, dass Ihr Docker-Image den Port 8080 verfügbar macht und den Pfad hat `/invocations`
+ **ARM64-Kompatibilität: Derzeit muss** Ihr Container ARM64-kompatibel sein
+ **Wiederholungslogik: Informieren Sie** sich über die Wiederholungsmechanismen zur Behandlung vorübergehender Probleme
## 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:
+ **Fehlende Berechtigungen für den Anrufer.** Vergewissern Sie sich, dass die Anmeldeinformationen des Anrufers gültig sind. `bedrock-agentcore:CreateAgentRuntime`
+ **Die Ausführungsrolle kann nicht von Bedrock Amazon AgentCore Bedrock übernommen werden.** Stellen Sie sicher, dass die Ausführungsrolle diese Anleitung zu den [Berechtigungen für die Amazon Bedrock AgentCore Runtime-Ausführungsrolle](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) befolgt.
## 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](https://github.com/docker/buildx) für plattformübergreifende Builds zu verwenden. Alternativ können Sie verwenden. CodeBuild Beispielcode finden Sie in den [Amazon AgentCore Bedrock-Beispielen](https://github.com/awslabs/amazon-bedrock-agentcore-samples/).
## 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html).
Zusammenfassend muss Ihr Docker-Container die folgenden Anforderungen erfüllen:
+ **Port: Port** 8080 verfügbar machen (weitere Ports werden in Kürze unterstützt)
+ **Endpunkt:** Der `/invocations` Pfad muss verfügbar sein
+ **Architektur:** Muss ARM64-kompatibel sein
+ **Antwort:** Sollte das erwartete Nutzdatenformat verarbeiten
## 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-long-run.html) 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 wird`Healthy`, 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:**
+ Wenn Sie das Bedrock Agents SDK verwenden, verwenden Sie`context.session_id`.
+ Wenn Sie einen benutzerdefinierten Runtime-Server erstellen, extrahieren Sie ihn aus dem `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` HTTP-Header.
**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:
```
## 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:
+ Fehler beim Starten des Containers
+ Probleme mit Berechtigungen im Zusammenhang mit der Ausführungsrolle
+ Authentifizierungsprobleme mit dem Bearer-Token
**Resolution (Auflösung)**
Gehen Sie wie folgt vor, um das Problem zu beheben:
1. ** CloudWatch Protokolle überprüfen**: Alle Probleme beim Starten des Containers werden als 403 - angezeigt RuntimeClientError. Navigieren Sie zur folgenden CloudWatch Protokollgruppe, um nach Startfehlern zu suchen:
```
/aws/bedrock-agentcore/runtimes/-/[runtime-logs]
```
1. **Überprüfen Sie die Ausführungsrolle**: Stellen Sie sicher, dass die Ausführungsrolle Ihres Agenten über die erforderlichen Berechtigungen verfügt. Weitere Informationen finden Sie unter [AgentCore Runtime-Ausführungsrolle](runtime-permissions.md#runtime-permissions-execution-role).
1. **Authentifizierung validieren**: Stellen Sie für MCP-Protokollagenten sicher, dass Ihr Bearer-Token gültig und nicht abgelaufen ist.
## 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:
1. **Überprüfen Sie die richtige Protokollgruppe**: Stellen Sie sicher, dass Sie in der richtigen CloudWatch Protokollgruppe suchen. Das Standardmuster ist:
```
/aws/bedrock-agentcore/runtimes/-/runtime-logs
```
1. **Lokal zur Diagnose ausführen**: Wenn keine CloudWatch Protokolle vorhanden sind, versuchen Sie, den Agent-Container lokal mit genau derselben Payload auszuführen, die Sie für den Aufruf in AgentCore Runtime verwendet haben. Dies kann helfen, Probleme zu identifizieren, die in den Protokollen möglicherweise nicht sichtbar sind.
1. **Ausführliche Protokollierung aktivieren**: Aktualisieren Sie Ihren Agentencode so, dass er eine detailliertere Protokollierung enthält, insbesondere in Bezug auf die Eintrittspunkte und jegliche Fehlerbehandlungslogik.
## 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:
1. **Überprüfen Sie die Payload-Struktur**: Stellen Sie sicher, dass Ihre Payload-Struktur den Erwartungen Ihres Agenten entspricht. Achten Sie besonders auf:
+ Wenn Ihr Agentencode ein `input` Schlüsselwort in der Payload erwartet, stellen Sie sicher, dass Sie es angeben:
```
{
"input": {
"prompt": "Your question here"
}
}
```
+ Nicht nur:
```
{
"prompt": "Your question here"
}
```
1. **Dokumentation überprüfen**: Überprüfe das erwartete Eingabeformat in der Dokumentation.
## 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 () from runtime. Please check your CloudWatch logs for more information
```
**Resolution (Auflösung)**
Hier sind die häufigsten Fehlercodes und ihre Bedeutung:
**4.2.2 Unverarbeitbare Entität**
Dies passiert, wenn der Container auf Validierungsprobleme mit der Eingabe-Payload stößt.
Häufige Ursachen:
+ Fehlende Pflichtfelder in der Payload (z. B. fehlendes „Eingabefeld“)
+ Falsche Datentypen für Felder
+ Ungültiges Format für die Payload
**403 Forbidden**
Probleme mit der Authentifizierung oder Autorisierung.
Überprüfen Sie Ihre Bearer-Token- oder IAM-Berechtigungen.
**500 Interner Serverfehler**
Laufzeitausnahmen in Ihrem Agentencode.
Suchen Sie in den CloudWatch Protokollen nach detaillierten Stack-Traces.
## 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:
+ Führen Sie Ihren Agent-Container lokal mit demselben Docker-Image aus
+ Stellen Sie sicher, dass es mit genau derselben Payload funktioniert
**Nutzlasten vergleichen**
Stellen Sie die Konsistenz zwischen den Umgebungen sicher:
+ Stellen Sie sicher, dass die Payload-Struktur zwischen lokalen Tests und AgentCore Runtime-Aufrufen identisch ist
+ Achten Sie besonders auf die Verschachtelung von Feldern wie „Eingabe“ und „Eingabeaufforderung“
## 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
docker run -p 8080:8080
```
**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
```
## 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:
1. Installieren und starten Sie den MCP Inspector: `npx @modelcontextprotocol/inspector`
1. Connect zu Ihrem lokalen Server her unter `http://localhost:8000/mcp`
1. Verwenden Sie für bereitgestellte Agenten den richtigen URL-encoded Endpunkt
**Probleme bei der Authentifizierung**
Überprüfen Sie die Authentifizierungskonfiguration:
+ Stellen Sie sicher, dass das Bearer-Token in den Headern korrekt eingestellt ist
+ Stellen Sie sicher, dass Ihr Cognito-Benutzerpool korrekt eingerichtet ist
## 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:
1. Testen Sie die Basisverbindung: Stellen Sie sicher, dass Ihr Agent WebSocket Verbindungen akzeptiert unter `ws://localhost:8080/ws`
1. Testen Sie die Nachrichtenverarbeitung: Senden Sie einfache Textnachrichten und überprüfen Sie die Antworten
1. Testen Sie die Sitzungsverwaltung: Stellen Sie sicher, dass persistente Konversationen wie erwartet funktionieren
1. Testfehlerbehandlung: Stellen Sie sicher, dass Ihr Agent Verbindungsabbrüche und falsch formatierte Nachrichten ordnungsgemäß behandelt
**Probleme bei der Authentifizierung**
Überprüfen Sie die Authentifizierungskonfiguration für die bereitgestellten Agenten:
+ Für OAuth: Stellen Sie sicher, dass das Bearer-Token gültig und nicht abgelaufen ist
+ Für Sigv4: Stellen Sie sicher, dass die Eingabe in den Signaturalgorithmus korrekt ist, einschließlich der WebSocket URL, der Header und der Anforderungsmethode
+ Verwenden Sie die richtige Authentifizierungsmethode, die der Konfiguration Ihres Agenten entspricht
**Häufige Verbindungsprobleme**
Beheben Sie häufig auftretende WebSocket Verbindungsprobleme:
+ Stellen Sie sicher, dass das Nachrichtenformat den Erwartungen Ihres Agenten und Ihrer Kunden entspricht
+ Konfigurieren Sie die Nachrichtenframe-Fragmentierung oder implementieren Sie Chunking, um die Grenzwerte für die Nachrichten-Frame-Größe (64 KB) und die Nachrichten-Frame-Rate (250 Frames pro Sekunde) einzuhalten, um ein Schließen der Verbindung zu verhindern
## 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 [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html)Vorgangs 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 hat`Sampled=0`, wird dieser Kontext ohne Stichprobe an Runtime weitergegeben und die AgentCore Runtime überspringt die Span-Generierung für diesen Aufruf.
**Lösung:**
+ **Aktives Lambda-Tracing aktivieren:** Aktivieren Sie das X-Ray aktive Tracing für Ihre Lambda-Funktion, sodass sie Stichproben-Traces erzeugt (). `Sampled=1`
+ ** CloudWatch Transaktionssuche überprüfen:** Stellen Sie sicher, dass Sie die Einrichtung [unter Observability konfigurieren](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html) abgeschlossen haben und dass Ihr Trace-Segmentziel auf Logs gesetzt ist. CloudWatch
+ **Überprüfen Sie die Stichprobenentscheidung:** Protokollieren Sie die `_X_AMZN_TRACE_ID` Umgebungsvariable in Ihrer Lambda-Funktion. Falls dies angezeigt wird`Sampled=0`, ist die aktive Ablaufverfolgung nicht aktiviert oder ein Upstream-Aufrufer trifft die Entscheidung für die Stichprobenziehung.
## 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](runtime-filesystem-configurations.md).
**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:::file-system/*",
"Condition": {
"StringEquals": {
"s3files:AccessPointArn": ""
}
}
}
```
Stellen Sie für EFS sicher, dass Ihre Ausführungsrolle Folgendes hat:
```
{
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": "arn:aws:elasticfilesystem:::file-system/",
"Condition": {
"StringEquals": {
"elasticfilesystem:AccessPointArn": ""
}
}
}
```
Lassen Sie `s3files:ClientWrite` oder weg`elasticfilesystem: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:**
+ Stellen Sie sicher, dass das Dateisystem existiert:
+ S3-Dateien: `aws s3files list-file-systems --region `
+ EFS: `aws efs describe-file-systems --region `
+ Stellen Sie sicher, dass der Access Point existiert:
+ S3-Dateien: `aws s3files list-access-points --file-system-id --region `
+ EFS: `aws efs describe-access-points --file-system-id --region `
+ Stellen Sie sicher, dass Mount-Ziele in allen erforderlichen Availability Zones vorhanden sind:
+ S3-Dateien: `aws s3files list-mount-targets --file-system-id --region `
+ EFS: `aws efs describe-mount-targets --file-system-id --region `
+ Stellen Sie sicher, dass für jedes Mount-Ziel der Status Verfügbar angezeigt wird und sich in derselben VPC wie die Agent-Laufzeit befindet.
+ Wenn die Ressource gelöscht wurde, erstellen Sie sie neu und aktualisieren Sie die Agenten-Laufzeit mit dem neuen Access Point-ARN
## 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:**
+ **Sicherheitsgruppen auf Mount-Zielen überprüfen:** Stellen Sie sicher, dass die mit Ihren Mount-Zielen verknüpfte Sicherheitsgruppe **eingehendes TCP auf Port 2049** aus der Sicherheitsgruppe zulässt, die von Ihrer Agent-Laufzeit verwendet wird
+ **Überprüfen Sie die Sicherheitsgruppen während der Agent-Laufzeit:** Stellen Sie sicher, dass die von Ihrer Agent-Laufzeit verwendete Sicherheitsgruppe **ausgehendes TCP auf Port 2049** zur Mount-Zielsicherheitsgruppe zulässt
+ **Stellen Sie sicher, dass Mount-Ziele in den richtigen Availability Zones existieren:** Mount-Ziele müssen sich in denselben Availability Zones befinden wie die Subnetze, die auf Ihrer Agent-Laufzeit konfiguriert sind:
+ S3-Dateien: `aws s3files list-mount-targets --file-system-id --region `
+ EFS: `aws efs describe-mount-targets --file-system-id --region `
+ **Überprüfen Sie das Subnetz-Routing:** Stellen Sie sicher, dass Ihre Subnetze über das richtige Routing verfügen (lokale VPC-Route für den CIDR-Bereich)
## 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:**
+ **Überprüfen Sie die IAM-Berechtigungen:** Stellen Sie sicher, dass Ihre Ausführungsrolle `s3files:ClientWrite` (S3-Dateien) oder `elasticfilesystem:ClientWrite` (EFS) umfasst. Ohne Schreibberechtigungen ist der Mount schreibgeschützt. Weitere Informationen finden Sie unter [Berechtigungen für die Amazon Bedrock AgentCore Runtime-Ausführungsrolle](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html).
+ **Überprüfen Sie die POSIX-Berechtigungen:** Wenn das Verzeichnis einem anderen Benutzer als Ihrem Container-Prozess gehört, werden Schreibvorgänge verweigert. Entweder:
+ Stellen Sie den POSIXUser Ihres Access Points so ein, dass er dem entspricht, unter dem uid/gid Ihr Container läuft, sodass alle Operationen unter diesem Benutzer ausgeführt werden.
+ Setzen Sie die Verzeichnisberechtigungen auf 777, damit alle Benutzer schreiben können.
## 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` statt`USER 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:
+ **Verwenden Sie eine numerische USER-Direktive:** Ersetzen `USER myuser` Sie sie in Ihrem Dockerfile durch die numerische UID (z. B.). `USER 1000` Sie können die UID Ihres Benutzers finden, indem Sie sie innerhalb des Containers ausführen`id myuser`. Dadurch wird das Einhängen des Dateisystems vollständig vermieden.
+ **Bildebenen reduzieren:** Verwenden Sie mehrstufige Docker-Builds, um Ihr Bild auf weniger als 53 Ebenen zu reduzieren. Sie können die Anzahl der Ebenen Ihres Bilds wie folgt überprüfen:
```
docker inspect | jq '.[0].RootFS.Layers | length'
```
+ **Ebenen verkleinern:** Verwende `docker build --squash` oder ein ähnliches Tool, `docker-squash` um deine Bildebenen zu glätten.
## Bewährte Methoden
**Ermöglichen Sie eine umfassende Protokollierung**
Implementieren Sie eine gründliche Protokollierung in Ihrem Agenten:
+ Schließen request/response Sie die Anmeldung in Ihren Agenten ein
+ Protokollieren Sie kritische Pfade und Fehlerbedingungen
**Verwenden Sie eine strukturierte Fehlerbehandlung**
Implementieren Sie eine klare Fehlerberichterstattung:
+ Gibt klare Fehlermeldungen mit bestimmten Codes zurück
+ Nehmen Sie umsetzbare Informationen in die Fehlerantworten auf
**Testen Sie inkrementelle Änderungen**
Folgen Sie einem methodischen Testansatz:
+ Wenn Sie Ihren Agenten ändern, testen Sie ihn vor der Bereitstellung lokal
+ Überprüfen Sie die Payload-Kompatibilität sowohl mit lokalen als auch mit bereitgestellten Umgebungen
**Überwachen Sie die Leistung**
Richten Sie die Überwachung für Ihren Agenten ein:
+ Verwenden Sie CloudWatch Metriken, um Aufrufmuster zu verfolgen
+ Richten Sie Alarme für Fehlerraten und Latenz ein