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

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

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

始める前に

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

2. BigQuery、Gemini Data Analytics、Gemini for Google Cloud、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 管理コンソールで A2A エージェントを登録して管理する権限が必要です。
• エージェントを見つけて使用する:
  • データ エージェントとチャットする: 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 でナレッジソースとして使用するテーブルのデータ分析情報を生成できます。

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

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

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

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

サンプル エージェントを表示するには、次の操作を行います。

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

   [エージェント] に移動

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

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

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

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

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

注: データソースとの会話中に、その会話からエージェントを作成することもできます。

最初の手順

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

   [エージェント] に移動

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

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

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

5. [エージェントの説明] フィールドに、データ エージェントの説明を入力します。適切な説明を付けておくと、エージェントの機能や使用するデータがわかり、チャット相手とするデータ エージェントを選択する際に役立ちます（例: Ask questions about customer orders and revenue）。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注: 説明の変更が Google Cloud コンソールに反映されない場合は、list メソッドを使用して確認するか、patch メソッドを使用して説明を更新できます。

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

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

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

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

[例を表示] をクリックすると、指示の例がさらに表示されます。

情報の種類	説明	例
主なフィールド	分析に関して最も重要なフィールド。	「このテーブルで最も重要なフィールドは、[お客様 ID]、[商品 ID]、[注文日] です。」
フィルタリングとグループ化	エージェントがデータのフィルタリングとグループ化に使用するフィールド。	「質問がタイムラインや「時間の経過」に関するものである場合は、必ず order_created_date 列を使用してください。」「商品別」と指定された場合は、product_category 列でグループ化します。
デフォルトのフィルタリング	デフォルトでフィルタリングするフィールド。	「特に記載がない限り、常に order_status = 'Complete' でデータをフィルタします。」
類義語とビジネス用語	主なフィールドの代替用語。	「収益または売上について質問された場合は、total_sale_amount 列を使用します。」「購入回数が 5 回を超えるお客様を『ロイヤル』顧客とみなします。」
除外済みフィールド	データ エージェントが使用を避けるべきフィールド。	「[取得された取引日]、[取得された市区町村] のフィールドは使用しないでください。」
結合関係	2 つ以上のテーブルが互いにどのように関連付けられているか、およびどの列で結合されているか。エージェントは、列ペアに対して標準 SQL JOIN を使用してデータを結合する必要があります。例の列をご覧ください。	Customer Activity order_items.user_id = users.id （販売と顧客をリンクするため） events.user_id = users.id （ウェブサイトのアクティビティをログイン済みの顧客にリンクするため）

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

エージェントは、確認済みのクエリを次の 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. クエリ ウィンドウで [詳細を表示] をクリックして、クエリの説明を展開します。
4. 既存のクエリを開くには、[編集] をクリックします。
5. クエリの構成を完了するには、検証済みクエリのパラメータを構成するをご覧ください。

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

1. 初期手順を参照し、残りの構成手順を完了して検証済みクエリに進みます。
2. Google Cloud コンソールの新しいエージェントの [検証済みクエリ] セクションで、[クエリを追加] をクリックします。[検証済みクエリの追加] ページが開きます。
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 には表示されない。
• ナレッジ カタログを使用していない場合は、特定のエージェントで定義する必要がある用語に対して、BigQuery カスタム用語集の用語を作成できます。

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

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

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

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

構成の設定

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

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

2. Google Cloud リソースの整理に役立つラベルを作成します。ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Google Cloud リソースと組み合わせてグループ化できる 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. データ エージェントをドラフト モードにして後で再編集できるようにするには、 [戻る] をクリックして [エージェント カタログ] ページに戻ります。エージェントが下書きモードになったため、[エージェント カタログ] タブの [下書きエージェント] セクションに表示されます。

   エージェントを公開するには、エージェントの作成ページで次の手順に進みます。

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

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. 新しいエージェント ページに戻るには、[閉じる] をクリックします。エージェントを保存または公開すると、すぐに Agent Catalog に表示されます。

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

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

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

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

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

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

   [エージェント] に移動

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

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

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

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

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

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

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

   

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

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

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

   [エージェント] に移動

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

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

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

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

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

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

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

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

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

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

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

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

    

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

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

   [エージェント] に移動

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注: [投稿できるユーザー] の設定が [グループ メンバーのみ] になっている Google グループにメールを送信する場合は、グループのオーナーまたはマネージャーがグループの設定を [組織全体] に更新して、配信を有効にする必要があります。

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

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: この機能に関するフィードバックやサポートのリクエストを行う場合は、[e-mail] 宛てにメールを送信してください。

以降のセクションでは、Gemini Enterprise でデータ エージェントを公開する方法について説明します。このプロセスには通常、データ アナリスト、Gemini Enterprise 管理者、ビジネス ユーザー間のコラボレーションが含まれます。これらのユーザーに必要なロールの詳細については、必要なロールをご覧ください。

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

1. データ エージェントを作成して公開します。
2. 認可の詳細情報を構成します。
3. エージェントをプロビジョニングします。
4. エージェントを見つけて使用します。

エージェントを作成して公開する

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

