Este guia descreve as abordagens recomendadas para renderizar saídas da API Conversational Analytics em uma interface do usuário (UI) usando fontes de dados do Looker.
Quando um usuário consulta a API, a resposta pode incluir etapas de raciocínio intermediárias, além da resposta final. Este guia descreve como renderizar respostas da API com diferentes níveis de detalhes implementando uma visualização da resposta principal e uma visualização de detalhes completos:
- A visualização da resposta principal mostra a resposta à pergunta do usuário diretamente. Essa visualização oferece uma apresentação concisa e não inclui detalhes sobre o raciocínio do agente de imediato.
- A visualização de detalhes completos mostra todo o processo de raciocínio que o agente segue para chegar à resposta final, incluindo todos os elementos da visualização de resposta principal.
Um padrão UI recomendado é mostrar a visualização principal da resposta por padrão e oferecer um controle de IU, como um botão ou uma alternância, que permita aos usuários mudar para a visualização de detalhes completos. Embora os detalhes do raciocínio sejam úteis para validar a lógica, mostrá-los por padrão pode adicionar detalhes desnecessários para usuários que estão interessados principalmente na resposta final.
Visualização da resposta principal
Para renderizar apenas a resposta direta final à pergunta do usuário, siga as etapas desta seção. Essa visualização se concentra na saída final e exclui as etapas intermediárias.
Orientações sobre a renderização de mensagens do sistema
A tabela a seguir descreve as mensagens do sistema consideradas respostas diretas finais, além de recomendações sobre como renderizar essas mensagens.
| Mensagem do sistema | Orientações sobre renderização |
|---|---|
DataQuery |
Renderizar com o resultado associado. Renderize essa mensagem apenas nos casos em que você renderizar a mensagem DataResult correspondente. Não renderize mensagens DataQuery nos seguintes casos:
|
DataResult |
Renderize todas as mensagens DataResult, exceto resultados intermediários e vazios.Não renderize mensagens DataResult nos seguintes casos:
|
ChartResult |
Renderizar todos os gráficos. Renderiza todas as mensagens ChartResult na resposta da API. |
TextMessage |
Renderizar apenas as respostas finais. Renderize mensagens TextMessage somente quando o valor de TextType for FINAL_RESPONSE. |
Exemplo: renderizar a visualização da resposta principal
Você pode implementar uma alternância, como Mostrar justificativa, para permitir que os usuários mudem da visualização de resposta principal para a visualização de detalhes completa.
A transcrição a seguir demonstra a visualização da resposta principal. Para mensagens DataQuery, recomendamos ocultar os detalhes da consulta atrás de uma alternância inline, indicada na transcrição por um ícone recolhido (), para fornecer acesso opcional à lógica de consulta subjacente.
Usuário: compare o total de vendas do Grupo Cymbal em 2022 e 2023. Represente o resultado em um gráfico.
Agente:
Este é o resultado da consulta para o Total de vendas do grupo Cymbal em 2022 e 2023.
Ano de criação Total de vendas 2023 US$ 96.627,00 2022 US$ 93.095,50 Vendas totais do Grupo Cymbal em 2022 e 2023
O total de vendas do Grupo Cymbal em 2022 foi de US$93.095,50 e, em 2023, de US$96.627,00.
A tabela a seguir mapeia os elementos da interação de exemplo para as mensagens do sistema da API correspondentes.
| Elemento | Mensagem de origem |
|---|---|
| Consulta gerada (JSON oculto atrás da alternância por padrão) | DataQuery |
| Tabela de dados | DataResult |
| Gráfico de barras | ChartResult |
| Resposta final em texto | TextMessage (FINAL_RESPONSE) |
Visualização de detalhes completos
Use esta orientação para renderizar o processo de raciocínio completo. Essa visualização inclui tudo da visualização principal de respostas e mostra o conteúdo e as etapas na ordem em que são gerados pelo agente. Essa visualização mostra todas as etapas que o agente realiza para chegar à resposta final, incluindo o raciocínio e os dados intermediários.
Orientação de renderização para raciocínio e recuperação granular de dados
A tabela a seguir descreve as mensagens do sistema que representam o raciocínio do agente e as etapas de recuperação granular, além de recomendações sobre como renderizar essas mensagens.
| Mensagem do sistema | Orientações sobre renderização |
|---|---|
TextMessage com um valor TextType de THOUGHT |
Renderizar etapas de raciocínio. Mostre essas mensagens para exibir o processo de raciocínio interno do agente. Essas mensagens têm duas partes:
parts[0]) como o indicador de status temporário. |
TextMessage com um valor TextType de PROGRESS |
Mostrar mensagens do PROGRESS. Mostre essas mensagens para fornecer insights sobre as ações do agente. São mensagens informativas sobre o progresso do agente, como uma ferramenta que está sendo invocada. Isso é diferente do processo de pensamento interno do agente (THOUGHT) e da resposta final ao usuário (FINAL_RESPONSE). Essas mensagens têm duas partes:
|
DataQuery e DataResult com um nome que termina em _sample_values |
Mostrar mensagens intermediárias DataQuery e DataResult. As mensagens DataQuery e DataResult com um campo name que termina em _sample_values são etapas intermediárias para a recuperação granular de dados e não aparecem na visualização principal de respostas. Inclua essas informações na visualização da resposta completa (atrás de uma alternância) para mostrar as etapas que o agente realiza. |
DataResult com um campo data vazio |
Mostrar apenas a mensagem DataQuery associada. Não mostre mensagens DataResult com um campo data vazio em nenhuma visualização. Na visualização de detalhes completa, mostre a mensagem DataQuery que resultou no resultado vazio (atrás de uma alternância). Isso permite que o usuário veja a consulta executada, mesmo que ela não tenha gerado resultados. O resumo da resposta final (TextMessage com o tipo FINAL_RESPONSE) já terá informado ao usuário que a consulta não retornou dados. |
Exemplo: renderizar a visualização de detalhes completa
Quando um usuário muda a opção Mostrar raciocínio para o estado expandido, a UI mostra o raciocínio do agente etapa por etapa.
A transcrição a seguir demonstra a visualização de detalhes completa, incluindo as etapas de raciocínio. Para mensagens DataQuery, os detalhes da consulta podem ser mostrados por padrão, opcionalmente atrás de uma alternância inline indicada por um ícone expandido (), como mostrado na transcrição.
Usuário: compare o total de vendas do Grupo Cymbal em 2022 e 2023. Represente o resultado em um gráfico.
Agente:
Como entender o esquema
Para comparar o total de vendas do "Cymbal Group" em 2022 e 2023, preciso consultar a análise detalhada "Itens do pedido". Vou filtrar pelo nome do produto "Cymbal Group" e pelos anos de 2022 e 2023. Em seguida, vou recuperar os campos
Total SaleseCreated Year.Este é o resultado da consulta para o Total de vendas do grupo Cymbal em 2022 e 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"}} ]
Ano de criação Total de vendas 2023 US$ 96.627,00 2022 US$ 93.095,50 Como representar a distribuição de vendas
Recuperei o total de vendas do "Cymbal Group" em 2022 e 2023. Agora vou gerar um gráfico para visualizar essa comparação e fornecer a resposta final.
Gere um gráfico de barras comparando o total de vendas do "Cymbal Group" em 2022 e 2023. O eixo x representa o ano, e o eixo y representa o total de vendas.
O total de vendas do Grupo Cymbal em 2022 foi de US$93.095,50 e, em 2023, de US$96.627,00.
A tabela a seguir mapeia as etapas da interação de exemplo para as mensagens do sistema da API correspondentes.
| Elemento | Mensagem de origem |
|---|---|
| "Como entender o esquema" (resumo do pensamento) | TextMessage (tipo THOUGHT, parts[0]) |
| "Para comparar o total de vendas..." (texto completo do pensamento) | TextMessage (tipo THOUGHT, parts[1]) |
| Consulta gerada (JSON mostrado quando a chave é expandida) | DataQuery |
| Tabela de dados | DataResult |
| "Traçando a distribuição de vendas" (resumo do pensamento) | TextMessage (tipo THOUGHT, parts[0]) |
| "Recuperei..." (texto completo do pensamento) | TextMessage (tipo THOUGHT, parts[1]) |
| Gráfico de barras | ChartResult |
| Resposta final em texto | TextMessage (FINAL_RESPONSE) |