| Add-on | AI Agents – Advanced |
Der Integration Builder ist ein leistungsstarkes Tool, mit dem Sie Ihren AI Agent ohne Programmierung mit jeder API oder Datenquelle verbinden können – auch wenn Sie über keine besonderen Kenntnisse auf dem Gebiet der Technik oder Informatik verfügen. Personalisieren Sie Ihr Chat-Erlebnis und steigern Sie den Anteil automatisierter Lösungen mit dynamischen Inhalten.
Stellen Sie sich einen AI Agent vor, der nahtlos auf Kundeninformationen aus Ihrem Backoffice-System zugreift, Daten aus jeder anderen externen Datenquelle abruft oder mit externen Anwendungen interagiert, ohne dass Sie auch nur eine Zeile Code schreiben müssen.
Die dynamischen Inhaltsfunktionen des Integration Builders sorgen dafür, dass Ihr AI Agent Daten in Echtzeit abfragen, analysieren und transformieren kann, und versetzen ihn in die Lage, gezielt auf die individuellen Anforderungen des jeweiligen Benutzers zugeschnittene Antworten, Empfehlungen und Lösungen bereitzustellen.
Mit seiner benutzerfreundlichen, intuitiven und funktionalen No-Code-Oberfläche bietet der Integration Builder ein Höchstmaß an Flexibilität und Anpassbarkeit auch für Benutzer ohne besondere technische Kenntnisse.
In diesem Beitrag stellen wir die wichtigsten Funktionen und Vorteile des Integration Builders vor und zeigen Ihnen Schritt für Schritt, wie Sie Ihren AI Agent mit einer beliebigen API oder Datenquelle verbinden.
Erste Schritte
Klicken Sie im seitlichen Navigationsmenü auf „API-Integrationen“, um den Integration Builder aufzurufen. Sie gelangen zu einer Übersichtsliste, in der Sie mühelos auf alle Ihre zukünftigen Integrationen zugreifen können. Je nach Ihrem Onboarding-Verfahren wird hier anfangs entweder keine API-Integration oder eine Beispielintegration angezeigt.
Klicken Sie oben rechts auf „Integration hinzufügen“, um eine neue Integration zu erstellen.
Geben Sie einen Namen für die Integration ein.
Fügen Sie eine kurze Beschreibung mit weiterem Kontext hinzu.
Wenn Sie fertig sind, klicken Sie auf „Speichern“, um zur Konfigurationsseite der Integration zu gelangen.
Wenn in der seitlichen Navigationsmenü keine API-Integrationen angezeigt werden, sind Sie wahrscheinlich kein Client-Administrator. Derzeit können nur Client-Administratoren auf den Integration Builder zugreifen. Bitten Sie gegebenenfalls Ihren Kundenbetreuer, Ihnen die erforderlichen Zugriffsberechtigungen zu erteilen.
Für den Fall, dass Sie lieber mit audiovisuellen Medien lernen, haben wir unten ein Einführungsvideo von Chloe aus unserem Custom Engineering-Team eingebunden.
Anfrageparameter
Damit die API die gewünschten Antworten liefert, müssen Sie zunächst die erforderlichen Anfrageparameter konfigurieren. Diese Anfrageparameter enthalten Informationen, die aus der Konversation übernommen werden und dazu dienen, die Details der jeweiligen API-Anfrage zu definieren. Wenn Sie beispielsweise bestimmte Benutzerinformationen abrufen möchten, die während der Konversation angezeigt werden sollen, muss die Benutzer-ID in der Anfrage enthalten sein. Diese sorgt dafür, dass die API-Antwort Daten enthält, die für den aktuellen Benutzer oder Besucher im Chat relevant sind.
Das folgende Beispiel zeigt einen konfigurierten Anfrageparameter.
Neben dem Schlüssel und dem Typ des Anfrageparameters können Sie auch einen Testwert angeben. Dieser Testwert wird benötigt, wenn Sie während der Konfiguration die Testfunktion oben rechts im Fenster verwenden möchten. In einer echten Live-Konversation wird der Wert vor der eigentlichen Anfrage an die API-Integration übergeben. Da beim Testen jedoch der Kontext der aktuellen Live-Konversation fehlt, ist die Angabe des Testwerts für einen erfolgreichen API-Aufruf notwendig.
Mit dem Kontrollkästchen „Erforderlich“ können Sie festlegen, ob der Anfrageparameter optional ist oder vor dem Aufruf der API-Integration in der Konversation erfasst werden muss, sofern er nicht bereits in der Sitzung gespeichert wurde.
Ob Anfrageparameter eingebunden werden müssen, hängt von den spezifischen Anforderungen der aufzurufenden API ab. Bei manchen APIs werden die Anfrageparameter an die URL angehängt, bei anderen hingegen in der Kopfzeile oder im Anforderungstext übergeben. Bitte sehen Sie in Ihrer API-Dokumentation nach, wo Sie die Parameter einbinden müssen. Anschließend können Sie den Anfrageparameter der URL, der Kopfzeile oder dem Anforderungstext hinzufügen, indem Sie einfach auf den Schlüssel in doppelten geschweiften Klammern verweisen – {{userID}}.
Umgebungen
Nachdem Sie den Anfrageparameter hinzugefügt haben, können Sie im Abschnitt „Umgebung“ die ersten Einstellungen für den API-Aufruf vornehmen. Neben dem Umgebungsnamen, der beim Testen der Integration oder im Dialoggenerator angezeigt wird, müssen Sie wie in der jeweiligen API-Dokumentation beschrieben die Methode, die URL und den Autorisierungstyp auswählen.
Autorisierungstypen
Folgende Autorisierungstypen stehen zur Auswahl:
| Autorisierungstyp | Beschreibung | Beispiel |
| API-Schlüssel | Ein einfacher API-Schlüssel, der vom Eigentümer der API bereitgestellt werden sollte |  |
| Inhaber-Token | Ein weiteres Token, das vom Eigentümer der API bereitgestellt werden sollte |  |
| Standardauthentifizierung | API-Authentifizierung mit Benutzername und Kennwort |  |
| OAuth 2.0 | API-Authentifizierung mit von der Gewährungsart abhängigen Informationen |  |
| Angepasst | Autorisierung über temporäres Token | Weitere Informationen finden Sie unter Verwenden der angepassten Autorisierung mit dem Integration Builder. |
Denken Sie daran, das Autorisierungstoken für alle Autorisierungstypen (ausgenommen keine Autorisierung) in die Anfrage aufzunehmen, indem Sie es der Kopfzeile als {{apiToken}} hinzufügen. Ein Beispiel hierfür finden Sie im Abschnitt „Kopfzeilen“.
Kopfzeilen
Kopfzeilen enthalten zusätzliche Informationen zur Anfrage oder zur Kommunikation zwischen Client und Server. Diese werden in Form von Schlüssel-Wert-Paaren in den Kopfbereich der Anfrage eingefügt. Beispiele für häufig verwendete Kopfzeilen sind:
- Content-Type: Gibt das Format der Daten im Anforderungstext an (z. B. JSON, XML, Formulardaten).
- Authorization: Stellt Anmeldedaten oder Token für die Authentifizierung des anfragenden Clients bereit.
- User-Agent: Gibt den User Agent an, der die Anfrage stellt. In der Regel ist das der Webbrowser oder die Client-Anwendung.
- Accept: Informiert den Server über die vom Client akzeptierten Antwortformate.
- Cache-Control: Definiert Caching-Richtlinien für den Server oder zwischengeschaltete Caches.
- X-Requested-With: Gibt die Art der vom Client gestellten Anfrage an (z. B. XMLHttpRequest oder Fetch API).
Anforderungstext
Der Anforderungstext einer API-Anfrage enthält die an die API gesendeten Daten. Er wird in der Regel in Anfragen verwendet, die Eingabedaten für die Verarbeitung oder Datenmanipulation aufseiten der API erfordern. Je nach API und aufgerufenem Endpunkt kann der Anforderungstext unterschiedliche Formate aufweisen, z. B. JSON, XML, Nur-Text oder Formulardaten. In unserem Fall wird derzeit nur das JSON-Format unterstützt.
Verwalten von Umgebungen
Um die Handhabung von Sandbox- und Produktionsumgebungen für APIs zu vereinfachen, haben wir das Konzept der Umgebungen in den Integration Builder aufgenommen. Neben der standardmäßigen Hauptumgebung, die beim Einrichten einer Integration automatisch erstellt wird, können Sie weitere Umgebungen bereitstellen.
Diese zusätzlichen Umgebungen ermöglichen Ihnen, die URL, die Authentifizierungsdetails, die Kopfzeilen und den Anforderungstext gezielt für API-Anfragen an bestimmte Sandbox- oder Produktionsumgebungen anzupassen.
Klicken Sie auf das Pluszeichen (+) neben dem Abschnitt „Umgebungen“, um eine neue Umgebung zu erstellen. Wenn Sie eine vorhandene Umgebung replizieren möchten, setzen Sie den Mauszeiger auf die gewünschte Umgebung, klicken Sie auf die drei Punkte und wählen Sie im Menü die Option „Duplizieren“. Beachten Sie, dass jeweils nur eine Umgebung als Standardumgebung festgelegt werden kann, die ganz oben in der Liste erscheint und – sofern nicht anders eingestellt – im Dialoggenerator automatisch ausgewählt wird.
Eine Umgebung, die von keinem AI Agent verwendet wird und weder die einzige noch die Standardumgebung ist, kann gelöscht werden. Zum Ändern der Standardeinstellungen wählen Sie einfach im Drei-Punkte-Menü die gewünschte Option aus.
Testfunktion
Nachdem Sie die API-Anfrage eingerichtet haben, sollten Sie alle Konfigurationseinstellungen überprüfen. Oben rechts im Integration Builder finden Sie eine praktische Testfunktion, die diesen Vorgang vereinfacht.
Die betreffende Schaltfläche ist mit der Beschriftung „Test“ und dem Namen der Standardumgebung gekennzeichnet. Sie bewirkt, dass der Integration Builder eine Anfrage mit den Informationen aus den Anfrageparametern und den Umgebungsabschnitten an die API sendet. Die von der API zurückgegebene Antwort wird dann im Abschnitt „Integration testen“ auf der rechten Seite angezeigt. Wenn Sie die API mit den Anfragedetails aus einer anderen Umgebung testen möchten, wählen Sie einfach die gewünschte Umgebung im Dropdownmenü der Testfunktion aus und klicken Sie erneut auf die Schaltfläche „Test“.
Inhalt der Antwort
Die von der API zurückgegebene Antwort wird im Abschnitt „Integration testen“ des Integration Builders angezeigt. Sie ist in folgende Objekte untergliedert:
| Objekte | Inhalte | Beispiel |
| statusCode | Das statusCode-Objekt der HTTP-Antwort zeigt an, ob die betreffende HTTP-Anfrage erfolgreich abgeschlossen wurde. Weitere Infos. | "statusCode": 200 |
| data | Bei einer erfolgreichen Anfrage werden die relevanten Daten der API im data-Objekt angezeigt. Bei einer erfolglosen Anfrage hingegen stellt dieses Objekt zusätzliche Informationen in Form der entsprechenden Statuscodes bereit. |
"data": { "name": "Deutschland", "capital": "Berlin", "region": "Europa", "population": 83240525, "area": 357114 } |
| requestParameters | Im requestParameters-Objekt zeigt der Integration Builder die beim Aufruf der API verwendeten Anfrageparameter zusammen mit den zugehörigen Testwerten an. |
"requestParameters": { "country": "de"} |
Achten Sie darauf, die Integration zu speichern, bevor Sie die Testfunktion erneut verwenden, um eine geänderte Konfiguration zu überprüfen.
Szenarien
Jede neu erstellte Integration enthält drei vorkonfigurierte Szenarien. Zwei dieser Szenarien können je nach Bedarf angepasst oder gelöscht werden, das dritte Szenario namens „Fallback“ hingegen lässt sich nicht bearbeiten. Es dient als primäre Fallback-Option für den Fall, dass keines der vorherigen Szenarien ausgelöst wird.
| Szenario | Standardanfrage | Beschreibung |
| Success | statusCode >= 200 und statusCode < 300 | Dieses Szenario sollte den bevorzugten Pfad (zufrieden) bei einem statusCode von zwischen 200 und 300 erfassen. |
| Failure | statusCode < 200 oder statusCode >= 300 | Dieses Szenario sollte den nicht erfolgreichen Pfad bei einem statusCode erfassen, der nicht im 200er-Bereich liegt. |
| Fallback | - | Dieses Fallback-Szenario gewährleistet, dass immer mindestens ein Szenario ausgelöst wird. |
Die Szenarien entsprechen den verschiedenen Zweigen, denen die Konversation nach dem Aufruf der API-Integration folgen kann.
Szenarioabfragen
Für jede API-Integration kann nur ein Szenario ausgelöst werden. Die Logik zur Bestimmung des während einer Konversation ausgelösten Szenarios basiert auf den Szenarioabfragen und der Reihenfolge, in der die Szenarien definiert sind.
Die Szenarioabfragen stellen die Bedingungen dar, die erfüllt sein müssen, damit ein bestimmtes Szenario ausgelöst wird. Um festzustellen, ob eine Bedingung erfüllt ist, prüft der Integration Builder die Szenarioabfrage sowie die in der API-Antwort enthaltenen Daten. Zu den häufig verwendeten Datenfeldern gehören Statuscodes, API-spezifische Daten im Datenobjekt der API-Antwort und möglicherweise Werte aus den Anfrageparametern.
Die Standard-Szenarioabfrage des Szenarios „Success“ setzt voraus, dass der statusCode der API-Antwort zwischen 200 und 300 liegt. Wenn diese Bedingung erfüllt ist, wird das Szenario „Success“ ausgelöst.
Da die Standard-Szenarioabfragen geändert und neue Szenarien hinzugefügt werden können, ist es möglich, dass basierend auf der API-Antwort mehrere Szenarioabfragen aus verschiedenen Szenarien wahr sind. Wenn dies der Fall ist, bestimmt die Reihenfolge der Szenarien, welches Szenario ausgelöst wird.
Um ein visuelles Feedback zu geben, haben wir eine Funktion implementiert, die anzeigt, welches Szenario aufgrund der aktuellen API-Antwort ausgelöst würde. Außerdem zeigt diese Funktion an, welche Szenarien theoretisch ausgelöst werden könnten, aber aufgrund ihrer Position in der Reihenfolge der Szenarien nicht ausgelöst würden. Darüber hinaus werden Szenarien gekennzeichnet, die nicht ausgelöst würden, weil ihre Bedingungen nicht erfüllt sind.
| Kriterien stimmen überein | Visualisierung | Beschreibung |
| Kriterien erfüllt, erstes in der Reihenfolge |  |
Der blaue Punkt kennzeichnet das Szenario, das ausgelöst würde. |
| Kriterien nicht erfüllt |  |
Der leere Punkt kennzeichnet Szenarien, die nicht ausgelöst würden. |
| Kriterien erfüllt, aber nicht erstes in der Reihenfolge |  |
Der graue Punkt kennzeichnet Szenarien, die nur theoretisch ausgelöst werden könnten. |
Um die Reihenfolge der Szenarien zu ändern, klicken Sie einfach auf ein Szenario und ziehen Sie es an die gewünschte Position. Mit Ausnahme des Fallback-Szenarios, das immer an letzter Stelle steht, können Sie die Reihenfolge nach Belieben anpassen.
Sitzungsparameter
Beim Konfigurieren der einzelnen Szenarien können Sie die Konversation mit verschiedenen Datenpunkten aus Ihrem Backend-System anreichern. Sie können angeben, welche Daten für jedes Szenario zugänglich sein sollen, indem Sie die relevanten Informationen aus der API-Antwort transformieren und in Sitzungsparametern speichern. Diese Sitzungsparameter können dann beim Aufbau der Dialoge verwendet werden, um den Besuchern Informationen zu präsentieren oder den zugrunde liegenden Workflow abzubilden.
Ein Sitzungsparameter wird durch ein Schlüssel-Wert-Paar definiert. Der Schlüssel wird im Dialoggenerator als Referenz verwendet, während die Anfrage dazu dient, bestimmte Daten aus der API-Antwort zu transformieren und zu extrahieren, um den Wert zu speichern. Der Integration Builder zeigt in Echtzeit an, wie der gespeicherte Wert basierend auf der aktuellen Antwort im Antwortwertfeld erscheinen wird.
In der oben stehenden Abbildung ist der Sitzungsparameterschlüssel als „capital“ definiert und kann im Dialoggenerator in doppelten geschweiften Klammern referenziert werden – {{capital}}. Die Abfrage bestimmt, welche Daten transformiert und als Wert für den Sitzungsparameter gespeichert werden sollen. In diesem Fall wird der Inhalt aus dem Feld „capital“ im Datenobjekt der API-Antwort extrahiert.
Abfragesprache – JSONata
JSONata dient als Abfragesprache für Abfragen auf Szenario- und Sitzungsparameterebene. Sie basiert auf dem Prinzip, dass einfache Abfragen auch für technisch weniger versierte Benutzer leicht zu schreiben sein sollten. JSONata zeichnet sich durch eine flache Lernkurve aus und kann daher rasch produktiv eingesetzt werden. Mit JSONata können Sie grundlegende Funktionen ausführen, Daten transformieren und sogar verschiedene Datenpunkte zusammenführen.
JSONata ist eine öffentlich dokumentierte Abfrage- und Transformationssprache. Die Dokumentation finden Sie hier.
0 Kommentare
Melden Sie sich an, um einen Kommentar zu hinterlassen.