Erweiterung aus einem Schritt aufrufen

Gehen Sie wie folgt vor, um eine angepasste Erweiterung über eine Aktion aufzurufen:

1. Erstellen oder öffnen Sie im Aktionseditor den Schritt, von dem aus Sie die Erweiterung aufrufen wollen.

2. Optional: Geben Sie im Feld Assistent sagt eine Nachricht ein, die dem Kunden angezeigt werden soll, bevor die Erweiterung aufgerufen wird (z. B. Please wait while I retrieve your account balance...).

   Die Ausgabe dieses Schritts wird an den Kanal gesendet, wobei die globale Kontextvariable skip_user_input auf true gesetzt ist. Diese Variable weist den Kanal an, die Nachricht anzuzeigen, aber nicht , den Kunden zur Eingabe einer Antwort aufzufordern. Stattdessen sendet der Kanal eine leere Nachricht, sodass der Assistent mit dem Aufruf der Erweiterung fortfahren kann.

   Alle integrierten Kanalintegrationen (z. B. der Web-Chat) berücksichtigen die Kontextvariable skip_user_input. Wenn Sie die API zum Entwickeln eines angepassten Clients verwenden, liegt es in Ihrer Verantwortung, eine Logikprüfung für diese Variable einzuschließen. Weitere Informationen finden Sie unter Benutzereingabe verarbeiten.

3. Klicken Sie im Schritteditor auf Nächster Schritt.

4. Klicken Sie auf Erweiterung verwenden.

5. Geben Sie im Fenster Erweiterungskonfiguration die folgenden Informationen ein:

   • Wählen Sie im Feld Erweiterung die Erweiterung aus, die Sie aufrufen wollen.

   • Wählen Sie im Feld Operation die Operation aus, die Sie durchführen wollen. (Eine Operation ist eine Methode oder Funktion, die von der Erweiterung unterstützt wird.)

6. Geben Sie Werte für jeden der erforderlichen Eingabeparameter an. Ein Parameter ist ein Eingabewert, der an eine Operation gesendet wird, z. B. die ID eines Kundendatensatzes, den Sie abrufen möchten, oder der Standort, der für eine Wettervorhersage verwendet wird.

   Um einem Parameter einen Wert zuzuordnen, klicken Sie auf das Eingabefeld für den entsprechenden Wert. Anschließend können Sie in der Liste der verfügbaren Variablen eine Auswahl treffen oder einen Ausdruck schreiben, um den Wert anzugeben.

   

   Jeder Parameter weist einen Datentyp auf (z. B. number oder string). Die von Ihnen gewählte Variable muss mit dem Datentyp des Parameters kompatibel sein; weitere Informationen finden Sie unter Kompatible Variablen für Parameter.

   Bevor Sie fortfahren können, müssen Sie Werte für alle erforderlichen Parameter angeben.

7. Wenn Sie einen Wert für einen optionalen Parameter angeben möchten, klicken Sie auf Optionale Parameter. Anschließend können Sie diesen Vorgang für jeden optionalen Parameter wiederholen, den Sie verwenden möchten.

8. Klicken Sie auf Anwenden. (Wenn die Schaltfläche Anwenden nicht verfügbar ist, stellen Sie sicher, dass Sie Werte für alle erforderlichen Parameter angegeben haben.)

Der Abschnitt Nächster Schritt des Schritteditors enthält jetzt eine Übersicht über den Aufruf der Erweiterung:

Wenn Sie Änderungen vornehmen müssen, klicken Sie auf Erweiterung bearbeiten, um das Fenster Erweiterungskonfiguration erneut zu öffnen.

Auf Antwortdaten für Erweiterungen zugreifen

Nach dem Aufruf einer Erweiterung werden Werte aus den Antwortdaten in speziellen Aktionsvariablen gespeichert, auf die Sie in nachfolgenden Schritten zugreifen können.

