Es kann vorkommen, dass sich eine Integration zwischen dem Arbeitsbereich für AI Agents und einem anderen System nicht wie erwartet verhält und Sie eine Fehlerbehebung durchführen müssen. In diesem Beitrag werden einige Schritte beschrieben, mit denen Sie versuchen können, Integrationsprobleme zu beheben.
In diesem Beitrag werden folgende Themen behandelt:
- Integration im Integration Builder testen
- Anfrageparameter auf Übereinstimmung prüfen
- Konversationsprotokolle auf Sitzungsparameter überprüfen
- Rohwerte im Fehlerszenario ausgeben
- HTTP-Statuscode überprüfen
- Technische Fehler im Dialog untersuchen
Verwandte Beiträge:
Integration im Integration Builder testen
Der erste Schritt bei der Fehlerbehebung besteht darin, die Integration im Integration Builder zu testen. Vergewissern Sie sich, dass Sie eine Antwort erhalten und in den Sitzungsparametern die richtigen Daten angezeigt werden.
Anfrageparameter auf Übereinstimmung prüfen
Die Anfrageparameter, die Sie im Integration Builder verwenden – sei es in der URL-Query, im Anfragetext oder in der Kopfzeile –, müssen exakt mit den im Dialog erfassten Parametern übereinstimmen.
Überprüfen Sie folgende Punkte:
- Sind alle Parameter richtig geschrieben?
- Wenn Sie den Namen eines Parameters an irgendeiner Stelle im Dialog korrigiert oder aktualisiert haben, haben Sie ihn in der Integration entsprechend angepasst?
- Stimmt die Schreibweise exakt überein? Bei Parametern wird zwischen Groß- und Kleinschreibung unterschieden.
Tipp: Wir empfehlen, für alle Anfrage- oder Sitzungsparameter eine einheitliche Namenskonvention zu verwenden, z. B. lowerCamelCase oder snake_case.
Konversationsprotokolle auf Sitzungsparameter überprüfen
Überprüfen Sie die Konversationsprotokolle auf weitere Informationen, beispielsweise Sitzungsdaten. Sie können mit der API nach Konversationen suchen, indem Sie nach Stichwörtern filtern. Wenn die Konversation die API verwendet, können Sie nach ihr suchen.
Klicken Sie in den Konversationsprotokollen oben links auf „Filter hinzufügen“.
Navigieren Sie im Menü auf der linken Seite zu „Labels“.
Hier können Sie die Liste der Integrationen nach Namen und nach dem Szenario filtern (z. B. Erfolg, Fehler oder API-Fehler).
Der Name von Integrationen, die im Integration Builder erstellt wurden, setzt sich aus dem Präfix „API“, der Bezeichnung der Integration und der Bezeichnung des Szenarios zusammen.
Ein Beispiel aus dem unten stehenden Screenshot lautet „API-Chloe Demo: Apple Cart-Success“:
- API = Präfix
- Chloe Demo: Apple Cart = Bezeichnung der Integration
- Success = Bezeichnung des Szenarios
Wenn Sie den Mauszeiger auf das Stichwortsymbol einer Konversation setzen, werden die mit ihr verknüpften Stichwörter angezeigt.
Wenn Sie bei einer Stichwortsuche nur feststellen möchten, warum bei einer Konversation ein API-Fehler aufgetreten ist, suchen Sie nach „apiError“.
Wählen Sie anschließend die Konversation aus, um weitere Informationen zu anzuzeigen.
In der Konversation können Sie dann die vorhandenen Sitzungsdaten überprüfen.
Klicken Sie zu diesem Zweck oben rechts auf „Details“.
Die Konversationsübersicht wird angezeigt. Klicken Sie als Nächstes auf „Sitzungsdaten“.
Nun können Sie die Sitzungsdaten im Chat sehen. Von Interesse sind in diesem Zusammenhang die von der API-Integration stammenden Sitzungsparameter am Ende der Liste.
Dialog auf Sitzungsparameter überprüfen
Um rasch zu überprüfen, ob die Sitzungsparameter für die Sitzung vorhanden sind, können Sie sie im Dialog in einer AI Agent-Nachricht protokollieren. Am sichersten ist es, wenn Sie den Dialog in einer Staging-Umgebung testen. Falls Sie eine Live-Integration verwenden, sollten Sie unbedingt darauf achten, den Dialog beim Testen nicht zu speichern.
In der unten stehenden AI Agent-Nachricht werden die Sitzungsparameter protokolliert, sodass sie beim Testen sichtbar sind.
Rohwerte im Fehlerszenario ausgeben
Fassen Sie alle Daten in der Antwort in einer Zeichenfolge zusammen, indem Sie „data“ in die Funktion „$string(data)“ einschließen. Diese kann dann beim Testen im Fehlerszenario protokolliert werden, um die Rückgabe zu überprüfen.
HTTP-Statuscode überprüfen
Achten Sie beim Testen der Integration darauf, den zurückgegebenen HTTP-Statuscode zu überprüfen. Dieser wird in der Antwort auf der rechten Seite mit dem Schlüssel „statusCode“ angezeigt.
2xx: Erfolg
-
200 OK: Die Anfrage war erfolgreich und der Server hat mit den erwarteten Daten geantwortet.
- Dies ist die ideale Antwort beim Testen einer Integration.
4xx: Clientfehler
Fehler in diesem Bereich weisen im Allgemeinen auf ein Problem mit der gesendeten Anfrage im Integration Builder hin.
-
400 Bad Request: Der Server konnte die Anfrage aufgrund einer ungültigen Syntax oder fehlender Parameter nicht verstehen.
- Prüfen Sie die Nutzlast der Anfrage auf Fehler, fehlende Felder oder falsche Formatierung.
-
401 Unauthorized: Eine erforderliche Authentifizierung wurde nicht durchgeführt oder ist ungültig.
- Überprüfen Sie den API-Schlüssel, das Token oder andere Authentifizierungsdaten. Überprüfen Sie die Autorisierungskopfzeilen.
-
403 Forbidden: Der Server hat die Anfrage verstanden, aber die Autorisierung verweigert.
- Stellen Sie sicher, dass die IP-Adressen in der Zulassungsliste verzeichnet sind, oder überprüfen Sie die Berechtigungen für die API.
-
404 Not Found: Die angeforderte Ressource wurde auf dem Server nicht gefunden.
- Überprüfen Sie die URL oder den Endpunkt. Stellen Sie sicher, dass der richtige Pfad angegeben und die Ressource vorhanden ist.
5xx: Serverfehler
Fehler in diesem Bereich deuten normalerweise auf ein Problem mit dem Backend-Server hin.
-
500 Internal Server Error: Ein allgemeiner Fehler, der auf ein Problem mit dem Backend-Server hindeutet.
- Wenden Sie sich an das Backend-Team mit Details zur Anfrage, damit das Team eine weitergehende Fehlerbehebung durchführen kann.
-
502 Bad Gateway: Der Server hat eine ungültige Antwort von einem Upstream-Server erhalten.
- Dies deutet häufig auf ein Problem mit den internen Diensten oder Abhängigkeiten des Backends hin.
-
503 Service Unavailable: Der Server kann die Anfrage derzeit nicht bearbeiten. Mögliche Ursachen hierfür sind Überlastung oder Wartungsarbeiten.
- Versuchen Sie es einige Zeit später erneut und prüfen Sie, ob Ausfallzeiten geplant sind.
-
504 Gateway Timeout: Der Server hat keine rechtzeitige Antwort von einem Upstream-Server erhalten.
- Stellen Sie sicher, dass der Backend-Dienst betriebsbereit ist, und überprüfen Sie ihn auf Latenzprobleme.
Technische Fehler im Dialog untersuchen
Es kann vorkommen, dass eine Meldung angezeigt wird, die auf einen technischen Fehler hinweist. Eine solche Meldung enthält den folgenden Text:
„Es scheint ein technisches Problem vorzuliegen. Ich hoffe, bald wieder einsatzbereit zu sein.“
In diesem Fall wird das Problem höchstwahrscheinlich durch einen Fehler im Dialog und nicht durch die Integration selbst verursacht. Hier sind einige Tipps:
- Überprüfen Sie den Dialog, um sicherzustellen, dass die Integration im Konversationsfluss erreicht wird. Verwenden Sie Puffermeldungen zur Bestätigung und prüfen Sie, ob Wechselwirkungen zwischen Schaltflächenfunktionen, defekte Links oder Kreuzverweise vorliegen.
- Stellen Sie sicher, dass alle erforderlichen Parameter vorhanden sind. Wenn erforderliche Parameter fehlen, werden Fehler ausgelöst, bevor die Integration ausgeführt wird.
- Stellen Sie sicher, dass bei dynamischen Inhalten wie Karten und Karussells alle Felder ausgefüllt sind. Nicht definierte Werte, leere Werte oder Nullwerte können die Funktion dieser Komponenten beeinträchtigen und Fehler verursachen.