Renderize respostas do agente para origens de dados do Looker

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Este guia descreve abordagens recomendadas para renderizar resultados da API Conversational Analytics numa interface do utilizador (IU) através de origens de dados do Looker.

Quando um utilizador consulta a API, a resposta pode incluir passos de raciocínio intermédios, além da resposta final. Este guia descreve como renderizar respostas da API com diferentes níveis de detalhe através da implementação de uma vista de resposta principal e uma vista de detalhes completos:

• A vista de resposta principal apresenta a resposta à pergunta do utilizador diretamente. Esta vista apresenta uma apresentação concisa e não inclui detalhes sobre o raciocínio do agente antecipadamente.
• A vista de detalhes completos apresenta o processo de raciocínio completo que o agente segue para chegar à resposta final, incluindo todos os elementos da vista de resposta principal.

Um padrão de IU recomendado é apresentar a vista de resposta principal por predefinição e fornecer um controlo da IU, como um botão ou um interruptor, que permita aos utilizadores mudar para a vista de detalhes completos. Embora os detalhes do raciocínio sejam úteis para validar a lógica, a apresentação predefinida dos mesmos pode adicionar detalhes desnecessários para os utilizadores que estão principalmente interessados na resposta final.

Vista de resposta principal

Para renderizar apenas a resposta direta final à pergunta do utilizador, siga os passos nesta secção. Esta vista foca-se no resultado final e exclui os passos intermédios.

Orientações de renderização de mensagens do sistema

A tabela seguinte descreve as mensagens do sistema consideradas respostas diretas finais, juntamente com recomendações sobre como renderizar estas mensagens.

Mensagem do sistema	Orientações de renderização
DataQuery	Renderizar com o resultado associado. Apresente esta mensagem apenas nos casos em que apresenta a mensagem DataResult correspondente. Não renderize mensagens DataQuery nos seguintes casos: O campo name da mensagem DataQuery termina em _sample_values (por exemplo, products_brand_sample_values). O campo name da mensagem DataResult correspondente termina em _sample_values. O campo data na mensagem DataResult correspondente está vazio. Recomendamos que coloque o texto da consulta num botão para apresentar a consulta de origem a pedido. Por exemplo, a análise conversacional no Looker usa um controlo "Como é que isto foi calculado?".
DataResult	Renderizar todas as mensagens DataResult, exceto os resultados intermédios e vazios. Não renderize mensagens DataResult nos seguintes casos: O campo name termina em _sample_values. Estes são passos intermédios para obter valores de exemplo de um campo específico. O campo data está vazio. Estes resultados são resumidos na resposta TextMessage final.
ChartResult	Renderizar todos os gráficos. Renderizar todas as mensagens ChartResult na resposta da API.
TextMessage	Apresentar apenas respostas finais. Apresente mensagens TextMessage apenas quando o valor de TextType for FINAL_RESPONSE.

Exemplo: renderizar a vista de resposta principal

Pode implementar um botão ativar/desativar, como Mostrar raciocínio, para permitir que os utilizadores alternem entre a vista de resposta principal e a vista de detalhes completa.

A seguinte transcrição demonstra a vista de resposta principal. Para mensagens DataQuery, recomendamos que oculte os detalhes da consulta atrás de um botão inline, indicado na transcrição por um ícone reduzido (), para fornecer acesso opcional à lógica de consulta subjacente.

Utilizador: compara o total de vendas do grupo Cymbal em 2022 com 2023. Representar o resultado num gráfico.

Agente:

Aqui está o resultado da consulta para Total Sales Cymbal Group 2022 2023.

Ano de criação	Total de vendas
2023	96 627,00 €
2022	93 095,50 €

Total de vendas do grupo Cymbal em 2022 e 2023

O total de vendas do grupo Cymbal em 2022 foi de 93 095,50 € e, em 2023, foi de 96 627,00 €.

A tabela seguinte mapeia os elementos da interação de exemplo com as respetivas mensagens do sistema da API.

Elemento	Mensagem de origem
Consulta gerada (JSON oculto atrás do botão por predefinição)	DataQuery
Tabela de dados	DataResult
Gráfico de barras	ChartResult
Resposta de texto final	TextMessage (FINAL_RESPONSE)

Vista de detalhes completos

Use estas orientações para renderizar o processo de raciocínio completo. Esta vista inclui tudo o que está na vista de resposta principal e mostra o conteúdo e os passos pela ordem em que são gerados pelo agente. Esta vista apresenta todos os passos que o agente realiza para chegar à resposta final, incluindo o respetivo raciocínio e dados intermédios.

Orientações de renderização para o raciocínio e a obtenção de dados detalhados