Sie können auf diese Variablen auf dieselbe Weise wie auf andere Aktionsvariablen zugreifen. Sie können sie im Assistent sagt-Text referenzieren, als Teil einer Schrittbedingung auswerten oder einer Sitzungsvariablen zuordnen, damit andere Aktionen darauf zugreifen können. Die Antwortvariablen werden in der Liste der verfügbaren Variablen angezeigt, und zwar kategorisiert unter dem Namen der Erweiterung und dem Schritt, aus dem sie aufgerufen wurden:

Mit jedem Aufruf einer Erweiterung wird eine separate Gruppe von Antwortvariablen erstellt. Wenn Ihre Aktion dieselbe Erweiterung mehrmals aus verschiedenen Schritten aufruft, stellen Sie sicher, dass Sie die Variablen aus dem richtigen Schritt auswählen.

Jede Variable stellt einen Wert aus dem Antworthauptteil dar. Um den Zugriff auf diese Werte zu erleichtern, werden Daten aus komplexen, verschachtelten Objekten extrahiert und einzelnen Antwortvariablen zugeordnet. Der Name jeder Variablen spiegelt ihre Position im Antworthauptteil wider (z. B. body.name oder body.customer.address.zipcode).

In diesem Aktionsschritt wird beispielsweise ein Ausdruck verwendet, um die Eigenschaft availability in einer Erweiterungsantwort zu überprüfen:

Wenn eine Antwortvariable ein Array enthält, können Sie einen Ausdruck schreiben, der Array-Methoden verwendet, um auf die Elemente des Arrays zuzugreifen. Sie können beispielsweise die Methode contains() in einer Schrittbedingung verwenden, um zu testen, ob das Array einen bestimmten Wert enthält, oder die Methode join(), um Daten aus dem Array als Zeichenfolge zu formatieren, die Sie in eine Assistentenantwort einschließen können. Weitere Informationen zu Array-Methoden finden Sie unter Array-Methoden.

Auf Erfolg oder Fehler überprüfen

Möglicherweise möchten Sie, dass Ihr Assistent Fehler verarbeiten kann, die beim Aufrufen einer angepassten Erweiterung auftreten. Sie können dies umsetzen, indem Sie die Antwortvariable Ran successfully überprüfen, die zusammen mit der Antwort des Aufrufs an die Erweiterung zurückgegeben wird. Diese Variable ist ein boolescher Wert (true oder false).

Wenn Sie Schrittbedingungen definieren, mit denen die Variable Ran successfully überprüft wird, können Sie Schritte erstellen, die es Ihrem Assistenten ermöglichen, in Abhängigkeit davon, ob der Aufruf an die Erweiterung erfolgreich war, unterschiedlich zu antworten. (Weitere Informationen zu Schrittbedingungen finden Sie unter Schrittbedingungen.)

Das folgende Beispiel zeigt eine Schrittbedingung, die in Schritt 3 eine Überprüfung auf einen Fehler von einer Erweiterung durchführt. Durch die Verwendung dieser Bedingung können Sie einen Schritt erstellen, mit dem dem Kunden mitgeteilt wird, dass ein Fehler aufgetreten ist. Zusätzlich könnte dem Kunden angeboten werden, eine Verbindung zu einem Agenten herzustellen, um weitere Hilfe zu erhalten.

Bedingung für HTTP

Zusätzlich zur Variablen Ran successfully können Sie auch eine Schrittbedingung basierend auf HTTP der Antwort erstellen. Auf diese Weise können Sie Schritte erstellen, die die Situation je nach Fehlerursache unterschiedlich behandeln. Wenn der Aufruf beispielsweise aufgrund eines Timeout-Fehlers HTTP ) fehlgeschlagen ist, können Sie den Aufruf erneut versuchen.

Es gibt viele mögliche HTTP-Statuscodes und verschiedene Methoden verwenden unterschiedliche Statuscodes, um verschiedene Erfolgs- oder Fehlertypen anzugeben. Um HTTP zu berücksichtigen, müssen Sie wissen, welche HTTP der externe Dienst unter welchen Umständen zurückgibt. Diese Statuscodes werden in der Regel in dem Dokument OpenAPI angegeben, in dem die externe API beschrieben wird.

