データ エージェントを作成する

このドキュメントでは、BigQuery でデータ エージェントを作成、編集、管理、削除する方法について説明します。

BigQuery では、データ エージェントと会話し、自然言語で BigQuery データに関する質問をすることができます。データ エージェントには、テーブル メタデータとユースケース固有のクエリ処理の指示が含まれています。これらにより、選択した一連のナレッジソース（テーブル、ビュー、ユーザー定義関数（UDF）など）に関するユーザーからの質問に答える最適な方法を定義します。

始める前に

1. Cloud de Confiance プロジェクトで課金が有効になっていることを確認します。

2. BigQuery、Gemini Data Analytics、Gemini for Cloud de Confiance by S3NS、Knowledge Catalog の各 API がまだ有効になっていない場合は、有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を学習する。

   API を有効にする

必要なロール

データ エージェントを使用するには、ユースケースに一致する Identity and Access Management（IAM）権限が必要です。以降のセクションでは、エージェントの作成と公開、Gemini Enterprise でのエージェントのプロビジョニング、さまざまなサーフェスでのエージェントの検出と使用に基づいて、必要なロールを一覧表示します。詳細については、Conversational Analytics API の IAM ロールをご覧ください。

• エージェントの作成、編集、公開、共有、削除:
  • プロジェクトにデータ エージェントを作成する: プロジェクトに対する Gemini データ分析データ エージェント作成者（roles/geminidataanalytics.dataAgentCreator）。このロールにより、作成したデータ エージェントに対する Gemini データ分析 Data Agent Owner のロールが自動的に付与されます。
  • データ エージェントを編集、共有、削除する: エージェントまたはプロジェクトに対する Gemini Data Analytics Data Agent Owner（roles/geminidataanalytics.dataAgentOwner）。
  • プロジェクト内のデータ エージェントを編集する: プロジェクトに対する Gemini データ分析データ エージェント編集者（roles/geminidataanalytics.dataAgentEditor）。
  • プロジェクト内のデータ エージェントを表示する: プロジェクトに対する Gemini データ分析データ エージェント閲覧者（roles/geminidataanalytics.dataAgentViewer）。
• Gemini Enterprise でエージェントをプロビジョニングする:
  • 公開されたエージェントを Gemini Enterprise のユーザーが利用できるようにするには、カスタム エージェントを登録して管理し、Gemini Enterprise 管理コンソールで Agent Gateway を構成する権限が必要です。
• エージェントを見つけて使用する:
  • データ エージェントとチャットする: Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser）。
  • プロジェクト内のすべてのデータ エージェントを表示する: Gemini データ分析データ エージェント閲覧者（roles/geminidataanalytics.dataAgentViewer）。
  • データポータルで Gemini を搭載したチャット インターフェースを使用するには、BigQuery Studio ユーザー（roles/bigquery.studioUser）または Gemini for Google Cloud ユーザー（roles/cloudaicompanion.user）が必要です。これらのユーザーには cloudaicompanion.topics.create 権限が付与されます。これらのロールは、プロジェクト レベルで付与します。ユーザーには、データポータル アセット閲覧者（roles/datastudio.viewer）のロールも必要です。
• エージェントにナレッジソースを追加する:
  • プロジェクトに対する Data Catalog 閲覧者（roles/datacatalog.viewer）。

会話を行うには、会話に必要なロールをご覧ください。

エージェントはユーザーに代わって動作し、ユーザーの権限を使用します。エージェントは、アクセス権を持つデータとリソースにのみアクセスできます。

ベスト プラクティス

会話分析は、ユーザーに代わってクエリを自動的に実行し、質問に回答します。クエリ費用が増加する可能性がある次の要因を考慮してください。

• テーブルサイズが大きい
• クエリでのデータ結合の使用
• クエリ内の AI 関数の頻繁な呼び出し

分析情報を生成する

必要に応じて、Knowledge Catalog でナレッジソースとして使用するテーブルのデータ分析情報を生成できます。

生成インサイトは、データ エージェントが質問に対する回答を生成するために利用できるテーブル メタデータを提供します。

分析情報を事前に生成していない場合は、データ エージェントの作成時にテーブルをナレッジソースとして選択したときに、システムによって分析情報が自動的に生成されます。

サンプルデータ エージェントを使用する

会話型分析用のエージェントの構成に慣れていない場合は、必要に応じて、すべてのCloud de Confiance プロジェクト用に生成された事前定義済みのサンプル エージェントを表示できます。チャットしたり、パラメータを表示して作成方法を確認したりできますが、変更はできません。

サンプル エージェントを表示する手順は次のとおりです。

1. Cloud de Confiance コンソールで、BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [エージェント カタログ] タブを選択します。

3. [Google によるサンプル エージェント] セクションで、サンプル エージェント カードをクリックします。

データ エージェントを作成する

以降のセクションでは、データ エージェントの作成方法について説明します。

エージェントを作成したら、設定を編集できます。

最初の手順

1. Cloud de Confiance コンソールで、BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [エージェント カタログ] タブを選択します。

3. [新しいエージェント] をクリックします。[新しいエージェント] ページが開きます。

4. [エディタ] セクションの [エージェント名] フィールドに、データ エージェントのわかりやすい名前（Q4 sales data、User activity logs など）を入力します。

