使用编写的上下文来引导智能体行为

本页面介绍了一种建议的结构来为 Conversational Analytics API 数据智能体编写有效的提示。您可以使用 system_instruction 参数编写字符串形式的上下文，来定义这些提示。结构清晰的系统指令可以提高 API 所提供回答的准确性和相关性。

如需查看不同环境中所编写上下文的示例，请参阅以下文档页面：

什么是系统指令？

系统指令是一种用户定义的准则，开发者可以通过提供系统指令来引导数据智能体的行为并优化 API 的回答。系统指令是 API 据此回答问题的上下文的一部分。此上下文还包括所连接的数据源（BigQuery 表、Looker 探索、Looker Studio 数据源）和对话记录（针对多轮对话）。

通过系统指令进行清晰的结构化引导，您可以提高智能体解读用户问题的能力，并生成有用的准确回答。如果您要连接到 BigQuery 表等数据，那么提供明确定义的系统指令则尤为重要，因为与 Looker 探索不同，这些数据可能没有预定义的语义层。

例如，您可以使用系统指令对智能体进行以下类型的引导：

  • 业务特定逻辑：将“忠实”客户定义为在特定时间范围内购买次数超过 5 次的客户。
  • 回答格式：将数据智能体的所有回答总结为不超过 20 个字，以节省用户的时间。
  • 数据呈现：将所有数字的格式设置为符合公司的风格指南。

提供系统指令

您可以使用 system_instruction 参数以 YAML 格式的字符串形式向 Conversational Analytics API 提供系统指令。虽然 system_instruction 是可选参数，但建议您通过该参数提供结构清晰的系统指令，以便获得准确且相关的回答。

您可以在初始设置期间在代码中定义 YAML 格式的字符串，如配置初始设置和身份验证 (HTTP) 或指定结算项目和系统指令 (Python SDK) 中所示。之后，您可以在以下 API 调用中添加 system_instruction 参数：

系统指令的 YAML 模板

以下模板展示了一种建议的 YAML 结构来为 system_instruction 参数提供字符串，包括可用的键和预期的数据类型。

您可以使用以下 YAML 模板来提供自己的系统指令：

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
    - table: # Details about a single table that is relevant for the agent.
        - name: str # The name of the table.
        - description: str # A description of the table.
        - synonyms: list[str] # Alternative terms for referring to the table.
        - tags: list[str] # Keywords or tags that are associated with the table.
        - fields: # Details about columns (fields) within the table.
            - field: # Details about a single column within the current table.
                - name: str # The name of the column.
                - description: str # A description of the column.
                - synonyms: list[str] # Alternative terms for referring to the column.
                - tags: list[str] # Keywords or tags that are associated with the column.
                - sample_values: list[str] # Sample values that are present within the column.
                - aggregations: list[str] # Commonly used or default aggregations for the column.
        - measures: # A list of calculated metrics (measures) for the table.
            - measure: # Details about a single measure within the table.
                - name: str # The name of the measure.
                - description: str # A description of the measure.
                - exp: str # The expression that is used to construct the measure.
                - synonyms: list[str] # Alternative terms for referring to the measure.
        - golden_queries: # A list of important or popular ("golden") queries for the table.
            - golden_query: # Details about a single golden query.
                - natural_language_query: str # The natural language query.
                - sql_query: str # The SQL query that corresponds to the natural language query.
        - golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
            - golden_action_plan: # Details about a single action plan.
                - natural_language_query: str # The natural language query.
                - action_plan: # A list of the steps for this action plan.
                    - step: str # A single step within the action plan.
    - relationships: # A list of join relationships between tables.
        - relationship: # Details about a single join relationship.
            - name: str # The name of this join relationship.
            - description: str # A description of the relationship.
            - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
            - join_type: str # The join type: inner, outer, left, right, or full.
            - left_table: str # The name of the left table in the join.
            - right_table: str # The name of the right table in the join.
            - relationship_columns: # A list of columns that are used for the join.
                - left_column: str # The join column from the left table.
                - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
    - glossary: # The definition for a single glossary item.
        - term: str # The term, phrase, or abbreviation to define.
        - description: str # A description or definition of the term.
        - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
    - text: str # Any additional general instructions or context not covered elsewhere.

系统指令的关键组成部分

以下部分介绍了系统指令的关键组成部分，以及如何使用这些组成部分来提高智能体回答的质量。这些键包括：

使用 system_instruction 定义智能体的角色及角色设定

使用 system_instruction 键定义智能体的角色及角色设定。此初始指令可为 API 的回答设定基调和风格，并帮助智能体理解其核心目标。

以下 YAML 代码块显示了 system_instruction 键的基本结构：

- system_instruction: str

例如，您可以将智能体定义成一个虚构网店的销售分析师，如下所示：

- system_instruction: >-
    You are an expert sales analyst for a fictitious ecommerce store. You will answer questions about sales, orders, and customer data. Your responses should be concise and data-driven.

使用 tables 描述数据