Um eine Schrittbedingung basierend auf HTTP zu erstellen, gehen Sie folgendermaßen vor:

1. Klicken Sie für den Wert, den Sie testen möchten, auf Ausdruck.

2. Geben Sie im Ausdrucksfeld ein Dollarzeichen ($) ein, um die Liste der verfügbaren Variablen anzuzeigen.

3. Wählen Sie eine beliebige Variable aus, bei der es sich einen Antwortwert aus der Erweiterung handelt. (Es spielt keine Rolle, welche Variable Sie auswählen, solange es sich um eine Antwortvariable aus der Erweiterung handelt.)

   Der Ausdruck wird automatisch aktualisiert und zeigt einen Verweis auf die ausgewählte Variable im Format ${step_xxx_result_y.body.variablename} an. Wenn Sie beispielsweise eine Antwortvariable namens body.id ausgewählt haben, könnte der Verweis ${step_596_result_1.body.id} lauten.

4. Bearbeiten Sie den Verweis in den geschweiften Klammern ({}), um .body.variablename zu entfernen. Es sollte ein Ausdruck wie ${step_596_result_1} übrig bleiben.

5. Fügen Sie nach der rechten geschweiften Klammer (}) .status hinzu. Der resultierende Verweis gibt den Statuscode an, der vom Aufruf der Erweiterung zurückgegeben wird (z. B. ${step_596_result_1}.status).

   Weitere Informationen zum Schreiben von Ausdrücken finden Sie in Ausdrücke schreiben.

6. Vervollständigen Sie den Ausdruck, indem Sie einen Operator und einen Vergleichswert hinzufügen, sodass der Ausdruck zu einem booleschen Wert (true/false) ausgewertet wird. Zum Beispiel prüft der folgende Ausdruck auf HTTP 408, der auf einen Timeout-Fehler hinweist:

   ${step_549_result_1}.status==408
   

Fehlerbehebung bei benutzerdefinierten Erweiterungen

Wenn Ihre Aufrufe an eine Erweiterung fehlschlagen, können Sie das Problem beheben, indem Sie sich detaillierte Informationen darüber ansehen, was an die System-API gesendet und von ihr zurückgegeben wird. Dazu können Sie den Inspektor im Vorschaufenster verwenden:

1. Rufen Sie die Seite Aktionen oder den Aktionseditor auf, und klicken Sie auf Vorschau, um den Vorschaubereich zu öffnen.

   Sie können den Inspektor nicht über die Assistentenvorschau auf der Seite Vorschau aufrufen, die nur das zeigt, was ein Kunde sehen würde. Verwenden Sie stattdessen die Vorschaufunktion, die Teil der Seite 'Aktionen' ist und Ihnen Zugriff auf zusätzliche Informationen gibt.

2. Interagieren Sie mit Ihrem Assistenten wie mit einem Kunden.

3. Jedes Mal, wenn eine Erweiterung aufgerufen wird, wird im Vorschaufenster eine Nachricht angezeigt, die Ihnen Zugriff auf detaillierte Informationen gibt:

   Klicken Sie auf Untersuchen, um Details zum Aufruf der Erweiterung anzuzeigen.

   Sie können auch auf das klicken, um den Inspektor ein- oder auszublenden. Sie müssen jedoch im Vorschaufenster auf Inspizieren klicken, um Informationen über einen bestimmten Anruf an eine Nebenstelle anzuzeigen.

   Die Registerkarte Übersicht des Inspektors zeigt die folgenden Informationen über einen Anruf an eine Nebenstelle an:

   Debugging-Option	Beschreibung
   Erweiterung	Der Name der Erweiterung, wie in den Erweiterungseinstellungen angegeben.
   Operation	Die aufgerufene Operation.
   Status	Der HTTP Statuscode der Antwort. Anhand solcher Codes können Sie ermitteln, ob ein Fehler vom externen Service zurückgegeben wird.
   Anforderungsparameter	Die Eingabeparameter, die als Teil der Anfrage an die System-API gesendet wurden.
   Antworteigenschaften	Die Werte aller Eigenschaften, die in der Antwort von der System-API enthalten sind. Dies sind die Werte, die Aktionsvariablen zugeordnet werden, nachdem der Aufruf der Erweiterung abgeschlossen ist.

   In den Tabellen Anforderungsparameter und Antworteigenschaften werden lange Eigenschaftsnamen möglicherweise abgeschnitten, sodass nur der letzte Teil des JSON-Pfads angezeigt wird. Um den vollständigen Pfad und den Eigenschaftsnamen anzuzeigen, bewegen Sie den Mauszeiger über den Eigenschaftsnamen in der Tabelle.