5. [エージェントの説明] フィールドに、データ エージェントの説明を入力します。適切な説明では、エージェントの動作、使用するデータ、チャット相手とするデータ エージェントを選択する際に役立つ情報（Ask questions about customer orders and revenue など）を説明します。

6. [ナレッジソース] セクションで、[ソースを追加] をクリックします。[ナレッジソースを追加] ページが開きます。

7. [最近使用したアイテム] セクションで、ナレッジソースとして使用するテーブル、ビュー、グラフ、UDF を選択します。 Cloud de Confiance コンソールでは、UDF の先頭に「fx」インジケーターが付いています。

8. 他のナレッジソースを表示するには、[keyboard_arrow_down さらに表示] を選択します。

9. 省略可: [最近使用したアイテム] セクションにリストされていないナレッジソースを追加します。

   1. [検索] セクションの [テーブルを検索] フィールドにソース名を入力し、Enter キーを押します。ソース名は正確でなくてもかまいません。

   2. [検索結果] セクションで、1 つ以上のソースを選択します。

10. [追加] をクリックします。新しいエージェント ページが再度開きます。

テーブルとフィールドの説明をカスタマイズする

データ エージェントの正確さを高めるために、追加のテーブル メタデータを提供できます。このメタデータはデータ エージェントによってのみ使用されるもので、ソーステーブルには影響しません。

テーブルとフィールドの説明を作成する際は、次のベスト プラクティスに従ってください。

• これらの説明は、データ エージェントがスキーマをどのように理解しているかを把握するためのガイドとして使用してください。エージェントが提案した説明が正しい場合は、承認できます。

• これらの説明を構成してもデータ エージェントがスキーマを理解していない場合は、説明を手動で調整して正しい情報を提供します。

テーブルとフィールドの説明を構成する手順は次のとおりです。

1. [ナレッジソース] セクションで、テーブルの [カスタマイズ] リンクをクリックします。

2. テーブルの説明を作成します。[テーブルの説明] フィールドに説明を入力するか、Gemini からの提案を受け入れます。

3. [フィールド] セクションで、Gemini から提案されたフィールドの説明を確認します。

4. 受け入れるフィールドの説明を選択して、[提案を承認する] をクリックします。却下する説明を選択して、[提案を拒否] をクリックします。

5. フィールドの説明を手動で編集するには、フィールドの横にある [編集] をクリックします。[フィールドを編集] ペインが開きます。

   1. [説明] フィールドに、フィールドの説明を入力します。
   2. フィールドの説明を保存するには、[更新] をクリックします。

6. 説明とフィールドの更新を保存するには、[更新] をクリックします。新しいエージェント ページが再度開きます。

7. カスタマイズが必要なテーブルごとに、この手順を繰り返します。

エージェントへの指示を作成する

エージェントは、カスタム指示がなくてもユーザーの質問のコンテキストを理解する必要があります。エージェントの動作を変更する必要がある場合や、他のコンテキスト機能（カスタム テーブルやフィールドのメタデータ、検証済みのクエリなど）でサポートされていない方法でコンテキストを改善する必要がある場合にのみ、エージェントのカスタム手順を作成します。

[手順] セクションの [エージェントへの指示] フィールドに、データ エージェントへの指示を入力します。データ エージェントは、これらの指示に基づいてユーザーからの質問のコンテキストを理解し、回答を提供するため、指示はできるだけ明確にしてください。

エージェントから満足のいく回答が得られない場合は、説明、例、用語集の用語などの構造化されたコンテキストを追加します。それでも満足のいく回答が得られない場合は、次の表の例のようにカスタム指示を追加します。

指示の例をさらに表示するには、[例を表示] をクリックします。

検証済みクエリを作成する

エージェントは、検証済みのクエリを次の 2 つの方法で使用します。

• エージェントが検証済みクエリを使用して質問に回答できる場合、信頼できる回答を確保するために、エージェントはクエリを記述どおりに呼び出します。
• エージェントが検証済みのクエリを使用して質問に回答できない場合でも、クエリをリファレンスとして使用して、データとクエリのベスト プラクティスを理解します。

システムによって生成されたリストから検証済みのクエリを選択することも、独自のクエリを作成することもできます。

データ エージェントの検証済みクエリ（以前はゴールデン クエリと呼ばれていました）を作成する手順は次のとおりです。

1. Gemini から提案された検証済みクエリを 1 つ以上選択します。

   1. [検証済みクエリ] セクションで、[候補の確認] をクリックします。[提案された検証済みクエリを確認する] ページが開きます。
   2. 検証済みクエリの候補を確認します。ユースケースに該当するものを選択します。
   3. [追加] をクリックします。新しいエージェント ページが再度開きます。

2. 独自の検証済みクエリを作成するには、[クエリを追加] をクリックします。[検証済みクエリの追加] ページが開きます。

   1. [質問] フィールドに、検証済みクエリが回答するユーザーからの質問を入力します。
   2. [SQL を生成] をクリックして、指定したユーザーの質問に対応する検証済みクエリを Gemini に生成させます。
   3. 必要に応じて、検証済みクエリを修正します。
   4. [実行] をクリックし、クエリが想定どおりの結果を返すことを確認します。
   5. [追加] をクリックします。新しいエージェント ページが再度開きます。

3. 必要に応じて、上記の手順を繰り返して追加の検証済みクエリを作成します。

パラメータ化された検証済みクエリを作成する

パラメータ化された検証済みクエリは、会話型分析エージェントのユーザーの質問から値を抽出し、カスタマイズされた結果を提供します。

