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

会話型データ エージェントを使用すると、自然言語インターフェースを使用してデータベース データを操作できます。これらのエージェントを構築することで、ユーザーは「データと対話」できるようになり、複雑な SQL クエリを記述しなくても運用データベースから分析情報を取得できます。

大まかに言うと、データ エージェントは、ペルソナと一連のデータソースを組み合わせたもので、目的を達成するために不可欠な一連のビジネス知識にアクセスできます。

アプリケーション デベロッパーにとって、これらのエージェントには次のようなメリットがあります。

  • 高精度: 作成されたコンテキストを使用することで、特定のビジネスに関する質問に対して高精度を実現できます。作成されたコンテキストは、エージェント作成者が精度を高めるために使用できる主な要因です。 これには、スキーマの説明、システム指示、予想されるデータベース クエリに関する追加情報を提供する構造化されたコンテキストが含まれます。
  • 複雑さの軽減: エージェントは、自然言語を SQL クエリ、実行、さらにはデータの要約や可視化に変換します。
  • 柔軟性: 個人テスト用のエージェントをドラフト作成することも、公開してプロジェクト内の他のユーザーが利用できるようにすることも、API を使用してプログラムで利用できるようにすることもできます。

始める前に

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

  2. Spanner、Data Analytics API with Gemini、Gemini for Google Cloud APIs. を有効にします。

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

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

    API を有効にする

必要なロール

データ エージェントを使用するには、ユースケースに一致する IAM 権限が必要です。次の表に、エージェントの作成と公開、Gemini Enterprise でのエージェントのプロビジョニング、エージェントの検出と使用のいずれを行うかに応じて必要なロールを示します。詳細については、Conversational Analytics API の Identity and Access Management ロールをご覧ください。

ユースケース 必要なロール
エージェントの作成、編集、公開、共有、削除
  • プロジェクトでデータ エージェントを作成するには: プロジェクトに対する Gemini データ分析データ エージェント作成者（roles/geminidataanalytics.dataAgentCreator）。このロールにより、作成したデータ エージェントに対する Gemini データ分析データ エージェント オーナーのロールが自動的に付与されます。
  • データ エージェントを編集、共有、削除するには: エージェントまたはプロジェクトに対する Gemini データ分析データ エージェント オーナー（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）。

Spanner リソースを操作するには、 Spanner のロールと権限をご覧ください。

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

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

基本の構成

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

    Spanner に移動

  2. リストからインスタンスを選択し、データベースを選択します。

  3. ナビゲーション メニューで、[エージェント] をクリックします。

  4. [エージェント] タブをクリックします。

  5. データベースを選択し、IAM アカウントを使用してログインします。

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

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

  8. [エージェントの説明] フィールドに、データ エージェントの説明を入力します。適切な説明は、エージェントの機能、使用するデータを示し、会話に使用する適切なデータ エージェントであるかどうかを判断するのに役立ちます（例: What are the top 10 selling products in Q2?）。

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

  10. エージェントが質問に回答する際に焦点を当てるテーブルを選択します。追加の ナレッジソースを表示するには、 [さらに表示] を選択します。

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

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

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

  • スキーマの説明: テーブルと列の説明を追加して、エージェントがデータを理解できるようにします。説明を追加しない場合、エージェントはデータ定義のスキーマの説明を使用します。

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

  • データ エージェントの定義だけでなく、データ定義にも説明を追加します。これにより、他のエージェントも説明のメリットを享受できます。
  • データ エージェントがデータを理解できるように適切な説明をプロトタイプするには、特定のエージェントに説明を追加します。説明が意図した効果をもたらすことを確認したら、データ定義に説明を追加するかどうかを決定できます。

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

  1. [エージェント カタログ] タブで、カスタマイズするエージェントを開きます。
  2. [エージェントを編集] をクリックします。
  3. [ナレッジソース] で、カスタマイズするテーブルを見つけて [カスタマイズ] をクリックします。
  4. テーブルの説明を入力します。
  5. フィールドの説明を編集するには、フィールドの横にある [編集] をクリックします。[フィールドを編集] ペインが開きます。
    1. [ID] フィールドに、フィールドの説明を入力します。
    2. フィールドの説明を保存するには、[更新] をクリックします。
  6. 説明とフィールドの更新を保存するには、[更新] をクリックします。新しいエージェント ページが再度開きます。
  7. カスタマイズするテーブルごとに、この手順を繰り返します。

データ エージェントにラベルを追加する