1. BigQuery でデータ エージェントを作成または編集します。
2. エージェントを公開します。エージェントを公開するときに、公開オプションとして [Gemini Enterprise] を選択します。
3. A2A エンドポイントの JSON をコピーします。
4. A2A エンドポイントの JSON とユーザーのリストを Gemini Enterprise 管理者と共有します。
5. アクセス権限が必要なユーザーとグループとエージェントを共有します。

認可の詳細情報を構成する

Gemini Enterprise 管理者がエージェントをプロビジョニングする前に、ユーザーまたは管理者が認可の詳細を構成して、Google Cloud OAuth クライアント認証情報を生成する必要があります。

OAuth クライアント ID とクライアント シークレットを作成するには、認可の詳細を構成するの手順に沿って操作します。

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

Gemini Enterprise 管理者は、公開されたエージェントを Google Cloud コンソールのユーザーが利用できるようにすることができます。

1. Google Cloud コンソールで、[Gemini Enterprise] に移動します。

   Gemini Enterprise

2. エージェントを登録するアプリの名前をクリックします。

3. [エージェント] > [エージェントの追加] をクリックします。

4. [エージェント タイプの選択] セクションで、[A2A によるカスタム エージェント] の [追加] をクリックします。

5. [エージェント カードの JSON] フィールドに、データ アナリストから以前に受け取ったエージェント カード情報詳細を JSON 形式で入力します。使用可能なフィールドの完全なリストについては、Agent2Agent（A2A）プロトコルの仕様をご覧ください。この例では、必須フィールドのみを使用しています。

6. [エージェントの詳細をプレビュー] > [次へ] をクリックします。

7. エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにするには、次の操作を行います。

   1. 認可の詳細を構成するで生成したクライアント ID とクライアント シークレットを入力します。

   2. [Authorization URI] フィールドに、次のように入力します。

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      client_id は、認可の詳細を構成するセクションで生成したクライアント ID に置き換えます。

   3. [トークン URI] フィールドに、次のように入力します。

      https://oauth2.googleapis.com/token

   4. [スコープ] フィールドに、次のように入力します。

      https://www.googleapis.com/auth/cloud-platform

8. [完了] をクリックします。

9. データ アナリストが提供するユーザーまたはグループとエージェントを共有します。

Gemini Enterprise での A2A エージェントの操作の詳細については、A2A エージェントを登録して管理するをご覧ください。

エージェントを見つけて使用する

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 にストリーミングされます。
• 会話の履歴を表示する: 会話は履歴ペインに自動的に保存されます。

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

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: この機能に関するフィードバックやサポートのリクエストを行う場合は、[e-mail] 宛てにメールを送信してください。

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

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

始める前に

Cloud Trace、Cloud Monitoring、Cloud Logging API を有効にします。

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

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

API を有効にする

必要なロールと権限

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

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• 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. Google Cloud コンソールで、BigQuery の [エージェント] ページに移動します。

   [エージェント] に移動

2. [モニタリング] タブを選択します。

3. オブザーバビリティが無効になっている場合は、プロンプトに沿って有効にします。

Google Cloud CLI

1. オブザーバビリティ設定を作成します。

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

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

   • SETTING_NAME: オブザーバビリティ設定の名前。
   • PROJECT_ID: プロジェクト ID。

2. オブザーバビリティ設定をプロジェクトにバインドします。

   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID

   BINDING_NAME は、設定バインディングの名前に置き換えます。バインディング名には binding-PROJECT_ID を使用することをおすすめします。

API

1. オブザーバビリティ設定を作成します。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

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

   • SETTING_NAME: オブザーバビリティ設定の名前。
   • PROJECT_ID: プロジェクト ID。

2. オブザーバビリティ設定をプロジェクトにバインドします。

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

   BINDING_NAME は、設定バインディングの名前に置き換えます。バインディング名には binding-PROJECT_ID を使用することをおすすめします。

指標を表示

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

BigQuery

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

   [エージェント] に移動

2. [モニタリング] タブを選択します。

Cloud Monitoring

1. Google Cloud コンソールで、Cloud Monitoring の [ダッシュボード] ページに移動します。

   ダッシュボードに移動する

2. [マイ ダッシュボード] ペインで、BigQuery Conversational Analytics という名前のダッシュボードを検索します。

3. ダッシュボードを開くには、ダッシュボードの名前をクリックします。

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

5. 省略可: 指標を個別に表示するには、[Metrics Explorer] ページに移動します。

   Metrics Explorer に移動

   エージェント指標には、エージェントの使用状況、モデル呼び出し、ツールの使用状況、健全性、レイテンシ、トークン使用量が含まれます。

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

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

1. Google Cloud コンソールで、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: 可観測性を有効にするために作成した可観測性設定の名前。 Google Cloud コンソールを使用してオブザーバビリティを有効にした場合、設定名は default です。
• PROJECT_ID: プロジェクト ID。

次のステップ

• BigQuery の会話型分析について詳細を確認する。
• Conversational Analytics API について詳細を確認する。
• 会話でデータを分析する。
• Gemini データ分析データ エージェント閲覧者（roles/geminidataanalytics.dataAgentViewer）ロールでデータ エージェントを表示する権限が付与される仕組みについて確認する。