アナリストとビルダーは、これらの値のプレースホルダを含む再利用可能な SQL テンプレートを作成できます。テンプレートは、実行時にパラメータを動的に置き換えて、通常の検証済みクエリよりも幅広いユーザーの質問に回答します。

ユーザーがテンプレートのパターンに一致する質問をすると、会話分析エージェントは質問からパラメータ値（商品名、リージョン、日付など）を抽出します。次に、これらの値をパラメータ化されたクエリに挿入します。クエリ テンプレートから一致するレスポンスが検証済みとして表示されます。

パラメータ化された検証済みクエリを使用すると、検証済みクエリの機能と柔軟性が大幅に向上します。さまざまな入力に対して一貫性のある信頼できる回答を保証し、維持する個々のクエリの数を減らします。

仕組み

データ アナリストなどのエキスパートが、テンプレートの質問（「@region の @product の売上はいくらでしたか？」など）を使用して、検証済みクエリを定義します。次に、エキスパートは、次の例に示すように、SQL パラメータを使用して検証済みクエリを作成または変更します。

SELECT * FROM sales WHERE region = @region AND product = @product

検証済みのクエリが保存されると、ユーザーは会話分析エージェントに自然言語で質問できます（例: 「北米でのノートパソコンの売上はいくらでしたか？」）。

お客様の質問に答えるため、エージェントは次の手順を行います。

1. 質問を、パラメータ化された検証済みクエリに関連付けられたパターンと照合します。エージェントは、自然言語理解（NLU）を使用して、ユーザーの質問から @region（北米）と @product（ノートパソコン）の値を特定して抽出します。
2. 抽出された値を SQL テンプレートの @region プレースホルダと @product プレースホルダに代入します。
3. 完全な SQL クエリ（SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops' など）を実行します。
4. 結果をユーザーに返します。一致は常に確認済みとしてマークされます。

効果的なパラメータ化されたクエリを作成するためのヒント

• わかりやすいパラメータ名を使用する。パラメータにはわかりやすい名前を使用します（例: @d1 ではなく @start_date）。
• 詳細なパラメータの説明を作成する。会話分析の大規模言語モデル（LLM）は、パラメータの説明を使用して、ユーザーの質問からパラメータとその値を識別します。たとえば、num_enrollments は有効なパラメータ名ですが、number of student enrollments from ages 5-14 はクエリに関するコンテキストをより多く提供するパラメータの説明です。
• 一貫性のあるデータ型を確保する。SQL クエリで想定されるデータ型が、ユーザーの質問から抽出される可能性のあるデータ型と一致していることを確認します。
• 明確に定義されたスコープを提供する。クエリの構造が複雑な場合や、ロジックが直感的でない場合は、一般的で重要な質問パターンのテンプレートを作成します。これにより、LLM は最適な結果を返すことができます。
• 徹底的にテストする。さまざまな自然言語の表現でテストして、パラメータが正しく抽出されることを確認します。

パラメータ化された検証済みクエリを作成する

システムによって生成されたリストから検証済みのクエリを選択することも、独自のクエリを作成することもできます。

クエリを作成または変更する前に、自然言語パターンと質問を考慮してクエリの下書きを作成します。たとえば、「米国東部倉庫の有機バナナの総在庫はわかりますか？」という質問は、「@region 倉庫の @product の総在庫は？」というパラメータ化された検証済みクエリに書き換えることができます。エージェントは、この質問を SQL クエリに変換します。このクエリは、デフォルト値で更新します。

データ エージェントのパラメータ化された検証済みクエリを作成するには、新しいエージェントを作成するときに新しいクエリを作成するか、新しいエージェントまたは既存のエージェントの既存の検証済みクエリを編集します。

次の手順では、検証済みのサンプルクエリを使用してパラメータを構成します。

Gemini から提案された既存の検証済みクエリを選択する

1. 新しいエージェントまたは既存のエージェントの [検証済みクエリ] セクションで、[候補の確認] をクリックします。[提案された検証済みクエリを確認する] ページが開きます。
2. 提案された検証済みクエリの横にあるチェックボックスをオンにします。
3. クエリ ウィンドウで、keyboard_arrow_down [もっと見る] をクリックして、クエリの説明を開きます。
4. 既存のクエリを開くには、[編集] をクリックします。
5. クエリの構成を完了するには、検証済みクエリのパラメータを構成するをご覧ください。

エージェントを作成してから、検証済みクエリを作成する

1. 最初の手順を確認し、残りの構成手順を検証済みクエリまで進めます。
2. Cloud de Confiance コンソールで、新しいエージェントの [検証済みクエリ] セクションの [クエリを追加] をクリックします。[検証済みクエリの追加] ページが開きます。
3. クエリの構成を完了するには、検証済みクエリのパラメータを構成するをご覧ください。

検証済みクエリのパラメータを構成する

1. [質問] フィールドに、検証済みクエリで回答するユーザーからの質問を入力します。
2. パラメータを指定するには、@ 記号の後にパラメータ名を続けます。この構文は、ユーザーの質問から値を取り込むプレースホルダを識別します。ユーザーの質問でパラメータがどのように使用されるかを示す自然言語の質問を使用します。例: 「@region の倉庫にある @product の合計在庫数は？」

3. [SQL を生成] をクリックします。SQL は次の例のようになります。

      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   