[Agent Settings] セクションで、 ラベルを作成してリソースを整理できます。 Google Cloud ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Google Cloud リソースと組み合わせてグループ化できる Key-Value ペアです。

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

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

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

  1. [プレビュー] セクションの [質問する] フィールドに質問の例を入力し、Enter キーを押します。

    データ エージェントが想定どおりのデータを返すことを確認するには、エージェントの回答を確認します。回答が想定どおりでない場合は、[エディタ] セクションで設定を変更して、満足のいく回答が得られるまでデータ エージェントの構成を調整します。エージェントのテストと修正を反復することで、エージェントの結果を改善できます。

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

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

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

  4. [公開] をクリックしてデータ エージェントを公開し、プロジェクトでデータ エージェントを使用できるようにします。エージェントを公開すると、同じデータベース テーブルにアクセスできる他のユーザーが、作成した手順とコンテキストを利用してエージェントを表示して会話できるようになります。

    データ エージェントとの会話は、コンソールの [エージェント] ページを使用して作成できます。 Google Cloud また、Conversational Analytics API を使用して、データ エージェントとチャットする独自のインターフェースを構築することもできます。

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

    1. [共有権限] ペインで、[プリンシパルを追加] をクリックします。
    2. [新しいプリンシパル] フィールドに、1 つ以上のプリンシパルを入力します。
    3. [ロールを選択] リストをクリックします。
    4. [ロール] リストで、次のいずれかのロールを選択します。
      • Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。
      • Gemini データ分析データ エージェント編集者（roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。
      • Gemini データ分析データ エージェント閲覧者（roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
    5. [保存] をクリックします。

  6. 省略可: データ エージェントを Gemini Enterprise に公開できます。詳細については、Gemini Enterprise でデータ エージェントを公開するをご覧ください。

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

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

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

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

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

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

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

    Spanner に移動

  2. リストからインスタンスを選択し、データベースを選択します。

  3. ナビゲーション メニューで、[エージェント] をクリックします。

  4. Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。

  5. [エージェント カタログ] タブをクリックします。

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

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

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

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

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

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

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

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

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

    Spanner に移動

  2. リストからインスタンスを選択し、データベースを選択します。

  3. ナビゲーション メニューで、[エージェント] をクリックします。

  4. Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。

  5. [エージェント カタログ] タブをクリックします。

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

  7. エージェント エディタでデータ エージェントを開くには、 [Open actions] > エージェント カードで [Edit] をクリックします。

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

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

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

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

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

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

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

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

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

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

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

    Spanner に移動

  2. リストからインスタンスを選択し、データベースを選択します。

  3. ナビゲーション メニューで、[エージェント] をクリックします。

  4. Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。

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

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

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

  8. [エージェントを削除しますか？] ダイアログで、[削除] をクリックします。エージェントを削除すると、エージェントはプロジェクトから完全に削除されます。

    エージェントを削除すると、既存の会話は表示専用モードで利用できます。 削除したエージェントに新しい質問をすることはできません。

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

データ アナリスト、Gemini Enterprise 管理者、ビジネス ユーザーが連携してデータ エージェントを公開します。これらのユーザーに必要なロールについては、必要なロールをご覧ください。

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

エージェントを作成、編集、公開する手順は次のとおりです。

  1. Spanner でデータ エージェントを作成または編集します。
  2. エージェントを公開します。エージェントを公開するときは、公開オプションとして [Gemini Enterprise] を選択します。
  3. A2A エンドポイント JSON をコピーするには、[JSON をコピー] をクリックします。
  4. A2A エンドポイント JSON とユーザーのリストを Gemini Enterprise 管理者と共有して、カスタム エージェントを Google Cloud コンソールに登録し、アクセス権を構成できるようにします。 詳細については、エージェントをプロビジョニングするをご覧ください。
  5. エージェントをアクセス権が必要なユーザーとグループと 共有します。

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

公開されたエージェントを Google Cloud コンソールのユーザーが利用できるようにする手順は次のとおりです。

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

    Gemini Enterprise

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

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

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

  5. [エージェント カードの JSON] フィールドに、データ アナリストから事前に受け取ったエージェント カード情報を JSON 形式で入力します。

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

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

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

    2. [認可 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. エージェントを共有 ユーザーまたはグループと。

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

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

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

  • Agent Gallery でエージェントを見つけて、専用のチャットを開始します。
  • エージェントの専用 URL を使用して、Gemini Enterprise を特定の Spanner データ エージェントとのセッションで直接開きます。
  • Gemini Enterprise コアチャットで @mention（@sales_pipeline_agent など）を記述してエージェントを呼び出します。
  • 「過去 3 か月間のセールス パイプラインの推移はどうですか？」などの一般的な分析に関する質問をして、Gemini Enterprise がクエリを関連するデータ エージェントに自動的にルーティングできるようにします。

エージェントを見つけたら、次のいずれかの方法で操作できます。

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

ロケーション

会話型分析はグローバルに運用されており、使用するリージョンを選択することはできません。

次のステップ