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

このページでは、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_instruction キーの基本構造を示しています。

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

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.