4. クエリのプレースホルダにデフォルト値を追加するには、[クエリ パラメータを管理] をクリックし、[クエリ パラメータを追加] をクリックします。

5. 最初のパラメータには、[名前]、[タイプ]、[値]、[説明] の 4 つのフィールドが表示されます。

   • [名前] に、質問から @product をコピーしてこのフィールドに貼り付けます。
   • [タイプ] で [STRING] を選択します。
   • [値] に「organic bananas」と入力します。
   • [説明] に、できるだけ具体的な説明を入力します。たとえば、地域別の倉庫に保管されている商品などです。

6. 2 つ目のパラメータで、[クエリ パラメータを追加] をクリックします。

   • [名前] に、質問から @region をコピーしてこのフィールドに貼り付けます。
   • [タイプ] で [STRING] を選択します。
   • [値] に「US-EAST」と入力します。
   • [説明] に、できるだけ具体的な説明を入力します（例: a regional warehouse where products are located.）。

7. 両方のパラメータのフィールドに入力したら、[保存] をクリックします。

パラメータ化された検証済みクエリをテストする

1. [実行] をクリックし、クエリが想定どおりの結果を返すことを確認します。
2. 後の画面でユーザーのクエリをテストするには、質問フィールド全体をコピーします。
3. [保存] をクリックして [クエリを追加] 画面を終了し、エージェントの [編集] ページに戻ります。
4. エージェントの [編集] ページで、前にコピーした質問フィールドを [プレビュー] ウィンドウに貼り付けます。
   1. @product 変数を organic bananas に置き換えます。
   2. @region 変数を US-EAST に置き換えます。
5. Enter キーを押します。結果を確認してみましょう。この場合、有効な回答は US-EAST リージョンのバナナの合計在庫数（1,000 など）です。
6. 追加の検証済みクエリを作成または編集するには、必要に応じて上記の手順を繰り返します。

クエリを保存すると、ユーザーは「US-EAST 倉庫のオーガニック バナナの合計在庫はわかりますか？」という質問をすることができます。会話分析は次の処理を行います。

1. この質問をパターンに一致させます。
2. 質問から @product パラメータを @product = "organic bananas"、@region パラメータを "US-EAST" として抽出します。
3. クエリ SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST'; を実行します。
4. 計算された total_stock を返します。

用語集の用語を作成または確認する

エージェントにローカルな BigQuery カスタム用語集の用語を作成したり、Knowledge Catalog からインポートされたビジネス用語集の用語を確認して、エージェント用に選択したナレッジソースに適用できます。

• Knowledge Catalog のビジネス用語集の用語は BigQuery リソースにグローバルに適用されるため、Knowledge Catalog を使用する場合は、個々のエージェントではなく Knowledge Catalog でビジネス用語集の用語を作成して管理します。
• Knowledge Catalog からインポートしたビジネス用語集の用語を変更する必要がある場合は、Knowledge Catalog で編集し、BigQuery に戻って確認する必要があります。
• BigQuery のカスタム用語集の用語は BigQuery に残ります。Knowledge Catalog には表示されない。
• Knowledge Catalog を使用していない場合は、特定のエージェントで定義する必要がある用語に対して、BigQuery カスタム用語集の用語を作成できます。

エージェントのカスタム用語集を作成する手順は次のとおりです。

1. エージェントの [エディタ] ページの [用語集] セクションで、[用語を追加] をクリックします。
2. [カスタム規約] セクションでは、既存のカスタム規約を編集または削除できます。
3. 1 つ以上の新しい用語を作成するには、[用語を作成] をクリックします。
   1. [用語]、[定義]、1 つ以上の [類義語] をカンマで区切って入力します。
   2. [Add] をクリックして、用語を作成します。
   3. 新しい用語を削除する場合は、[削除] をクリックします。
4. カスタム用語をさらに作成するには、上記の手順を繰り返します。

Knowledge Catalog からインポートされたビジネス用語集の用語を表示する手順は次のとおりです。

1. エージェントの [エディタ] ページの [用語集] セクションで、[用語を追加] をクリックします。
2. [Dataplex からインポート] というページ セクションに移動します。
3. Knowledge Catalog でインポートされた用語を変更するには、[Dataplex の用語集に移動] をクリックします。
4. Knowledge Catalog で用語を変更したら、エージェントの [エディタ] ページに戻って、変更された用語を確認できます。

構成の設定

[設定] セクションでは、次のオプション設定を構成できます。

1. [モデル] セクションで、エージェントとの会話でユーザーが利用できるモデルのタイプを選択します。デフォルトでは、プレビュー版と一般提供版の両方のモデルを使用できます。プレビュー版のモデルは、グローバル エンドポイントを使用する場合があります。

2. ラベルを作成して、Cloud de Confiance by S3NS リソースを整理します。ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Cloud de Confiance by S3NS リソースと組み合わせてグループ化できる Key-Value ペアです。

   1. [設定] セクションで [ラベルを管理] をクリックします。
   2. [ラベルを追加] をクリックします。
   3. [キー] フィールドと [値] フィールドに、ラベルの Key-Value ペアを入力します。
   4. ラベルをさらに追加する場合は、[ラベルを追加] をもう一度クリックします。
   5. ラベルを削除するには、[削除] をクリックします。
   6. 選択が完了したら、[追加] をクリックします。新しいエージェント ページが再度開きます。