4. Klicken Sie im Erweiterungs-Inspector auf die Registerkarte Erweitert, um die unformatierten Anforderungs-und Antwortdaten anzuzeigen:

   • Die Anforderung wird als cURL-Befehl angezeigt, den Sie an einer Eingabeaufforderung ausführen oder in ein Tool wie Postmanimportieren können. (Aus Sicherheitsgründen wird der Inhalt eines Authorization-Headers nicht eingeschlossen.)
   • Die Antwort wird als vollständige JSON-Daten angezeigt, die von der System-API zurückgegeben werden.

Fehlerbehebung bei der konversationellen Suche oder bei fähigkeitsbasierten Aktionen

Wenn Ihre Aufrufe der konversationellen Suche oder der fähigkeitsbasierten Aktionen fehlschlagen, können Sie das Problem beheben, indem Sie die detaillierten Informationen darüber einsehen, was an die System-API gesendet und von ihr zurückgegeben wird.

Der Inspektor für die konversationelle Suche wird nur angezeigt, wenn die konversationelle Suche in Ihrer Suchintegration aktiviert ist. Wenn Sie die Integration der benutzerdefinierten Dienstsuche verwenden, müssen Sie bei der Konfiguration der Suchintegration ausschließlich die serverseitige Suche verwenden. Die clientseitige Suche wird im Conversational Search Inspector nicht unterstützt.

Um die detaillierten Informationen zur Analyse des Problems anzuzeigen, verwenden Sie den Inspektor im Vorschaubereich:

1. Rufen Sie die Seite Aktionen auf, oder klicken Sie im Aktionseditor auf Vorschau, um den Vorschaubereich zu öffnen.

   Sie können den Inspektor nicht über die Assistentenvorschau auf der Seite Vorschau aufrufen. Verwenden Sie stattdessen die Vorschaufunktion, die Teil der Seite 'Aktionen' ist und Ihnen Zugriff auf zusätzliche Informationen gibt.

2. Interagieren Sie mit Ihrem Assistenten wie mit einem Kunden.

3. Jedes Mal, wenn eine Nebenstelle aufgerufen wird, erscheint im Vorschaufenster eine Meldung, die den Zugriff auf detaillierte Informationen ermöglicht: Sie können auch auf das Symbol klicken, um den Erweiterungsinspektor ein-oder auszublenden. Klicken Sie im Vorschaufenster auf Inspizieren, um Informationen über einen bestimmten Aufruf der Suchintegration anzuzeigen.

