Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Probleme mit dem Connect AI-Agenten beheben
Verwenden Sie dieses Thema, um häufig auftretende Probleme mit Connect AI-Agenten zu diagnostizieren und zu lösen.
**Topics**
+ [Logging und Tracing für Connect AI-Agenten](viewing-logs-for-connect-ai-agents-self-service.md)
+ [Beheben Sie Self-Service-Probleme von Agenturen](ts-agentic-self-service.md)
+ [Häufige Probleme](ts-common-self-service-issues.md)
+ [(Ältere) Self-Service-Probleme](ts-non-agentic-self-service.md)
# Logging und Tracing für Connect AI-Agenten
Verwenden Sie die folgenden Protokollierungs- und Ablaufverfolgungsoptionen, um Probleme mit dem Connect AI-Agenten effektiv zu beheben.
+ **ListSpans API (empfohlen für Orchestrator-AI-Agenten)**: Verwenden Sie die [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API, um die Ausführungsspuren des AI-Agenten für eine Sitzung abzurufen. Dies ist der empfohlene Ausgangspunkt für das Debuggen von Interaktionen mit Orchestrator-AI-Agenten, da er detaillierte Einblicke in die Orchestrierungsabläufe der Agenten, LLM-Interaktionen und Tool-Aufrufe bietet, sodass Sie nachvollziehen können, wie der AI-Agent eine Anfrage bearbeitet hat und welche Tools er ausgewählt und ausgeführt hat.
+ **CloudWatch Protokolle**: Aktivieren Sie die CloudWatch Protokollierung für Ihre Connect AI-Agenten, indem Sie die Schritte unter befolgen[Überwachen Sie Connect AI-Agenten](monitor-ai-agents.md).
Bei älteren Self-Service-Interaktionen werden Protokolleinträge mit dem Ereignistyp `TRANSCRIPT_SELF_SERVICE_MESSAGE` im folgenden Format generiert:
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1751414298692,
"event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
"session_id": "{UUID}",
"utterance": "[CUSTOMER]...",
"prompt": "{prompt used}",
"prompt_type": "SELF_SERVICE_PRE_PROCESS|SELF_SERVICE_ANSWER_GENERATION",
"completion": "{Response from model}",
"model_id": "{model id e.g.: us.amazon.nova-pro-v1:0}",
"session_message_id": "{UUID}",
"parsed_response": "{model response}"
}
```
Self-Service-Interaktionen mit Agenten generieren Protokolleinträge mit dem Ereignistyp. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Diese Einträge umfassen den vollständigen Orchestrierungskontext, z. B. die Eingabeaufforderung mit den Toolkonfigurationen, den Konversationsverlauf mit Toolaufrufen und -ergebnissen, die Fertigstellung des Modells und die Konfiguration des KI-Agenten. Das folgende Beispiel zeigt die wichtigsten Felder:
```
{
"assistant_id": "{UUID}",
"event_timestamp": 1772748470993,
"event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
"session_id": "{UUID}",
"prompt": "{full prompt including system instructions, tool configs, and conversation history}",
"prompt_type": "ORCHESTRATION",
"completion": "{model response with message and tool use}",
"model_id": "{model id e.g.: us.anthropic.claude-haiku-4-5-20251001-v1:0}",
"parsed_response": "{parsed customer-facing message}",
"generation_id": "{UUID}",
"ai_agent_id": "{UUID}"
}
```
+ **Amazon Lex-Protokollierung (nur Self-Service)**: Aktivieren Sie die Amazon Lex Lex-Protokollierung, indem Sie die Schritte unter [Fehler mit Fehlerprotokollen in Amazon Lex V2 protokollieren](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html) befolgen.
+ **Amazon-Connect-Protokollierung**: Aktivieren Sie die Amazon-Connect-Protokollierung, indem Sie dem Amazon-Connect-Flow einen [Protokollierungsverhalten festlegen](set-logging-behavior.md)-Flow-Block hinzufügen.
# Beheben Sie Self-Service-Probleme von Agenturen
[Die folgenden Probleme betreffen speziell den Self-Service von Agenturen.](agentic-self-service.md)
## Der KI-Agent reagiert nicht auf Kunden
Wenn Ihr KI-Agent Anfragen bearbeitet, Kunden aber keine Antworten erhalten, fehlen in der Orchestrierungsaufforderung möglicherweise die erforderlichen Anweisungen zur Nachrichtenformatierung.
Die KI-Agenten von Orchestrator zeigen Kunden nur dann Nachrichten an, wenn die Antwort des Modells in `` Tags verpackt ist. Wenn Ihre Aufforderung das Modell nicht anweist, diese Tags zu verwenden, werden dem Kunden keine Antworten übermittelt.
**Lösung**: Stellen Sie sicher, dass Ihre Orchestrierungsaufforderung Formatierungsanweisungen enthält, nach denen das Modell die Antworten in `` Tags verpackt. Weitere Informationen finden Sie unter [Analysieren von Nachrichten](use-orchestration-ai-agent.md#message-parsing).
## Fehler beim Aufruf des MCP-Tools
Wenn Ihr AI-Agent die MCP-Tools während einer Konversation nicht aufrufen kann, überprüfen Sie Folgendes:
+ **Sicherheitsprofilberechtigungen** — Stellen Sie sicher, dass das Sicherheitsprofil des AI-Agenten Zugriff auf die spezifischen MCP-Tools gewährt, die er benötigt. Der AI-Agent kann nur Tools aufrufen, für deren Zugriff er ausdrücklich berechtigt ist.
+ **Gateway-Konnektivität** — Stellen Sie sicher, dass das Amazon Bedrock AgentCore Gateway korrekt konfiguriert ist und dass die Discovery-URL gültig ist. Stellen Sie sicher, dass die Zielgruppen für eingehende Authentifizierung auf die Gateway-ID eingestellt sind. Überprüfen Sie den Gateway-Status in der AgentCore Konsole.
+ **Integrität der API-Endpunkte** — Stellen Sie sicher, dass die Backend-API oder Lambda-Funktion hinter dem MCP-Tool ausgeführt wird und korrekt reagiert. Überprüfen Sie die CloudWatch Protokolle auf Fehler im Zieldienst.
## IAM-Berechtigungen für MCP-Tools
Wenn MCP-Tool-Aufrufe die Fehlermeldung „Zugriff verweigert“ zurückgeben, stellen Sie sicher, dass die IAM-Rollen über die erforderlichen Berechtigungen verfügen:
+ **Amazon Bedrock AgentCore Gateway-Rolle** — Die Ausführungsrolle des Gateways muss berechtigt sein, die Backend APIs - oder Lambda-Funktionen aufzurufen, mit denen Ihre MCP-Tools eine Verbindung herstellen.
+ **Serviceverknüpfte Amazon Connect Connect-Rolle** — Die mit dem Service verknüpfte Amazon Connect Connect-Rolle muss über die Berechtigung verfügen, das Amazon Bedrock Gateway aufzurufen. AgentCore
# Häufige Probleme
## Bündeln Sie das neueste AWS SDK mit Ihren Lambda-Funktionen
Wenn Sie Connect AI-Agenten APIs direkt von Lambda-Funktionen aus aufrufen, müssen Sie die neueste Version des AWS SDK zusammen mit Ihrem Funktionscode paketieren und bündeln. Die Lambda-Laufzeitumgebung kann eine ältere Version des SDK enthalten, die die neuesten API-Modelle und Funktionen für Connect AI-Agenten nicht unterstützt.
**Symptome**: Wenn Sie eine veraltete SDK-Version verwenden, treten möglicherweise Ausnahmen bei der Parametervalidierung auf oder fordern, dass Eingabeparameter stillschweigend ignoriert werden.
Um Abweichungen beim API-Modell zu vermeiden, sollten Sie das neueste AWS SDK als Abhängigkeit in Ihr Bereitstellungspaket oder als Lambda-Schicht aufnehmen, anstatt sich auf das von der Lambda-Laufzeit bereitgestellte SDK zu verlassen. Die Schritte zum Bündeln des SDK variieren je nach Sprache. Informationen zu Node.js finden Sie beispielsweise unter [Erstellen eines Bereitstellungspakets mit Abhängigkeiten](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies). Informationen zu anderen Sprachen finden Sie in der entsprechenden Paketierungsdokumentation für Lambda Deployment. Informationen zur gemeinsamen Nutzung des SDK für mehrere Funktionen finden Sie unter [Lambda-Schichten](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).
# (Ältere) Self-Service-Probleme
Die folgenden Probleme betreffen speziell [ältere](generative-ai-powered-self-service.md) Self-Service-Systeme.
## Kunden erhalten unerwartet die Meldung „Eskalation an Kundendienstmitarbeiter...“
Eine unerwartete Eskalation an einen Kundendienstmitarbeiter tritt auf, wenn es während der Interaktion mit dem Self-Service-Bot zu einem Fehler kommt oder wenn das Modell keine gültige `tool_use`-Antwort für `SELF_SERVICE_PRE_PROCESS` liefert.
### Fehlerbehebungsschritte
1. **Überprüfen Sie die Connect AI-Agent-Protokolle**: Untersuchen Sie das `completion` Attribut im zugehörigen Protokolleintrag.
1. **Überprüfen Sie den Grund für den Abbruch**: Vergewissern Sie sich, dass `stop_reason` den Wert `tool_use` aufweist.
1. **Überprüfen Sie die analysierte Antwort**: Prüfen Sie, ob das Feld `parsed_response` ausgefüllt ist, da dies die Antwort darstellt, die Sie vom Modell erhalten werden.
### Bekanntes Problem mit Claude 3 Haiku
Wenn Sie Claude 3 Haiku für die Self-Service-Vorverarbeitung verwenden, gibt es ein bekanntes Problem, bei dem das `tool_use`-JSON als Text generiert wird, was zu einem `stop_reason` mit dem Wert `end_turn` statt `tool_use` führt.
**Lösung**: Aktualisieren Sie den benutzerdefinierten Prompt, sodass die Zeichenfolge des `tool_use`-JSON in ``-Tags eingeschlossen wird, indem Sie diese Anweisung hinzufügen:
```
You MUST enclose the tool_use JSON in the tag
```
## Self-Service-Chat oder Sprachanruf wird unerwartet beendet
Dieses Problem kann aufgrund von Timeouts bei Amazon Lex oder aufgrund einer falschen Amazon Nova Pro-Konfiguration auftreten. Diese Probleme werden im Folgenden beschrieben.
### Zeitüberschreitungen in Amazon Lex
+ **Symptome**: Die Amazon-Connect-Protokolle enthalten für den [Kundeneingabe abrufen](get-customer-input.md)-Block den Eintrag „Interner Serverfehler“
+ **Ursache**: Bei der Bereitstellung von Ergebnissen durch den Self-Service-Bot innerhalb der 10-Sekunden-Frist ist eine Zeitüberschreitung aufgetreten. Timeout-Fehler werden nicht in den Connect AI-Agentenprotokollen angezeigt.
+ **Lösung**: Vereinfachen Sie den Prompt, indem Sie komplexe Argumentationen vermeiden und dadurch die Bearbeitungszeit verkürzen.
### Konfiguration von Amazon Nova Pro
Wenn Sie Amazon Nova Pro für benutzerdefinierte KI-Prompt verwenden, stellen Sie sicher, dass die tool\$1use-Beispiele [Python-kompatibel](create-ai-prompts.md#nova-pro-aiprompt) sind.