3. データ エージェントによって処理されるクエリのサイズ上限を設定します。[設定] セクションの [課金される最大バイト数] フィールドに値を入力します。この上限は 10485760 以上に設定する必要があります。そうしないと、次のエラー メッセージが表示されます。

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

値を指定しない場合、maximum bytes billed はデフォルトでプロジェクトの 1 日あたりのクエリ使用量の割り当てに設定されます。カスタム割り当てを指定していない限り、1 日あたりの使用量の割り当ては無制限です。

次のセクションに進み、エージェントをドラフト モードにするか、エージェントを公開します。

エージェントをプレビューして公開する

1. [プレビュー] セクションの [質問する] フィールドにユーザーからの質問の例を入力し、Enter キーを押します。データ エージェントが想定どおりのデータを返すことを確認するには、エージェントの回答を確認します。回答が適切でない場合は、[エディタ] セクションで設定を変更して、満足のいく回答が得られるまでデータ エージェントの構成を調整します。エージェントのテストと修正を反復することで、エージェントの結果を改善できます。

2. [保存] をクリックします。

3. データ エージェントを下書きモードにして後で再編集できるようにするには、arrow_back [戻る] をクリックして [エージェント カタログ] ページに戻ります。エージェントが下書きモードになったため、[エージェント カタログ] タブの [下書きエージェント] セクションに表示されます。

   エージェントを公開するには、エージェント作成ページに留まり、次のステップに進みます。

4. [公開] をクリックして [公開チャネル] ペインを開き、データ エージェントを公開して、プロジェクトで使用できるようにします。

5. 省略可: [エージェントが公開されました] ダイアログで [共有] をクリックして、データ エージェントを他のユーザーと共有します。

   1. [共有権限] ペインで、[プリンシパルを追加] をクリックします。

   2. [新しいプリンシパル] フィールドに、1 つ以上のプリンシパルを入力します。

   3. [ロールを選択] リストをクリックします。

   4. [ロール] リストで、次のいずれかのロールを選択します。

      • Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。
      • Gemini データ分析データ エージェント編集者（roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。
      • Gemini Data Analytics Data Agent Viewer（roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。

6. [保存] をクリックします。

7. 新しいエージェント ページに戻るには、[閉じる] をクリックします。エージェントを保存または公開すると、すぐにエージェント カタログに表示されます。

BigQuery Studio またはデータポータルを使用して、データ エージェントとの会話を作成できます。また、Conversational Analytics API を使用して、データ エージェントとチャットする独自のインターフェースを構築することもできます。データポータルへの公開については、データポータルでデータ エージェントを公開するをご覧ください。Gemini Enterprise への公開については、Gemini Enterprise でデータ エージェントを公開するをご覧ください。

データ エージェントを管理する

既存のエージェントは [エージェント カタログ] タブで確認できます。このタブは次の 3 つのセクションで構成されています。

• エージェント: 作成して公開したすべてのエージェントのリスト。公開したエージェントは、変更して他のユーザーと共有できます。
• 下書きのエージェント: まだ公開していないエージェント。下書きエージェントは共有できません。
• 組織内の他のユーザーが共有: 他のユーザーが作成して共有したエージェント。他のユーザーから権限を付与されている場合は、これらの共有エージェントを編集できます。

データ エージェントを編集する

データ エージェントを編集する手順は次のとおりです。

1. BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [エージェント カタログ] タブを選択します。

3. 変更するデータ エージェントのエージェント カードを見つけます。

4. エージェント エディタでデータ エージェントを開くには、more_vert [アクションを開く] > エージェント カードで [編集] をクリックします。

5. 必要に応じてデータ エージェントの構成を編集します。

6. 変更を公開せずに保存するには、[保存] をクリックします。

7. 変更を公開するには、[公開] をクリックします。[共有] ダイアログで、エージェントを他のユーザーと共有するか、[キャンセル] をクリックします。

8. [エージェント] ペインに戻るには、arrow_back [戻る] をクリックします。

   

データ エージェントを共有する

公開されたデータ エージェントを共有する手順は次のとおりです。下書きエージェントは共有できません。

1. BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [エージェント カタログ] タブを選択します。

3. 変更するデータ エージェントのエージェント カードを見つけます。

4. エージェント エディタでデータ エージェントを開くには、more_vert [アクションを開く] > エージェント カードの [編集] をクリックします。

5. データ エージェントを他のユーザーと共有するには、[共有] をクリックします。

6. [共有権限] ペインで、[プリンシパルを追加] をクリックします。

7. [新しいプリンシパル] フィールドに、1 つ以上のプリンシパルを入力します。

8. [ロールを選択] リストをクリックします。

9. [ロール] リストで、次のいずれかのロールを選択します。

   • Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。
   • Gemini データ分析データ エージェント編集者（roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。
   • Gemini データ分析 Data Agent Viewer（roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。

10. [保存] をクリックします。

11. エージェントの編集ページに戻るには、[閉じる] をクリックします。

12. [エージェント] ペインに戻るには、arrow_back [戻る] をクリックします。

    

データ エージェントを削除する

1. BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [エージェント カタログ] タブを選択します。

3. [エージェント カタログ] タブの [自分のエージェント] セクションまたは [自分のドラフト エージェント] セクションで、削除するデータ エージェントのエージェント カードを見つけます。

4. more_vert [アクションを開く] > [削除] をクリックします。

5. [エージェントを削除しますか？] ダイアログで、[削除] をクリックします。