4. Verwenden Sie die Registerkarte "Übersicht ", um die Gründe für das Fehlschlagen Ihrer Aufrufe der Conversational Search zu finden.

   Machen Sie sich mit den beiden Phasen der Sucherweiterung vertraut, bevor Sie die Felder kennenlernen, die auf der Registerkarte Übersicht angezeigt werden.

   • Phase des Abrufs

     Stellt die erste Suchphase dar, in der eine externe Dokumentensuchmaschine aufgerufen wird, um die erste Ergebnismenge abzurufen.

   • Phase der Antwortgenerierung

     Stellt die Phase dar, in der die Daten während der Abrufphase abgerufen und an einen LLM gesendet werden, um eine für den Benutzer lesbare Antwort zu erzeugen.

   Die Registerkarte Übersicht des Inspektors zeigt die folgenden Informationen über den Aufruf der Suchintegration an.

   Debugging-Option	Beschreibung
   Erweiterung	Der Name der Erweiterung, wie in den Erweiterungseinstellungen angegeben.
   Index	Der Name des von der Suche verwendeten Elasticsearch, nur sichtbar, wenn die Sucherweiterung für die Verwendung von Elasticsearch konfiguriert ist.
   Projekt-ID	Die ID des Projekts, die von IBM Watson® Discovery während der Abrufphase der Suche verwendet wird. Dieses Feld ist nur sichtbar, wenn Sie die Sucherweiterung so konfigurieren, dass sie IBM Watson® Discovery verwendet.
   Abfrage	Die Abfrage, die vom System verwendet wird, um die Suche in der Dokument-Engine zu startenElasticsearch, IBM Watson® Discovery oder ein benutzerdefinierter Dienst auf dem Server). Der Wert dieses Feldes spiegelt die vom System umgeschriebene Abfrage wider.
   Original-Anfrage	Die Anfrage, mit der der Nutzer die Suche begonnen hat. Dieses Feld ist nur sichtbar, wenn das System die Abfrage neu schreibt, wenn die Multiturn-Gesprächssuche aktiviert ist.
   Benutzerdefinierter Ergebnisfilter	Zeigt den benutzerdefinierten Ergebnisfilter an, sofern dieser im Suchauslöser enthalten ist, der die Konversationssuche ausgelöst hat. Dieses Feld erscheint möglicherweise nicht immer in den Antworten.
   LLM-Typ	Der LLM, der während der Antwortgenerierungsphase aufgerufen wurde. Dieser Wert lautet watsonx.ai. Weitere Informationen zur Konfiguration des LLM in Ihrem Assistenten finden Sie unter Basis-LLM.
   Modell	Das Modell, das vom Basis-LLM während der Antwortgenerierungsphase der Suche verwendet wird.
   Grund für das Schließen des Stroms	Gibt den Grund an, warum der Stream beendet oder geschlossen wurde, mit einem entsprechenden Wert auf der Benutzeroberfläche. Dieses Feld ist nur sichtbar, wenn Sie das Streaming im Webchat aktivieren.
   Anzahl der LLM-Eingabe-Token	Gibt die Anzahl der Token in der Anfrage an, die in der Antwortgenerierungsphase der Suche an den LLM gesendet wurde.
   LLM-generierte Tokenanzahl	Gibt die Anzahl der Token in der Antwort an, mit der der LLM in der Antwortgenerierungsphase der Suche antwortet.
   IDK-Antwort	Dieses Feld ist nur sichtbar, wenn die Suchantwort eine IDK-Antwort (Ich weiß es nicht) ergibt.
   IDK Grund	Ein Grund dafür, warum eine Suchantwort vom System in eine IDK-Antwort (Ich weiß nicht) aufgelöst wurde, wird mit dem entsprechenden Wert angezeigt.
   IDK-Auslöser Eröffnungsphrase	Das Feld zeigt die erkannte Standard-Eröffnungsphrase, die eine IDK-Antwort (Ich weiß nicht) ausgelöst hat, und ist nur sichtbar, wenn der IDK-Grund auf diese Phrase zurückzuführen ist.
   IDK Auslösewort	Das Feld zeigt die erkannte Triggerphrase an, die eine IDK-Antwort (I don't know) ausgelöst hat, und ist nur sichtbar, wenn der IDK-Grund auf diese Phrase zurückzuführen ist.
   Gesamtzeit bis zur Rückkehr	Die Gesamtzeit, die das System für die Ausführung der konversationellen Suche benötigte.
   Suchzeit	Die Zeit, die das System benötigt, um die Suchmaschine aufzurufen und die Ergebnisse in der Abrufphase der Suche zu erhalten.
   Generierungszeit der Antwort	Die Zeit, die das System benötigt, um die Antwortgenerierungsphase der Suche abzuschließen.
   Konfidenzschwelle	Ein numerischer Wert, der den Schwellenwert für das Suchvertrauen darstellt, in der Konfiguration des Assistenten auch bekannt als Tendenz, "Ich weiß nicht" zu sagen.
   Extraktivität	Die Punktzahl gibt an, wie viel von der Antwort direkt aus Quellen zitiert wird. Eine höhere Punktzahl deutet auf ein direkteres Zitat hin, eine niedrigere Punktzahl auf eine Umformulierung der Quelle oder fehlende Quellenangaben.
   Vertrauen in den Abruf	Der Konfidenzwert gibt an, wie sicher das System bei den Suchergebnissen ist. Wenn der Wert unter dem Schwellenwert liegt, antwortet das System mit "IDK" und dem Grund "Abrufzuverlässigkeit zu niedrig".
   Vertrauen in die Antwort	Der Konfidenzwert gibt an, wie sicher das System in Bezug auf die generierte Antwort ist. Liegt er unter dem Schwellenwert, antwortet das System mit IDK und dem Grund Response confidence too low.

Fehlende Erweiterung neu konfigurieren

Eine Erweiterung ist möglicherweise nicht mehr verfügbar, wenn sie aus dem Assistenten auf der Seite Integrationen entfernt wird oder wenn die Aktion exportiert und dann in einen anderen Assistenten importiert wird, in dem die erforderliche Erweiterung nicht konfiguriert ist. In diesem Fall wird jeder Aktionsschritt, der die Erweiterung aufruft, ungültig.

Führen Sie folgende Schritte aus, um den Fehler zu beheben:

1. Erstellen Sie bei Bedarf die Erweiterung mit derselben OpenAPI-Spezifikation erneut, die zuvor verwendet wurde. (Weitere Informationen finden Sie unter Angepasste Erweiterung erstellen.)

2. Stellen Sie sicher, dass die Erweiterung zum Assistenten hinzugefügt wurde. (Weitere Informationen finden Sie unter Erweiterung zum Assistenten hinzufügen)

3. Bearbeiten Sie im Aktionseditor den Aktionsschritt, der die Erweiterung aufruft, und prüfen Sie, ob der Aufruf der Erweiterung ordnungsgemäß konfiguriert ist. Wenn watsonx Assistant die erforderliche Erweiterung erkennt, wird die Erweiterungskonfiguration automatisch wiederhergestellt.

   Wird die Nachricht Extension not fully configured angezeigt, bedeutet dies, dass watsonx Assistant die erforderliche Erweiterung nicht gefunden hat. Klicken Sie auf Erweiterung bearbeiten.

4. Wählen Sie im Fenster zur Einrichtung der Nebenstelle die Nebenstelle aus, die Sie anrufen möchten.

   Wenn watsonx Assistant eine verfügbare Erweiterung erkennt, die mit demselben OpenAPI-Dokument erstellt wurde, wird eine Nachricht angezeigt, die darauf hinweist, dass diese Erweiterung ausgewählt wurde. Sie können jedoch jede verfügbare Erweiterung auswählen.

5. Überprüfen Sie, ob die richtigen Werte in den Feldern Operation und Parameter angegeben sind.

6. Klicken Sie auf Anwenden.

7. Wenn Sie eine Erweiterung ausgewählt haben, die nicht mit der Erweiterung identisch ist, die zum Erstellen der Aktion verwendet wurde, müssen Sie möglicherweise nachfolgende Schritte ändern, die auf die Antworteigenschaften der Erweiterung zugreifen. Überprüfen Sie alle späteren Schritte, die auf die Antworteigenschaften verweisen, und stellen Sie sicher, dass die Referenzen noch gültig und korrekt sind.