作成されたコンテキストでエージェントの動作をガイドする

このページでは、Conversational Analytics API データ エージェント用の効果的なプロンプトを作成するための推奨構造について説明します。これらのプロンプトは、system_instruction パラメータを使用して文字列として定義する作成済みのコンテキストです。構造化されたシステム指示を使用すると、API が提供するレスポンスの精度と関連性を高めることができます。

システム指示とは

システム指示は、デベロッパーがデータ エージェントの動作を形成し、API の回答を調整するために提供できるユーザー定義のガイダンスです。システム指示は、API が質問に回答するために使用するコンテキストの一部です。このコンテキストには、接続されたデータソース（BigQuery テーブル、Looker Explore、Looker Studio データソース）と会話履歴（マルチターンの会話の場合）も含まれます。

システム指示を通じて明確で構造化されたガイダンスを提供することで、エージェントがユーザーの質問を解釈し、有用で正確な回答を生成する能力を高めることができます。明確に定義されたシステム指示は、BigQuery テーブルなどのデータに接続する場合に特に役立ちます。ここでは、Looker Explore のように事前定義のセマンティック レイヤがない可能性があるためです。

たとえば、システム指示を使用して、エージェントに次のようなガイダンスを提供できます。

  • ビジネス固有のロジック: 特定の期間内に 5 回以上購入した顧客を「リピーター」と定義します。
  • 回答の形式: ユーザーの時間を節約するため、データ エージェントからのすべての回答を 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_instrucction キーの基本構造を示しています。

- system_instruction: str

たとえば、次のように、架空の e コマースストアのセールス アナリストとしてエージェントを定義できます。

- 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.

たとえば、次の YAML コードブロックは、テーブル bigquery-public-data.thelook_ecommerce.orders の tables キーの基本構造を示しています。

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - description: Data for customer orders in The Look fictitious e-commerce store.
        - synonyms:
            - sales
            - orders_data
        - tags:
            - ecommerce
            - transaction

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.

たとえば、次の YAML コードサンプルでは、orders テーブルの order_id、status、created_at、num_of_items、earnings などのキーフィールドを記述しています。

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: The timestamp when the order was created.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations:
                    - sum
                    - avg
            - field:
                - name: earnings
                - description: The sales amount for the order.
                - aggregations:
                    - sum
                    - avg

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.

たとえば、次のように、収益から費用を差し引いた計算として profit メジャーを定義できます。

- tables:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms:
                    - gains

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.

たとえば、orders テーブルのデータの一般的な分析用に、次のようにゴールデン クエリを定義できます。

- tables:
    - table:
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'

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.

たとえば、年齢層別の注文の内訳を表示するアクション プランを定義し、SQL クエリと可視化関連の手順の詳細を含めることができます。

- tables:
    - table:
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.

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.

たとえば、次のように bigquery-public-data.thelook_ecommerce.orders テーブルと bigquery-public-data.thelook_ecommerce.users テーブルの間に orders_to_user 関係を定義できます。

- relationships:
    - relationship:
        - name: orders_to_user
        - description: >-
            Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id

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.

たとえば、次のように、特定のビジネス コンテキストに従って、一般的なビジネス ステータスや「OMPF」などの用語を定義できます。

- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: shipped
        - description: Represents an order status where the order has been shipped to the customer.
    - glossary:
        - term: returned
        - description: Represents an order status where the customer has returned the order.
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment

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.

たとえば、additional_descriptions キーを使用して、次のように組織に関する情報を提供できます。

- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.
    - text: 'Orders can be of three categories: food, clothes, and electronics.'

例: システム指示

次の例は、架空のセールス アナリストとして定義したエージェントへのシステム指示のサンプルを示しています。

- 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:
    - table:
        - name: bigquery-public-data.thelook_ecommerce.orders
        - description: Data for orders in The Look, a fictitious ecommerce store.
        - synonyms: sales
        - tags: 'sale, order, sales_order'
        - fields:
            - field:
                - name: order_id
                - description: The unique identifier for each customer order.
            - field:
                - name: user_id
                - description: The unique identifier for each customer.
            - field:
                - name: status
                - description: The current status of the order.
                - sample_values:
                    - complete
                    - shipped
                    - returned
            - field:
                - name: created_at
                - description: >-
                    The date and time at which the order was created in timestamp
                    format.
            - field:
                - name: returned_at
                - description: >-
                    The date and time at which the order was returned in timestamp
                    format.
            - field:
                - name: num_of_items
                - description: The total number of items in the order.
                - aggregations: 'sum, avg'
            - field:
                - name: earnings
                - description: The sales revenue for the order.
                - aggregations: 'sum, avg'
            - field:
                - name: cost
                - description: The cost for the items in the order.
                - aggregations: 'sum, avg'
        - measures:
            - measure:
                - name: profit
                - description: Raw profit (earnings minus cost).
                - exp: earnings - cost
                - synonyms: gains
        - golden_queries:
            - golden_query:
                - natural_language_query: How many orders are there?
                - sql_query: SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
            - golden_query:
                - natural_language_query: How many orders were shipped?
                - sql_query: >-
                    SELECT COUNT(*) FROM sqlgen-testing.thelook_ecommerce.orders
                    WHERE status = 'shipped'
        - golden_action_plans:
            - golden_action_plan:
                - natural_language_query: Show me the number of orders broken down by age group.
                - action_plan:
                    - step: >-
                        Run a SQL query that joins the table
                        sqlgen-testing.thelook_ecommerce.orders and
                        sqlgen-testing.thelook_ecommerce.users to get a
                        breakdown of order count by age group.
                    - step: >-
                        Create a vertical bar plot using the retrieved data,
                        with one bar per age group.
    - table:
        - name: bigquery-public-data.thelook_ecommerce.users
        - description: Data for users in The Look, a fictitious ecommerce store.
        - synonyms: customers
        - tags: 'user, customer, buyer'
        - fields:
            - field:
                - name: id
                - description: The unique identifier for each user.
            - field:
                - name: first_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'alex, izumi, nur'
            - field:
                - name: last_name
                - description: The first name of the user.
                - tag: person
                - sample_values: 'warmer, stilles, smith'
            - field:
                - name: age_group
                - description: The age demographic group of the user.
                - sample_values:
                    - 18-24
                    - 25-34
                    - 35-49
                    - 50+
            - field:
                - name: email
                - description: The email address of the user.
                - tag: contact
                - sample_values: '222larabrown@gmail.com, cloudysanfrancisco@gmail.com'
        - golden_queries:
            - golden_query:
                - natural_language_query: How many unique customers are there?
                - sql_query: >-
                    SELECT COUNT(DISTINCT id) FROM
                    bigquery-public-data.thelook_ecommerce.users
            - golden_query:
                - natural_language_query: How many users in the 25-34 age group have a cymbalgroup email address?
                - sql_query: >-
                    SELECT COUNT(DISTINCT id) FROM
                    bigquery-public-data.thelook_ecommerce.users WHERE users.age_group =
                    '25-34' AND users.email LIKE '%@cymbalgroup.com';
    - relationships:
        - relationship:
            - name: orders_to_user
            - description: >-
                Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
            - relationship_type: many-to-one
            - join_type: left
            - left_table: bigquery-public-data.thelook_ecommerce.orders
            - right_table: bigquery-public-data.thelook_ecommerce.users
            - relationship_columns:
                - left_column: user_id
                - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: shipped
        - description: Represents an order status where the order has been shipped to the customer.
    - glossary:
        - term: returned
        - description: Represents an order status where the customer has returned the order.
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.
    - text: 'Orders can be of three categories: food, clothes, and electronics.'