データポータルでデータ エージェントを公開する

エージェントを公開してデータポータル ユーザーと共有すると、エージェントはデータポータルの [データとチャットする] ページに自動的に表示され、ユーザーはエージェントとチャットできるようになります。

エージェントを作成してデータポータルに公開する

データアナリストは、次の手順でエージェントを作成、編集、公開してデータポータルに接続できます。

1. BigQuery でデータ エージェントを作成または編集します。
2. エージェントを公開します。エージェントを公開するときに、公開オプションとして [データポータル] を選択します。
3. 手順に沿ってエージェントを共有し、データポータル ユーザーに適切な Identity and Access Management ロールを付与します。

エージェントをデータポータルのユーザーと共有する

データポータルでエージェントとの会話を開くリンクをコピーして、データポータル ユーザーとエージェントを直接共有できます。また、エージェントにアクセスできることをユーザーに通知するメールを送信することもできます。

エージェントへの直接リンクを共有するには、次の方法でエージェント専用の URL をコピーします。

• エージェント カタログから: more_vert [アクションを開く] > [リンクをコピー] > [データポータル] を選択します。
• エージェントの詳細ビューで、content_copy [エージェントのリンクをコピー] > [データポータル] を選択します。
• [共有] オーバーフロー メニューから、[データポータルのエージェントへのリンクをコピー] を選択します。
• [共有権限] パネルで [保存] をクリックした後、[リンクをコピー] を選択します。

エージェントへのアクセス権を付与したことを受信者に通知するメール通知を送信するには、[権限を共有] パネルで [メールを送信] を選択します。メール通知は、その編集セッションでエージェントを共有したユーザーまたはグループにのみ送信されます。グループのすべてのメンバーにメール通知が届きます。特定のユーザーがエージェントに対するエージェント レベルの権限をすでに持っている場合でも同様です。メールには、エージェントを共有したユーザーの名前、エージェントの名前、データポータルでエージェントを開くためのリンクが含まれています。

Gemini Enterprise でデータ エージェントを公開する

BigQuery データ エージェントを Gemini Enterprise で公開すると、ビジネス ユーザーは Gemini Enterprise 内で直接、自然言語を使用してデータのクエリと分析を行うことができます。このプロセスでは通常、データ アナリスト、Gemini Enterprise 管理者、ビジネス ユーザーが連携します。これらのユーザーに必要なロールの詳細については、必要なロールをご覧ください。

Gemini Enterprise でデータ エージェントを公開する手順は次のとおりです。

1. 前提条件を確認してください。
2. BigQuery でデータ エージェントを作成して公開します。
3. Gemini Enterprise でエージェントをプロビジョニングします。
4. エージェントを検索してチャットします。

前提条件を確認

BigQuery 会話分析エージェントを公開するには、Agent Registry を使用することをおすすめします。このセクションの前提条件に沿って、Gemini Enterprise でエージェントが検出可能であることを確認してください。

または、A2A カード JSON を使用してエージェントを公開することもできます。この方法を使用する場合は、BigQuery でデータ エージェントを作成して公開するをご覧ください。

Agent Registry を使用するには、まず適切なリージョン マッピングで Agent Gateway を構成する必要があります。BigQuery データ エージェントのストレージ リージョンと、Gemini Enterprise の Agent Gateway レジストリ バインディングが一致している必要があります。

エージェントのストレージ リージョンは、BigQuery ウェブ UI のエージェント エディタの [リージョン] セクションで構成します。エージェントの保存後にリージョンを変更することはできません。

次の図は、Agent Gateway で使用可能なリージョン オプションを示しています。

Gemini Enterprise 管理者は、次の手順で Gemini Enterprise アプリケーションの Agent Gateway を構成します。

1. データ エージェントのリージョンと一致する Agent Registry バインディングを含む Agent Gateway を設定します。オプションには、米国、EU、グローバルがあります。
2. Gemini Enterprise でアプリケーションを開き、[セキュリティ] > [構成] に移動して、[Agent Gateway の構成] セクションにゲートウェイ リソース名を入力します。詳細な手順については、Agent Gateway を介して Gemini Enterprise トラフィックを転送するをご覧ください。

BigQuery でデータ エージェントを作成して公開する

データアナリストは、次の手順で BigQuery でエージェントを作成、構成、公開します。

1. BigQuery で、データ エージェントを作成または編集します。
2. [リージョン] セクションで、ストレージ リージョンがデータソースと Agent Gateway の構成と一致していることを確認します。オプションには、US、EU、Global があります。
3. [公開] をクリックします。エージェントが以前に公開されている場合は、[アップデートを公開] をクリックします。
4. [チャンネルの公開] ペインの [その他のチャンネル] で、公開方法を選択します。
   • BigQuery と Gemini Enterprise が同じプロジェクトにある場合は、[エージェント レジストリ] セクションで、[このエージェントを登録する] チェックボックスをオンにします。
     • エージェントをレジストリから削除する場合は、[登録解除] をクリックします。
   • BigQuery と Gemini Enterprise が異なるプロジェクトにある場合は、[A2A（Agent2Agent）を介して統合] セクションで [JSON をコピー] をクリックして A2A エンドポイントの JSON データをコピーし、Gemini Enterprise 管理者と共有します。この JSON データは、Gemini Enterprise でエージェントをプロビジョニングするセクションで使用します。