A tabela seguinte descreve as mensagens do sistema que representam o raciocínio do agente e os passos de obtenção detalhados, juntamente com recomendações sobre como renderizar estas mensagens.

Mensagem do sistema	Orientações de renderização
TextMessage com um valor de TextType de THOUGHT	Apresentar passos de raciocínio. Apresente estas mensagens para mostrar o processo de raciocínio interno do agente. Estas mensagens contêm duas partes: parts[0] é o resumo do pensamento, que resume brevemente o texto completo do pensamento parts[1] é o texto de reflexão completo Se a sua aplicação apresentar atualizações de estado (como um indicador de carregamento ou uma barra de progresso), recomendamos que apresente o resumo do raciocínio (parts[0]) como o indicador de estado transitório.
TextMessage com um valor de TextType de PROGRESS	Apresentar PROGRESS mensagens. Apresente estas mensagens para fornecer estatísticas sobre as ações do agente. Estas são mensagens informativas sobre o progresso do agente, como uma ferramenta que está a ser invocada. Isto é diferente do processo de raciocínio interno do agente (THOUGHT) e da resposta final ao utilizador (FINAL_RESPONSE). Estas mensagens contêm duas partes: parts[0] é o resumo. parts[1] é o texto de progresso completo.
DataQuery e DataResult com um nome terminado em _sample_values	Apresentar mensagens intermédias DataQuery e DataResult. As mensagens DataQuery e DataResult com um campo name que termina em _sample_values são passos intermédios para a obtenção de dados detalhados e não são apresentadas na vista de resposta principal. Inclua-os na vista de resposta completa (atrás de um botão) para mostrar os passos que o agente realiza.
DataResult com um campo data vazio	Apresentar apenas a mensagem DataQuery associada. Não apresentar mensagens DataResult com um campo data vazio em nenhuma vista. Na vista de detalhes completos, apresente a mensagem DataQuery que originou o resultado vazio (atrás de um botão). Isto permite ao utilizador ver a consulta que foi executada, mesmo que não tenha gerado resultados. O resumo da resposta final (TextMessage com o tipo FINAL_RESPONSE) já informou o utilizador de que a consulta não devolveu dados.

Exemplo: renderizar a vista de detalhes completa

Quando um utilizador muda o botão Mostrar raciocínio para o estado expandido, a IU revela o raciocínio passo a passo do agente.

A transcrição seguinte demonstra a vista de detalhes completa, incluindo os passos de raciocínio. Para DataQuery mensagens, os detalhes da consulta podem ser apresentados por predefinição, opcionalmente atrás de um botão inline indicado por um ícone expandido (), conforme mostrado na transcrição.

Utilizador: compara o total de vendas do grupo Cymbal em 2022 com 2023. Representar o resultado num gráfico.

Agente:

Compreender o esquema

Para comparar o total de vendas de "Cymbal Group" em 2022 com 2023, tenho de consultar a análise detalhada "Itens de encomenda". Vou filtrar por nome do produto "Cymbal Group" e pelos anos 2022 e 2023. Em seguida, vou obter os campos Total Sales e Created Year.

Aqui está o resultado da consulta para Total Sales 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"}}
]

Ano de criação	Total de vendas
2023	96 627,00 €
2022	93 095,50 €

Representar graficamente a distribuição de vendas

Recuperei o total de vendas de "Cymbal Group" para 2022 e 2023. Agora, vou gerar um gráfico para visualizar esta comparação e, em seguida, fornecer a resposta final.

Gera um gráfico de barras que compara o total de vendas do grupo "Cymbal Group" em 2022 e 2023. O eixo X deve representar o ano e o eixo Y deve representar o total de vendas.

O total de vendas do grupo Cymbal em 2022 foi de 93 095,50 € e, em 2023, foi de 96 627,00 €.

A tabela seguinte mapeia os passos da interação de exemplo com as respetivas mensagens do sistema da API.

Elemento	Mensagem de origem
"Compreender o esquema" (resumo do raciocínio)	TextMessage (tipo THOUGHT, parts[0])
"Para comparar o total de vendas…" (texto de pensamento completo)	TextMessage (tipo THOUGHT, parts[1])
Consulta gerada (JSON apresentado quando o botão está expandido)	DataQuery
Tabela de dados	DataResult
"Representar graficamente a distribuição de vendas" (resumo do raciocínio)	TextMessage (tipo THOUGHT, parts[0])
"Recuperei…" (texto de pensamento completo)	TextMessage (tipo THOUGHT, parts[1])
Gráfico de barras	ChartResult
Resposta de texto final	TextMessage (FINAL_RESPONSE)