tables 键为智能体提供了表说明的列表，并提供有关智能体可用来回答问题的特定数据的详细信息。此列表中的每个 table 对象都包含一个特定表的元数据，包括相应表的名称、说明、同义词、标记、字段、度量、黄金查询和黄金操作方案。

以下 YAML 代码块显示了 tables 键的基本结构：

- tables:
    - table:
      - name: str # The name of the table.
      - description: str # A description of the table.
      - synonyms: list[str] # Alternative terms for referring to the table.
      - tags: list[str] # Keywords or tags that are associated with the table.
      - fields: # A list of the fields in the table.
      - measures: # A list of the measures in the table.
      - golden_queries: # A list of golden queries for the table.
      - golden_action_plans: # A list of golden action plans for the table.

使用 fields 描述常用字段

嵌套在 table 对象中的 fields 键接受字段对象列表作为输入来描述各列。并非所有字段都需要提供额外的上下文信息；不过，对于常用字段，添加额外的详细信息有助于提升智能体的性能。

以下 YAML 代码块显示了 fields 键的基本结构：

- fields: # Details about columns (fields) within the table.
    - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - description: str # A description of the column.
        - synonyms: list[str] # Alternative terms for referring to the column.
        - tags: list[str] # Keywords or tags that are associated with the column.
        - sample_values: list[str] # Sample values that are present within the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.

使用 measures 定义业务指标

嵌套在 table 对象中的 measures 键用于定义未直接以列的形式呈现在表中的自定义业务指标或计算。提供衡量指标上下文信息有助于智能体回答有关关键绩效指标 (KPI) 或其他计算值的问题。

以下 YAML 代码块显示了 measures 键的基本结构：

- measures: # A list of calculated metrics (measures) for the table.
    - measure: # Details about a single measure within the table.
        - name: str # The name of the measure.
        - description: str # A description of the measure.
        - exp: str # The expression that is used to construct the measure.
        - synonyms: list[str] # Alternative terms for referring to the measure.

通过 golden_queries 提高准确性

嵌套在 table 对象中的 golden_queries 键接受 golden_query 对象列表作为输入。黄金查询有助于智能体针对常见问题或重要问题提供更准确、更相关的回答。通过为智能体提供每个黄金查询的自然语言查询及相应的 SQL 查询，您可以引导智能体提供更高质量且更一致的结果。

以下 YAML 代码块显示了 golden_queries 键的基本结构：

- golden_queries: # A list of important or popular ("golden") queries for the table.
    - golden_query: # Details about a single golden query.
        - natural_language_query: str # The natural language query.
        - sql_query: str # The SQL query that corresponds to the natural language query.

使用 golden_action_plans 概述多步任务

嵌套在 table 对象中的 golden_action_plans 键接受 golden_action_plan 对象列表作为输入。您可以使用黄金操作方案为智能体提供有关如何处理多步请求的示例，例如提取数据，然后创建可视化图表。

以下 YAML 代码块显示了 golden_action_plans 键的基本结构：

- golden_action_plans: # A list of suggested multi-step plans for answering specific queries.
    - golden_action_plan: # Details about a single action plan.
        - natural_language_query: str # The natural language query.
        - action_plan: # A list of the steps for this action plan.
            - step: str # A single step within the action plan.

使用 relationships 定义表联接

relationships 键包含表之间联接关系的列表。通过定义联接关系，有助于智能体理解在回答问题时应如何联接来自多个表的数据。

以下 YAML 代码块显示了 relationships 键的基本结构：

- relationships: # A list of join relationships between tables.
    - relationship: # Details for a single join relationship.
        - name: str # A unique name for this join relationship.
        - description: str # A description of the relationship.
        - relationship_type: str # The join relationship type (e.g., "one-to-one", "one-to-many", "many-to-one", "many-to-many").
        - join_type: str # The join type (e.g., "inner", "outer", "left", "right", "full").
        - left_table: str # The name of the left table in the join.
        - right_table: str # The name of the right table in the join.
        - relationship_columns: # A list of columns that are used for the join.
            - left_column: str # The join column from the left table.
            - right_column: str # The join column from the right table.

通过 glossaries 解释业务术语

glossaries 键列出了与您的数据及应用场景相关的业务术语、行话和缩写的定义。通过提供词汇表定义，有助于智能体准确解读并回答使用特定业务语言的问题。

以下 YAML 代码块显示了 glossaries 键的基本结构：

- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
    - glossary: # The definition for a single glossary item.
        - term: str # The term, phrase, or abbreviation to define.
        - description: str # A description or definition of the term.
        - synonyms: list[str] # Alternative terms for the glossary entry.

通过 additional_descriptions 添加更多说明

additional_descriptions 键列出了系统指令中未涵盖的任何其他一般性说明或上下文信息。通过提供更多说明，有助于智能体更好地理解您的数据及应用场景的上下文信息。

以下 YAML 代码块显示了 additional_descriptions 键的基本结构：

- additional_descriptions: # A list of any other general instructions or content.
    - text: str # Any additional general instructions or context not covered elsewhere.