5. [公開] または [更新を公開] をクリックします。
6. アクセスが必要なユーザーやグループとエージェントを共有し、Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser）ロールを付与します。

Gemini Enterprise でエージェントをプロビジョニングする

Gemini Enterprise 管理者は、次のいずれかの方法で、アプリケーションのユーザーがデータ エージェントを利用できるようにします。

オプション 1: Agent Registry からインポートする

登録済みエージェントをインポートする手順は次のとおりです。

1. Gemini Enterprise が BigQuery プロジェクトとは異なるプロジェクトにある場合は、次の手順に沿って、Agent Registry にエージェントを手動で登録します。それ以外の場合は、この手順をスキップします。
   1. Cloud de Confiance コンソールで、Gemini Enterprise と同じプロジェクトの [Agent Registry] に移動し、[エージェント] タブを選択して、[エージェントを追加] をクリックします。
   2. [エージェントの詳細] ペインの [タイプ] で、[A2A] を選択します。
   3. [リージョン] で、データ エージェントと Agent Gateway の構成に一致するリージョンを選択します。
   4. [JSON を貼り付け] を選択し、BigQuery から A2A エンドポイントの JSON データを貼り付けて、[保存] をクリックします。
2. Gemini Enterprise で、エージェントを追加するアプリの名前をクリックします。
3. ナビゲーション メニューで [エージェント] をクリック > add [エージェントを追加] をクリックします。
4. [エージェント タイプの選択] ペインで、[Agent Registry のエージェント] を見つけて [追加] をクリックします。
5. [エージェントを追加] ペインで、エージェント名、エージェント レジストリ ID、タイプ、プロデューサー、ユースケースでエージェントを検索するか、リストでエージェント カードを見つけます。
6. エージェント カードで [エージェントを追加] をクリックします。
7. [エージェントの詳細を確認する] ステップで、エージェントの A2A カードから入力されたエージェント メタデータ（名前、説明、エージェント URL、機能、スキルなど）を確認し、[次へ] をクリックします。
8. [エージェントを認証する] ステップで、Gemini Enterprise がエージェント プロバイダに対して認証する方法を選択します。
   • Google が管理するデフォルトの認証情報: Google が OAuth 認証情報を自動的に管理します。クライアント認証情報を手動で構成したり入力したりする必要はありません。
   • カスタム OAuth: 組織でカスタム OAuth クライアント認証情報が必要な場合にのみ、このオプションを選択し、クライアント ID、クライアント シークレット、認証 URL、トークン URL を入力します。
9. [完了] をクリックします。
10. エージェントが [エージェント テーブル] に表示され、状態が [有効]、エージェント タイプが [A2A（カスタム）] になります。
11. アクセス権が必要なユーザーまたはグループとエージェントを共有します。

オプション 2: A2A カードの JSON を使用してインポートする

BigQuery と Gemini Enterprise が異なるプロジェクトにある場合は、次の手順に沿って A2A カード JSON を使用してエージェントをインポートします。

1. Gemini Enterprise で、エージェントを追加するアプリの名前をクリックします。
2. ナビゲーション メニューで、[エージェント] > add [エージェントを追加] をクリックします。
3. [エージェント タイプの選択] ペインで、[A2A によるカスタム エージェント] を見つけて [追加] をクリックします。
4. [エージェント カードの JSON] フィールドに、データ アナリストから受け取ったエージェント カードの JSON を入力します。
5. [エージェントの詳細をプレビュー] > [次へ] をクリックします。
6. [エージェントの認可] ステップで、認証方法を選択します。
   • デフォルトの Google 管理の認証情報: Google が OAuth 認証情報を自動的に管理します。クライアント ID とクライアント シークレットを手動で入力または生成する必要はありません。
   • カスタム OAuth: A2A エージェントを登録して管理するの手順に沿って、カスタム OAuth 認証情報を手動で指定する場合は、このオプションを選択します。
7. [ツールの承認] ステップで、[完了] をクリックします。
8. エージェントが [エージェント テーブル] に表示され、状態が [有効]、エージェント タイプが [A2A（カスタム）] になります。
9. アクセス権が必要なユーザーまたはグループとエージェントを共有します。

エージェントを検出して使用する

Gemini Enterprise でデータ エージェントを検出して使用するには、次のいずれかの方法を使用します。

• 手動検出: Agent Gallery でデータ エージェントを見つけて、次のいずれかの方法で使用します。
  • ギャラリーを閲覧する: エージェントを選択して、専用のチャットを開始します。
  • 直接リンク: エージェント専用の URL を使用して、特定の BigQuery データ エージェントとのセッションで Gemini Enterprise を直接開きます。
  • Directed intent: Gemini Enterprise のコアチャットで @mention（@sales_pipeline_agent など）を使用してエージェントを呼び出します。
  • シームレスなオーケストレーション: 一般的な分析に関する質問（「過去 3 か月のセールス パイプラインの傾向はどうなっていますか？」など）をすると、Gemini Enterprise はクエリを関連するデータ エージェントに自動的にルーティングします。

エージェントを検出したら、次の手順でエージェントを操作できます。

• 認証: 1 回限りの OAuth ログインを完了して、BigQuery に対して安全に認証します。
• チャット: エージェントに自然言語で質問します。リクエストはエージェントによって処理され、レスポンスはテキスト、Markdown、グラフ、テーブルとして Gemini Enterprise にストリーミングされます。
• 会話の履歴を表示する: 会話は履歴ペインに自動的に保存されます。

