Questa guida descrive gli approcci consigliati per il rendering degli output dell'API Conversational Analytics in un'interfaccia utente utilizzando le origini dati di Looker.
Quando un utente esegue una query sull'API, la risposta può includere passaggi di ragionamento intermedi oltre alla risposta finale. Questa guida descrive come eseguire il rendering delle risposte API con diversi livelli di dettaglio implementando una visualizzazione della risposta principale e una visualizzazione dei dettagli completi:
- La visualizzazione della risposta principale mostra direttamente la risposta alla domanda dell'utente. Questa visualizzazione fornisce una presentazione concisa e non include i dettagli sul ragionamento dell'agente in anticipo.
- La visualizzazione dei dettagli completi mostra l'intero processo di ragionamento seguito dall'agente per raggiungere la risposta finale, inclusi tutti gli elementi della visualizzazione della risposta principale.
Un pattern UI consigliato è quello di visualizzare la visualizzazione della risposta principale per impostazione predefinita e fornire un controllo UI, ad esempio un pulsante o un pulsante di attivazione/disattivazione, che consenta agli utenti di passare alla visualizzazione dei dettagli completi. Sebbene i dettagli del ragionamento siano utili per convalidare la logica, la loro visualizzazione predefinita può aggiungere dettagli non necessari per gli utenti interessati principalmente alla risposta finale.
Visualizzazione principale delle risposte
Per visualizzare solo la risposta diretta finale alla domanda dell'utente, segui i passaggi descritti in questa sezione. Questa visualizzazione si concentra sull'output finale ed esclude i passaggi intermedi.
Linee guida per il rendering dei messaggi di sistema
La seguente tabella descrive i messaggi di sistema considerati risposte dirette finali, insieme ai suggerimenti su come visualizzarli.
| Messaggio di sistema | Indicazioni per il rendering |
|---|---|
DataQuery |
Esegui il rendering con il risultato associato. Visualizza questo messaggio solo nei casi in cui visualizzi il messaggio DataResult corrispondente. Non eseguire il rendering dei messaggi DataQuery nei seguenti casi:
|
DataResult |
Visualizza tutti i messaggi DataResult, ad eccezione dei risultati intermedi e vuoti.Non eseguire il rendering dei messaggi DataResult nei seguenti casi:
|
ChartResult |
Visualizza tutti i grafici. Visualizza tutti i messaggi ChartResult nella risposta dell'API. |
TextMessage |
Visualizza solo le risposte finali. Visualizza i messaggi TextMessage solo quando il valore di TextType è FINAL_RESPONSE. |
Esempio: rendering della visualizzazione della risposta principale
Puoi implementare un pulsante di attivazione/disattivazione, ad esempio Mostra motivazione, per consentire agli utenti di passare dalla visualizzazione della risposta principale alla visualizzazione dei dettagli completi.
La seguente trascrizione mostra la visualizzazione principale della risposta. Per i messaggi DataQuery, ti consigliamo di nascondere i dettagli della query dietro un pulsante di attivazione/disattivazione in linea, indicato nella trascrizione da un'icona compressa (), per fornire l'accesso facoltativo alla logica della query sottostante.
Utente: confronta le vendite totali di Cymbal Group nel 2022 e nel 2023. Traccia il risultato su un grafico.
Agente:
Ecco il risultato della query per Vendite totali Cymbal Group 2022 2023.
Anno di creazione Vendite totali 2023 $96.627,00 2022 93.095,50 $ Vendite totali per Cymbal Group nel 2022 e nel 2023
Le vendite totali di Cymbal Group nel 2022 sono state pari a 93.095,50$ e nel 2023 a 96.627,00$.
La seguente tabella mappa gli elementi dell'interazione di esempio ai relativi messaggi di sistema dell'API.
| Elemento | Messaggio di origine |
|---|---|
| Query generata (JSON nascosto per impostazione predefinita dal pulsante di attivazione/disattivazione ) | DataQuery |
| Tabella dati | DataResult |
| Grafico a barre | ChartResult |
| Risposta finale di testo | TextMessage (FINAL_RESPONSE) |
Visualizzazione dettagli completi
Utilizza queste indicazioni per visualizzare l'intero processo di ragionamento. Questa visualizzazione include tutti gli elementi della visualizzazione della risposta principale e mostra i contenuti e i passaggi nell'ordine in cui vengono generati dall'agente. Questa visualizzazione mostra tutti i passaggi che l'agente esegue per raggiungere la risposta finale, inclusi il ragionamento e i dati intermedi.
Linee guida per il rendering per il ragionamento e il recupero granulare dei dati
La seguente tabella descrive i messaggi di sistema che rappresentano il ragionamento dell'agente e i passaggi di recupero granulari, insieme ai suggerimenti su come visualizzare questi messaggi.
| Messaggio di sistema | Indicazioni per il rendering |
|---|---|
TextMessage con un valore TextType di THOUGHT |
Visualizza i passaggi del ragionamento. Visualizza questi messaggi per mostrare il processo di pensiero interno dell'agente. Questi messaggi sono composti da due parti:
parts[0]) come indicatore di stato temporaneo. |
TextMessage con un valore TextType di PROGRESS |
Visualizza i messaggi PROGRESS. Mostra questi messaggi per fornire informazioni sulle azioni dell'agente. Si tratta di messaggi informativi sullo stato di avanzamento dell'agente, ad esempio uno strumento che viene richiamato. Questo è diverso dal processo di pensiero interno dell'agente (THOUGHT) e dalla risposta finale all'utente (FINAL_RESPONSE). Questi messaggi sono composti da due parti:
|
DataQuery e DataResult con un nome che termina con _sample_values |
Visualizza i messaggi intermedi DataQuery e DataResult. I messaggi DataQuery e DataResult con un campo name che termina con _sample_values sono passaggi intermedi per il recupero granulare dei dati e non vengono visualizzati nella visualizzazione della risposta principale. Includi questi elementi nella visualizzazione della risposta completa (dietro un pulsante di attivazione/disattivazione) per mostrare i passaggi eseguiti dall'agente. |
DataResult con un campo data vuoto |
Visualizza solo il messaggio DataQuery associato. Non mostrare i messaggi DataResult con un campo data vuoto in nessuna visualizzazione. Nella visualizzazione dei dettagli completi, mostra il messaggio DataQuery che ha generato il risultato vuoto (dietro un pulsante di attivazione/disattivazione). In questo modo, l'utente può vedere la query eseguita anche se non ha prodotto risultati. Il riepilogo della risposta finale (TextMessage con il tipo FINAL_RESPONSE) avrà già informato l'utente che la query non ha restituito dati. |
Esempio: rendering della visualizzazione dei dettagli completi
Quando un utente attiva/disattiva l'opzione Mostra motivazione, la UI mostra il ragionamento passo passo dell'agente.
La seguente trascrizione mostra la visualizzazione completa dei dettagli, inclusi i passaggi di ragionamento. Per i messaggi DataQuery, i dettagli della query possono essere visualizzati per impostazione predefinita, facoltativamente dietro un pulsante di attivazione/disattivazione in linea indicato da un'icona espansa (), come mostrato nella trascrizione.
Utente: confronta le vendite totali di Cymbal Group nel 2022 e nel 2023. Traccia il risultato su un grafico.
Agente:
Comprendere lo schema
Per confrontare le vendite totali del "Gruppo di piatti" nel 2022 rispetto al 2023, devo eseguire una query nell'esplorazione "Articoli dell'ordine". Filtrerò per nome del prodotto "Cymbal Group" e per gli anni 2022 e 2023. Recupererò quindi i campi
Total SaleseCreated Year.Ecco il risultato della query per Vendite totali 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"}} ]
Anno di creazione Vendite totali 2023 $96.627,00 2022 93.095,50 $ Tracciare la distribuzione delle vendite
Ho recuperato le vendite totali di "Cymbal Group" per il 2022 e il 2023. Ora genererò un grafico per visualizzare questo confronto e poi fornirò la risposta finale.
Genera un grafico a barre che confronta le vendite totali del "Gruppo di piatti" nel 2022 e nel 2023. L'asse x deve rappresentare l'anno e l'asse y deve rappresentare le vendite totali.
Le vendite totali di Cymbal Group nel 2022 sono state pari a 93.095,50$ e nel 2023 a 96.627,00$.
La seguente tabella mappa i passaggi dell'interazione di esempio ai relativi messaggi di sistema dell'API.
| Elemento | Messaggio di origine |
|---|---|
| "Understanding the schema" (riepilogo del pensiero) | TextMessage (tipo THOUGHT, parts[0]) |
| "Per confrontare le vendite totali…" (testo del pensiero completo) | TextMessage (tipo THOUGHT, parts[1]) |
| Query generata (JSON mostrato quando il pulsante di attivazione/disattivazione è espanso) | DataQuery |
| Tabella dati | DataResult |
| "Plotting sales distribution" (riepilogo del pensiero) | TextMessage (tipo THOUGHT, parts[0]) |
| "Ho recuperato…" (testo del pensiero completo) | TextMessage (tipo THOUGHT, parts[1]) |
| Grafico a barre | ChartResult |
| Risposta finale di testo | TextMessage (FINAL_RESPONSE) |