使用撰寫的背景資訊引導代理程式行為

本頁面說明如何編寫有效的提示，以供 Conversational Analytics API 資料代理程式使用。這些提示是您使用 system_instruction 參數定義為字串的撰寫內容。結構良好的系統指令可提高 API 回覆的準確度和關聯性。

如需不同環境中撰寫的內容情境範例，請參閱下列說明文件頁面：

什麼是系統指示？

系統指令是開發人員定義的指引，可提供給資料代理程式，藉此塑造代理程式的行為，並改善 API 的回應。系統指令是 API 用來回答問題的脈絡資訊之一。這個脈絡也包括已連結的資料來源 (BigQuery 資料表、Looker 探索、Looker Studio 資料來源) 和對話記錄 (適用於多輪對話)。

透過系統指令提供清楚的結構化指引，有助於提升服務專員解讀使用者問題的能力，並生成實用且準確的回覆。如果您要連結至 BigQuery 資料表等資料，系統指令定義完善就特別實用，因為這類資料可能沒有預先定義的語意層 (如 Looker 探索功能)。

舉例來說，您可以使用系統指令，為代理程式提供下列類型的指引：

  • 特定商家的邏輯：將「忠實」顧客定義為在特定時間範圍內購買超過五次的顧客。
  • 回覆格式：將資料代理程式的所有回覆總結成 20 字以內，節省使用者時間。
  • 資料呈現：將所有數字格式設為符合公司風格指南。

提供系統指示

您可以使用 system_instruction 參數，以 YAML 格式的字串向 Conversational Analytics API 提供系統指令。雖然 system_instruction 參數為選用，但建議提供結構良好的系統指令，以獲得準確且相關的回覆。

您可以在初始設定期間，於程式碼中定義 YAML 格式的字串，如「設定初始設定和驗證」(HTTP) 或「指定帳單專案和系統指令」(Python SDK) 所示。然後在下列 API 呼叫中加入 system_instruction 參數：

系統指令的 YAML 範本

下列範本顯示提供給 system_instruction 參數的字串建議 YAML 結構，包括可用鍵和預期資料類型。

您可以使用下列 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 說明常用欄位

fields 鍵會巢狀內嵌在 table 物件中，並採用欄位物件清單來描述個別資料欄。並非所有欄位都需要額外背景資訊，但如果提供常用欄位的詳細資料，有助於提升服務專員的成效。

下列 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 定義業務指標

measures 鍵 (位於 table 物件中) 會定義自訂商家指標或計算，這些指標或計算不會直接顯示為表格中的資料欄。提供指標的背景資訊，有助於代理商回答有關主要成效指標 (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 提高準確度

golden_queries 鍵 (位於 table 物件內) 會採用 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 規劃多步驟工作

golden_action_plans 鍵 (位於 table 物件內) 會採用 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.