エージェントと会話をモニタリングする

BigQuery で Google Cloud Observability を使用すると、データ エージェントのパフォーマンス、導入、レイテンシ、費用と、その会話をモニタリングできます。エージェントのオブザーバビリティを有効にすると、次のような指標を表示できます。

• 会話で使用されたエージェントの数
• 質問したユーザーの数
• 作成された会話の数
• 最も多くの質問に回答したエージェント
• 最もよく使用されるナレッジソース
• ユーザー エンゲージメント
• 予測トークン使用量
• 1 時間あたりの回答レイテンシ

始める前に

Cloud Trace、Cloud Monitoring、Cloud Logging の各 API が有効になっていない場合は、有効にします。

API を有効にする

必要なロールと権限

エージェントのオブザーバビリティを有効にするには、プロジェクトに次の権限が必要です。

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
• cloudaicompanion.settingBindings.gibqObservabilitySettingsList
• cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
• geminidataanalytics.dataAgents.create
• geminidataanalytics.operations.get
• observability.traceScopes.create
• resourcemanager.projects.update
• serviceusage.services.enable
• serviceusage.values.test

指標、トレース、ログを使用してエージェントをモニタリングするために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• モニタリング データと構成を表示する: モニタリング閲覧者 （roles/monitoring.viewer）
• トレースを表示する: Cloud Trace ユーザー （roles/cloudtrace.user）
• ログを表示する: ログビューア （roles/logging.viewer）
• データセットとその内容を表示する: BigQuery データ閲覧者 （roles/bigquery.dataViewer）
• 管理者設定を表示する: Gemini for Google Cloud ユーザー （roles/cloudaicompanion.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

オブザーバビリティを有効にする

エージェントのオブザーバビリティはデフォルトで無効になっています。管理者は、プロジェクトまたは組織でこの機能を有効にできます。エージェントのオブザーバビリティを有効にするには、次のいずれかのオプションを選択します。

指標を表示

指標は、オブザーバビリティを有効にした後に収集されます。データはバックフィルされません。エージェントの指標を表示するには、次のいずれかのオプションを選択します。

モデルの呼び出しをデバッグする

会話ターンの操作シーケンス（モデル呼び出しやツール呼び出しなど）を可視化して、エラーやレイテンシのトラブルシューティングに役立てることができます。

1. Cloud de Confiance コンソールで、Cloud Monitoring の [Trace エクスプローラ] ページに移動します。

   Trace エクスプローラに移動

2. スパンをクリックして調べます。

3. [詳細] ペインの情報を確認します。

4. 省略可: カスタム トレース ダッシュボードを作成します。

トレースを保持する

Cloud Trace データは、オブザーバビリティ データセットに 30 日間保存されます。トレースデータを長期間保存するには、トレースデータを BigQuery データセットに移動します。

必要なロール

リンクされたデータセットを作成してライブ トレースを BigQuery に公開するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• Cloud Trace 管理者 （roles/cloudtrace.admin）
• オブザーバビリティ編集者 （roles/observability.editor）
• BigQuery ユーザー（roles/bigquery.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

トレースデータを BigQuery に移動する

トレースデータを保持するには、次の操作を行います。

1. Cloud Shell を開きます。

2. _Trace バケットのロケーションを確認します。

   gcloud beta observability buckets list --location=-

   次のステップで使用するため、_Trace バケットのロケーションをメモしておきます。

3. _Trace バケットを指すリンクされたデータセットを BigQuery プロジェクトに作成します。

   gcloud beta observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID

   次のように置き換えます。

   • PROJECT_ID: プロジェクト ID
   • LOCATION: 前のステップで取得した _Trace バケットのロケーション
   • LINK_NAME: リンクされたデータセットの名前

4. 履歴トレースを保存する標準データセットを作成します。次のコマンドは、デフォルトのパーティションの有効期限を 90 日（7,776,000 秒）に設定します。

   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET

   STORAGE_DATASET は、データセットの名前に置き換えます。

5. リンクされたデータセットと同じスキーマを使用して、ストレージ データセットに空のパーティション分割テーブルを作成します。日付でパーティショニングすると、データの保持とクエリ費用を管理できます。テーブルを作成するには、SQL エディタで次のクエリを実行します。

   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;

   TABLE_NAME は、テーブルの名前に置き換えます。

6. スケジュールされたクエリを作成して、リンクされたデータセットからアーカイブ テーブルに日次のトレースデータをコピーします。次のクエリは、前日のデータをコピーします。

   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

詳細については、トレースを検索して調査する方法をご覧ください。

オブザーバビリティをオフにする

データ エージェントのオブザーバビリティをオフにするには、オブザーバビリティ設定を更新します。

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

次のように置き換えます。

• SETTING_NAME: オブザーバビリティを有効にするために作成したオブザーバビリティ設定の名前。 Cloud de Confiance コンソールを使用してオブザーバビリティを有効にした場合、設定名は default です。
• PROJECT_ID: プロジェクト ID。

次のステップ

• BigQuery の会話型分析について詳細を確認する。
• Conversational Analytics API について詳細を確認する。
• 会話でデータを分析する。
• Gemini データ分析 Data Agent Viewer（roles/geminidataanalytics.dataAgentViewer）ロールでデータ エージェントを表示する権限を付与する方法の詳細。