In diesem Leitfaden werden empfohlene Methoden zum Rendern von Ausgaben der Conversational Analytics API in einer Benutzeroberfläche (UI) mithilfe von Looker-Datenquellen beschrieben.
Wenn ein Nutzer die API abfragt, kann die Antwort neben der endgültigen Antwort auch Zwischenschritte für die Argumentation enthalten. In dieser Anleitung wird beschrieben, wie Sie API-Antworten mit unterschiedlichen Detaillierungsgraden rendern, indem Sie eine Hauptantwortansicht und eine Ansicht mit allen Details implementieren:
- In der Hauptansicht wird die Antwort auf die Frage des Nutzers direkt angezeigt. Diese Ansicht bietet eine prägnante Darstellung und enthält nicht von vornherein Details zur Argumentation des Agents.
- In der Ansicht mit allen Details wird der vollständige Entscheidungsprozess angezeigt, den der Agent durchläuft, um zur endgültigen Antwort zu gelangen. Sie enthält alle Elemente aus der Hauptantwortansicht.
Ein empfohlenes UI-Muster besteht darin, standardmäßig die Hauptantwortansicht anzuzeigen und ein UI-Steuerelement wie eine Schaltfläche oder ein Schalter bereitzustellen, mit dem Nutzer zur Ansicht mit allen Details wechseln können. Begründungsdetails sind zwar nützlich, um die Logik zu validieren, aber wenn sie standardmäßig angezeigt werden, kann das für Nutzer, die sich hauptsächlich für die endgültige Antwort interessieren, unnötige Details hinzufügen.
Hauptansicht der Antwort
Wenn Sie nur die endgültige direkte Antwort auf die Frage des Nutzers rendern möchten, folgen Sie der Anleitung in diesem Abschnitt. Diese Ansicht konzentriert sich auf die endgültige Ausgabe und schließt Zwischenschritte aus.
Anleitung zum Rendern von Systemnachrichten
In der folgenden Tabelle werden die Systemmeldungen beschrieben, die als endgültige direkte Antworten gelten, sowie Empfehlungen für die Darstellung dieser Meldungen.
| Systemnachricht | Anleitung zum Rendern |
|---|---|
DataQuery |
Mit dem zugehörigen Ergebnis rendern: Diese Meldung darf nur gerendert werden, wenn auch die entsprechende DataResult-Meldung gerendert wird. DataQuery-Nachrichten in den folgenden Fällen nicht rendern:
|
DataResult |
Alle DataResult-Nachrichten rendern, mit Ausnahme von Zwischenergebnissen und leeren Ergebnissen.DataResult-Nachrichten in den folgenden Fällen nicht rendern:
|
ChartResult |
Alle Diagramme rendern: Alle ChartResult-Nachrichten in der API-Antwort rendern. |
TextMessage |
Nur endgültige Antworten rendern. TextMessage-Meldungen werden nur gerendert, wenn der Wert TextType FINAL_RESPONSE ist. |
Beispiel: Hauptantwortansicht rendern
Sie können einen Schalter wie Begründung anzeigen implementieren, damit Nutzer von der Hauptantwortansicht zur Ansicht mit allen Details wechseln können.
Das folgende Transkript zeigt die Hauptantwortansicht. Bei DataQuery-Nachrichten empfehlen wir, die Abfragedetails hinter einem Inline-Schalter zu verbergen, der im Transkript durch ein minimiertes Symbol () gekennzeichnet ist, um optionalen Zugriff auf die zugrunde liegende Abfragelogik zu ermöglichen.
Nutzer: Vergleiche den Gesamtumsatz der Cymbal Group im Jahr 2022 mit dem im Jahr 2023. Stelle das Ergebnis in einem Diagramm dar.
Agent:
Hier ist das Abfrageergebnis für „Total Sales Cymbal Group 2022 2023“ (Gesamtumsatz Cymbal Group 2022 2023).
Erstellungsjahr Gesamtumsatz 2023 96.627,00 $ 2022 93.095,50 $ Gesamtumsatz der Cymbal Group in den Jahren 2022 und 2023
Der Gesamtumsatz der Cymbal Group betrug 2022 93.095,50$ und 2023 96.627,00$.
In der folgenden Tabelle werden die Elemente aus der Beispielinteraktion den entsprechenden API-Systemmeldungen zugeordnet.
| Element | Quellnachricht |
|---|---|
| Generierte Abfrage (JSON ist standardmäßig hinter dem -Schalter verborgen) | DataQuery |
| Datentabelle | DataResult |
| Balkendiagramm | ChartResult |
| Endgültige Textantwort | TextMessage (FINAL_RESPONSE) |
Vollständige Detailansicht
Verwenden Sie diese Anleitung, um den vollständigen Begründungsprozess darzustellen. Diese Ansicht enthält alles aus der Hauptantwortansicht und zeigt die Inhalte und Schritte in der Reihenfolge an, in der sie vom Agent generiert werden. In dieser Ansicht werden alle Schritte angezeigt, die der Agent ausführt, um die endgültige Antwort zu erhalten, einschließlich der Begründung und der Zwischendaten.
Hinweise zur Darstellung für Schlussfolgerungen und den Abruf detaillierter Daten
In der folgenden Tabelle werden die Systemmeldungen beschrieben, die die Argumentation und die detaillierten Abrufschritte des Agenten darstellen, sowie Empfehlungen für die Darstellung dieser Meldungen.
| Systemnachricht | Anleitung zum Rendern |
|---|---|
TextMessage mit dem TextType-Wert THOUGHT |
Begründungsschritte rendern. Zeigen Sie diese Nachrichten an, um den internen Denkprozess des Agents zu veranschaulichen. Diese Nachrichten bestehen aus zwei Teilen:
parts[0]) als vorübergehende Statusanzeige zu verwenden. |
TextMessage mit dem TextType-Wert PROGRESS |
PROGRESS-Meldungen anzeigen: Diese Meldungen geben Aufschluss über die Aktionen des Agents. Das sind Informationsnachrichten zum Fortschritt des Agents, z. B. zu einem Tool, das aufgerufen wird. Das unterscheidet sich vom internen Denkprozess des Agents (THOUGHT) und der endgültigen Antwort an den Nutzer (FINAL_RESPONSE). Diese Nachrichten bestehen aus zwei Teilen:
|
DataQuery und DataResult mit einem Namen, der mit _sample_values endet |
Zwischenmeldungen für DataQuery und DataResult anzeigen: Sowohl DataQuery- als auch DataResult-Nachrichten mit einem name-Feld, das mit _sample_values endet, sind Zwischenschritte für den detaillierten Datenabruf und werden nicht in der Hauptansicht der Antwort angezeigt. Nehmen Sie diese in die Ansicht mit der vollständigen Antwort auf (hinter einem Ein/Aus-Schalter), um die Schritte zu zeigen, die der Agent ausführt. |
DataResult mit leerem Feld data |
Nur die zugehörige DataQuery-Meldung anzeigen: DataResult-Nachrichten mit einem leeren data-Feld dürfen in keiner Ansicht angezeigt werden. Zeigen Sie in der detaillierten Ansicht die DataQuery-Meldung an, die zum leeren Ergebnis geführt hat (hinter einem Ein/Aus-Schalter). So kann der Nutzer die ausgeführte Abfrage sehen, auch wenn sie keine Ergebnisse geliefert hat. In der Zusammenfassung der endgültigen Antwort (TextMessage mit dem Typ FINAL_RESPONSE) wurde der Nutzer bereits darüber informiert, dass für die Anfrage keine Daten zurückgegeben wurden. |
Beispiel: Vollständige Detailansicht rendern
Wenn ein Nutzer den Schalter Begründung anzeigen in den maximierten Zustand versetzt, wird in der Benutzeroberfläche die schrittweise Begründung des Agents angezeigt.
Das folgende Transkript zeigt die vollständige Detailansicht, einschließlich der Begründungsschritte. Bei DataQuery-Nachrichten können Abfragedetails standardmäßig angezeigt werden, optional hinter einem Inline-Schalter, der durch ein erweitertes Symbol () gekennzeichnet ist, wie im Transkript zu sehen.
Nutzer: Vergleiche den Gesamtumsatz der Cymbal Group im Jahr 2022 mit dem im Jahr 2023. Stelle das Ergebnis in einem Diagramm dar.
Agent:
Schema
Um den Gesamtumsatz für „Cymbal Group“ im Jahr 2022 mit dem im Jahr 2023 zu vergleichen, muss ich den Bereich „Bestellpositionen“ abfragen. Ich filtere nach dem Produktnamen „Cymbal Group“ und nach den Jahren 2022 und 2023. Ich rufe dann die Felder
Total SalesundCreated Yearab.Hier ist das Abfrageergebnis für „Total Sales Cymbal Group 2022 2023“ (Gesamtumsatz Cymbal Group 2022 2023).
[ {"model":"thelook","view":"order_items","fields":["order_items.total_sale_price","order_items.created_year"], "filters":{"order_items.created_year":"2022,2023","products.brand":"Cymbal Group"}} ]
Erstellungsjahr Gesamtumsatz 2023 96.627,00 $ 2022 93.095,50 $ Vertriebsverteilung darstellen
Ich habe den Gesamtumsatz für die „Cymbal Group“ für 2022 und 2023 abgerufen. Jetzt generiere ich ein Diagramm, um diesen Vergleich zu visualisieren, und gebe dann die endgültige Antwort.
Erstelle ein Balkendiagramm, in dem die Gesamtumsätze für die „Cymbal Group“ in den Jahren 2022 und 2023 verglichen werden. Auf der x-Achse sollte das Jahr und auf der y-Achse der Gesamtumsatz dargestellt werden.
Der Gesamtumsatz der Cymbal Group betrug 2022 93.095,50$ und 2023 96.627,00$.
In der folgenden Tabelle werden die Schritte aus der Beispielinteraktion den entsprechenden API-Systemnachrichten zugeordnet.
| Element | Quellnachricht |
|---|---|
| Das Schema verstehen (Zusammenfassung der Überlegung) | TextMessage (Typ THOUGHT, parts[0]) |
| „Gesamtumsatz vergleichen…“ (vollständiger Thinking-Text) | TextMessage (Typ THOUGHT, parts[1]) |
| Generierte Abfrage (JSON wird angezeigt, wenn der Schalter maximiert ist) | DataQuery |
| Datentabelle | DataResult |
| Vertrieb von Verkäufen darstellen (Zusammenfassung der Überlegung) | TextMessage (Typ THOUGHT, parts[0]) |
| „Ich habe abgerufen…“ (vollständiger Thinking-Text) | TextMessage (Typ THOUGHT, parts[1]) |
| Balkendiagramm | ChartResult |
| Endgültige Textantwort | TextMessage (FINAL_RESPONSE) |