本指南介绍了建议的方法，用于使用 Looker 数据源在界面 (UI) 中呈现来自 Conversational Analytics API 的输出。
当用户查询 API 时，除了最终回答之外，回答还可以包含中间推理步骤。本指南介绍了如何通过实现主要回答视图和完整详细信息视图来呈现不同详细程度的 API 响应：
- 主要回答视图直接向用户显示问题的回答。此视图提供简洁的呈现方式，不会预先包含有关智能体推理的详细信息。
- 完整详细信息视图会显示智能体得出最终回答的完整推理过程，包括主要回答视图中的所有元素。
建议采用的界面模式是默认显示主要回答视图，并提供一个界面控件（例如按钮或切换开关），让用户可以切换到完整详细信息视图。虽然推理详细信息有助于验证逻辑，但默认显示这些详细信息可能会给主要对最终回答感兴趣的用户增加不必要的详细信息。
主要回答视图
如需仅呈现用户问题的最终直接回答，请按照本部分中的步骤操作。此视图侧重于最终输出，不包含中间步骤。
系统消息呈现指南
下表介绍了被视为最终直接回答的系统消息，以及有关如何呈现这些消息的建议。
| 系统消息 | 渲染指南 |
|---|---|
DataQuery |
使用关联的结果进行渲染。仅在呈现相应的 DataResult 消息时呈现此消息。在以下情况下，请勿渲染 DataQuery 消息：
|
DataResult |
呈现所有 DataResult 消息，但中间结果和空结果除外。在以下情况下，请勿渲染 DataResult 消息：
|
ChartResult |
呈现所有图表。呈现 API 响应中的所有 ChartResult 消息。 |
TextMessage |
仅呈现最终回答。仅当 TextType 值为 FINAL_RESPONSE 时，才渲染 TextMessage 消息。 |
示例：呈现主要回答视图
您可以实现一个切换开关（例如显示推理），让用户从主要回答视图切换到完整详细信息视图。
以下转写内容展示了主要回答视图。对于 DataQuery 消息，我们建议将查询详细信息隐藏在内嵌切换开关（在转写中以收起图标 [] 表示）后面，以便选择性地访问底层查询逻辑。
用户：比较 Cymbal Group 在 2022 年和 2023 年的总销售额。在图表上绘制结果。
智能体：
以下是“Total Sales Cymbal Group 2022 2023”的查询结果。
创建年份 总销售额 2023 $96,627.00 2022 $93,095.50 Cymbal Group 在 2022 年和 2023 年的总销售额
Cymbal Group 在 2022 年的销售总额为 $93,095.50，在 2023 年的销售总额为 $96,627.00。
下表将示例互动中的元素映射到相应的 API 系统消息。
| 元素 | 来源消息 |
|---|---|
| 生成的查询（默认情况下，JSON 隐藏在 开关后面） | DataQuery |
| 数据表格 | DataResult |
| 条形图 | ChartResult |
| 最终文本回答 | TextMessage (FINAL_RESPONSE) |
完整详细信息视图
使用此指南可呈现完整的推理过程。此视图包含主要回答视图中的所有内容，并按智能体生成内容和步骤的顺序显示这些内容和步骤。此视图会显示智能体为生成最终回答而采取的所有步骤，包括推理过程和中间数据。
推理和精细数据检索的呈现指南
下表介绍了表示智能体推理和精细检索步骤的系统消息，以及有关如何呈现这些消息的建议。
| 系统消息 | 渲染指南 |
|---|---|
TextType 值为 THOUGHT 的 TextMessage |
渲染推理步骤。显示这些消息可展示智能体的内部思考过程。这些消息包含两部分：
parts[0]) 显示为临时状态指示器。 |
TextType 值为 PROGRESS 的 TextMessage |
显示 PROGRESS 消息。显示这些消息可深入了解智能体的操作。这些是有关智能体进度的信息性消息，例如正在调用的工具。这与智能体的内部思考过程 (THOUGHT) 和给用户的最终回答 (FINAL_RESPONSE) 不同。这些消息包含两部分：
|
名称以 _sample_values 结尾的 DataQuery 和 DataResult |
显示中间 DataQuery 和 DataResult 消息。包含以 _sample_values 结尾的 name 字段的 DataQuery 和 DataResult 消息都是用于精细数据检索的中间步骤，不会显示在主要回答视图中。在完整回答视图中（通过切换开关）包含这些信息，以显示智能体执行的步骤。 |
具有空 data 字段的 DataResult |
仅显示关联的 DataQuery 消息。在任何视图中，都不显示 DataResult 消息中 data 字段为空的情况。在完整详细信息视图中，显示导致结果为空的 DataQuery 消息（位于切换开关后面）。这样，用户即使没有获得任何查询结果，也可以看到执行的查询。最终回答摘要（类型为 FINAL_RESPONSE 的 TextMessage）已告知用户查询未返回任何数据。 |
示例：呈现完整详细信息视图
当用户将显示推理切换开关切换到展开状态时，界面会显示智能体的逐步推理过程。
以下转写内容展示了完整详细信息视图，包括推理步骤。对于 DataQuery 消息，默认情况下可以显示查询详细信息，也可以选择将其隐藏在由展开图标 () 指示的内嵌切换开关后面，如转写中所示。
用户：比较 Cymbal Group 在 2022 年和 2023 年的总销售额。在图表上绘制结果。
智能体：
了解架构
若要比较 2022 年与 2023 年 Cymbal Group 的总销售额，我需要查询“订单项”探索。我将按商品名称“Cymbal Group”以及 2022 年和 2023 年进行过滤。然后，我将检索
Total Sales和Created Year字段。以下是“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"}} ]
创建年份 总销售额 2023 $96,627.00 2022 $93,095.50 绘制销售分布图
我已检索到“Cymbal Group”在 2022 年和 2023 年的总销售额。现在，我将生成一个图表来直观呈现此比较结果，然后提供最终回答。
生成一个条形图，比较“Cymbal Grou”在 2022 年和 2023 年的总销售额。x 轴应表示年份，y 轴应表示总销售额。
Cymbal Group 在 2022 年的销售总额为 $93,095.50，在 2023 年的销售总额为 $96,627.00。
下表将示例互动中的元素映射到相应的 API 系统消息。
| 元素 | 来源消息 |
|---|---|
| “了解架构”（思考摘要） | TextMessage（类型 THOUGHT、parts[0]） |
| “比较总销售额…”（完整思考文本） | TextMessage（类型 THOUGHT、parts[1]） |
| 生成的查询（展开 开关后显示的 JSON） | DataQuery |
| 数据表格 | DataResult |
| “绘制销售分布图”（思考摘要） | TextMessage（类型 THOUGHT、parts[0]） |
| “我已检索到…”（完整思考文本） | TextMessage（类型 THOUGHT、parts[1]） |
| 条形图 | ChartResult |
| 最终文本回答 | TextMessage (FINAL_RESPONSE) |