このページは Cloud Translation API によって翻訳されました。

データ分析情報エージェントで分析情報を取得する

Data Insights エージェントは、Google 製のエージェントです。BigQuery データからデータ分析情報を取得できます。Data Insights エージェントを使用すると、SQL の事前知識は必要ありません。これにより、データに基づいた十分な情報に基づくビジネス上の意思決定が可能になり、データアナリストはより複雑なタスクに集中できます。

このページでは、 Google Cloud プロジェクト管理者が Google Cloud コンソールと REST API を使用して Data Insights エージェントを承認、作成、デプロイする方法について説明します。このページでは、エンドユーザーがエージェントを使用する方法についても説明します。

概要

Data Insights エージェントは、次の処理を行うように設計されています。

ユーザーの意図を理解する: 接続されたデータソースのコンテキストとユーザーの自然言語クエリを分析して、ユーザーの目標を理解します。
SQL を生成する: この理解に基づいて、ユーザーの質問を構文的にも意味的にも正しい SQL クエリに変換します。
データを取得する: 生成された SQL を実行して、接続されたデータソース（BigQuery データセット）から関連データを直接取得します。
分析情報を提供する: 取得したデータをグラフや表などの可視化された形式で表示したり、テキストベースの要約として表示したりして、ユーザーのクエリに回答します。

データ分析エージェントに送信できるクエリの例

Data Insights エージェントに質問できるクエリの例を次に示します。

データの集計と可視化:
- 「今年の中南米地域の第 2 四半期の売上は、昨年の第 2 四半期と比較してどうでしたか？」
- 「この地域のアクセス数上位 5 か国の比較を示す棒グラフを作成して。」
傾向分析:
- 「過去 6 か月間の発信通話の件数は、地域別にどのように変化しましたか？」
- 「リスボンの 3 つ星以上のホテルの予約パターンを分析して」
データマイニング:
- 「顧客が購入したときの合計販売額と相関関係がある要因はどれですか？関係を示すヒートマップを作成して。」
分析とレポート:
- 「商談とアカウントの表を要約し、主な傾向を強調した短いレポートを作成してください。」

始める前に

Gemini Enterprise で Data Insights エージェントの使用を開始する手順は次のとおりです。

Gemini Enterprise を使ってみるの手順に沿って操作します。
Gemini Enterprise のライセンスを取得する手順に沿って操作します。
Data Insights エージェントにアクセスするには、Google アカウントマネージャーにお問い合わせください。
BigQuery データを準備します。詳細については、BigQuery のドキュメントをご覧ください。
エージェントを最大限に活用するには、BigQuery データセット内のデータを理解します。

BigQuery データへのアクセス権を付与する

Data Insights エージェントが BigQuery データを表示してクエリを実行できるようにするには、エージェントのユーザーに Identity and Access Management（IAM）ロールを付与します。

ワークフロー

Data Insights エージェントを設定して使用する全体的なワークフローは次のとおりです。

認可の詳細を取得します。
Google Cloud コンソールまたは REST API を使用してエージェントを設定します。
ユーザーとその権限を追加または変更する
エージェントインスタンスの動作状態を変更する
エージェントを使用する

承認の詳細を取得する

承認を設定する手順は次のとおりです。取得した詳細は、Data Insights エージェントが BigQuery データに接続することを承認するために必要です。

Google Cloud コンソールで、[API とサービス] の [認証情報] ページに移動します。

[認証情報] に移動
エージェントにクエリを実行させる BigQuery データセットを含む Google Cloud プロジェクトを選択します。
[認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
[アプリケーションの種類] で [ウェブアプリケーション] を選択します。
[承認済みのリダイレクト URI] セクションに、次の URI を追加します。
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
[作成] をクリックします。
[OAuth クライアントを作成しました] パネルで、[JSON をダウンロード] をクリックします。ダウンロードした JSON には、選択したGoogle Cloud プロジェクトの次の詳細が含まれます。認可リソースを作成するには、次の情報が必要です。
- Client ID: CLIENT_ID
- 承認 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%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
- トークン URI: TOKEN_URI
- クライアントシークレット: CLIENT_SECRET

Google Cloud コンソールを使用してエージェントを設定する

このセクションでは、 Google Cloud コンソールを使用して Data Insights エージェントのインスタンスを承認、作成、デプロイする方法について説明します。作成したエージェントにアクセスできるユーザーを決定するユーザー権限を追加することもできます。

エージェントインスタンスを承認して作成する

次の手順で、Data Insights エージェントインスタンスを承認して作成します。

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

Gemini Enterprise に移動
エージェントを作成するアプリを選択します。
メニューで [エージェント] をクリックします。

[エージェント] ページに、既存のエージェントが表示されます。
[エージェントを追加] をクリックします。
[エージェントを作成] ペインで、[データエージェント] カードの [作成] をクリックします。
[承認] で、[承認を追加] をクリックして、承認の詳細を入力します。詳細については、承認を取得するをご覧ください。
[完了] をクリックします。
[次へ] をクリックします。
エージェントを次のように構成します。
1. エージェントの名前と説明を入力します。
2. [BigQuery データセット] で、[参照] をクリックし、次のいずれかを行います。
  - 使用可能なデータセットを選択し、[選択] をクリックします。
  - 必要な BigQuery データセットのパスを入力し、[検索] をクリックして選択し、[選択] を選択します。
3. 省略可: 詳細オプションを表示するには、[詳細を表示] をクリックします。
4. 正しいテーブルアクセスオプションを選択します。許可リストまたはブロックリストを適用する場合は、制限付きテーブルのパスを指定します。
5. 省略可: 自然言語クエリ構成を定義して、自然言語から SQL または Python コードへの変換に固有のカスタマイズを指定します。自然言語クエリ、想定される SQL 出力、想定されるレスポンスを使用して SQL の例を指定することもできます。これにより、エージェントの出力の品質が向上します。
  - スキーマの説明: BigQuery データセットのスキーマを説明する自然言語の文字列。
  - 自然言語クエリを SQL に変換するプロンプト: 自然言語のクエリが SQL 命令に変換されます。
  - 自然言語クエリを Python に変換するプロンプト: 自然言語のクエリが Python の指示に変換されます。
6. 省略可: SQL クエリに変換された自然言語クエリの例を追加します。
  - クエリ: SQL クエリに変換する必要がある自然言語クエリの例。たとえば、「カリフォルニア州に在住するお客様の名前とメールアドレスを教えて」
  - Expected SQL: 自然言語クエリに対応する SQL クエリの例を示す文字列。たとえば、customers という名前の BigQuery テーブルがあるとします。この場合、想定される SQL クエリは SELECT customer_name, email FROM customers WHERE state = 'California' になります。
  - 想定されるレスポンス: 想定される SQL クエリを実行して、クエリに対する想定される回答を提供する文字列。次に例を示します。
```
Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \
```
[作成] をクリックします。

Data Insights エージェントインスタンスが [エージェント] リストに表示されます。
エージェントの操作を開始するには、[エージェントの状態] 列にインスタンスの [有効] が表示されるまで待ちます。

REST API を使用してエージェントを設定する

このセクションでは、REST API を使用して Data Insights エージェントインスタンスを承認、作成、デプロイする方法について説明します。

エージェントを承認する

管理者として、Gemini Enterprise で認可リソースを作成します。これにより、Data Insights エージェントが BigQuery データにアクセスできるようになります。

認可リソースを作成します。
REST

次のサンプルは、authorizations.create メソッドを使用して認可リソースを作成する方法を示しています。
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \ -d '{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID", "serverSideOauth2": { "clientId": "CLIENT_ID", "clientSecret": "CLIENT_SECRET", "authorizationUri": "AUTHORIZATION_URI", "tokenUri": "TOKEN_URI" } }'
次のように置き換えます。
- PROJECT_NUMBER: Google Cloud プロジェクトの番号。
- LOCATION: Google Cloud プロジェクトの場所。
- AUTHORIZATION_ID: 認可リソースを識別するために指定する必要がある ID。
- CLIENT_ID: 前の手順で取得したクライアント ID。
- CLIENT_SECRET: 前の手順で取得したクライアントシークレット。
- AUTHORIZATION_URI: 前の手順で取得した承認 URI。
- TOKEN_URI: 前の手順で取得したトークン URI。
レスポンス

次のような JSON レスポンスが返されます。AUTHORIZATION_RESOURCE_NAME をメモします。これは、Data Insights エージェントの作成に使用する必要があります。AUTHORIZATION_RESOURCE_NAME の末尾にある一意の ID は AUTHORIZATION_ID です。

{ "name": "AUTHORIZATION_RESOURCE_NAME", "serverSideOauth2": { "clientId": "CLIENT_ID", "clientSecret": "CLIENT_SECRET", "tokenUri": "TOKEN_URI", "authorizationUri": "AUTHORIZATION_URI" } }

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

Google Cloud プロジェクト管理者は、Data Insights エージェントインスタンスを作成できます。これには、エージェントを使用してクエリする BigQuery データのプロジェクト ID とデータセット ID が必要です。

REST

次のサンプルは、agents.create メソッドを使用して Data Insights エージェントインスタンスを作成する方法を示しています。このサンプルに追加できる高度なフィールドについては、エージェントの高度な構成を追加するをご覧ください。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

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

PROJECT_NUMBER: Google Cloud プロジェクトの番号。
LOCATION: Gemini Enterprise アプリのロケーション。
APP_ID: アプリの ID。
AGENT_DISPLAY_NAME: Data Insights エージェントインスタンスの名前。
AGENT_ICON_URI: エージェントのアイコンの URI を指定するオプションのフィールド。
AGENT_DESCRIPTION: エージェントの目的や BigQuery データソースの詳細を示す Data Insights エージェントインスタンスの説明。
BIGQUERY_PROJECT_ID: BigQuery データセットを含むGoogle Cloud プロジェクトのプロジェクト ID。
BIGQUERY_DATASET_ID: クエリ対象のデータを含む BigQuery データセット ID。
AUTHORIZATION_RESOURCE_NAME: 前のセクションで取得した認可リソース名。

レスポンス

次のような JSON レスポンスが返されます。AGENT_RESOURCE_NAME に注意してください。これは、Data Insights エージェントのデプロイに使用する必要があります。AGENT_RESOURCE_NAME の末尾にある一意の ID は AGENT_ID です。

{
  "name": "AGENT_RESOURCE_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "icon": {
    "uri": "AGENT_ICON_URI"
  },
  "createTime": "CREATION_TIME",
  "managedAgentDefinition": {
    "toolSettings": {
      "toolDescription": "AGENT_DISPLAY_NAME"
    },
    "deploymentInfo": {},
    "dataScienceAgentConfig": {
      "bqProjectId": "BIGQUERY_PROJECT_ID",
      "bqDatasetId": "BIGQUERY_DATASET_ID"
    }
  },
  "authorization_config": {
    "tool_authorizations" : [
      "AUTHORIZATION_RESOURCE_NAME"
    ]
  },
  "state": "CONFIGURED"
}

エージェントの高度な構成を追加する

必要に応じて nlQueryConfig フィールドを定義して、自然言語から SQL または Python コードへの変換に固有のカスタマイズを指定できます。自然言語クエリ、想定される SQL 出力、想定されるレスポンスを使用して、SQL の例を指定することもできます。これにより、エージェントの出力の品質が向上します。次のコードスニペットは、これらの詳細フィールドを構成する方法を示しています。

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

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

NL_TO_SQL_INSTRUCTIONS: 自然言語のクエリが SQL 命令に変換されたもの。
NL_TO_PYTHON_INSTRUCTIONS: 自然言語のクエリが Python の指示に変換されたもの。
EXAMPLE_NL_QUERY: SQL クエリに変換する必要がある自然言語クエリの例。（例: 「カリフォルニア州に拠点を置くお客様の名前とメールアドレスを教えて」）
EXPECTED_SQL_QUERY: 自然言語クエリに対応する SQL クエリの例を示す文字列。たとえば、customers という名前の BigQuery テーブルがあるとします。この場合、想定される SQL クエリは「SELECT customer_name, email FROM customers WHERE state = 'California'」になります。

EXPECTED_SQL_RESPONSE: クエリの想定される回答と想定される SQL クエリを提供する文字列。次に例を示します。

Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

NL_DESCRIPTION_OF_BQ_DATASET: BigQuery データセットのスキーマを説明する自然言語の文字列。

インスタンスをデプロイする

Data Insights エージェントインスタンスを作成したら、管理者はエンドユーザーが使用できるようにデプロイできます。

REST

エージェントをデプロイします。次のサンプルは、agents.deploy メソッドを使用して作成したエージェントをデプロイする方法を示しています。エージェントのデプロイは長時間実行オペレーション（LRO）です。
```
curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'
```
次のように置き換えます。
- PROJECT_NUMBER: Google Cloud プロジェクトの番号。
- AGENT_RESOURCE_NAME: 前のセクションでエージェントを作成したときに取得したエージェントリソース名。
レスポンス

次のような JSON レスポンスが返されます。LRO のステータスを取得するために使用する必要がある DEPLOY_OPERATION_NAME をメモします。
```
{
 "name": "DEPLOY_OPERATION_NAME",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.DeployAgentMetadata"
 }
}
```
デプロイオペレーションのステータスを取得します。次のサンプルは、デプロイオペレーションのステータスを取得する方法を示しています。operations.get メソッド。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"
```
DEPLOY_OPERATION_NAME は、前の手順でエージェントをデプロイしたときに取得した LRO 名に置き換えます。

レスポンスで、done フィールドの値が true の場合、デプロイは完了しています。done フィールドの値が false の場合、デプロイは進行中です。

ユーザーとその権限を追加または変更する

次の手順で、Data Insights エージェントインスタンスにプリンシパルを追加または変更し、特定の Identity and Access Management（IAM）ロールを割り当てます。

コンソール

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

Gemini Enterprise に移動
Data Insights エージェントインスタンスを含むアプリを選択します。
メニューで [エージェント] をクリックします。

[エージェント] ページに、既存のエージェントが表示されます。
ユーザーを追加または変更するエージェントをクリックします。

デフォルトでは、新しく作成されたエージェントにはユーザーが設定されていません。
[権限のあるユーザー] テーブルで、[ユーザーを追加] をクリックします。
使用可能なリストからメンバータイプを選択します。
タイプに応じてメンバーの ID を入力し、1 つ以上のロールを割り当てます。
- ユーザー、グループ、サービスアカウントの場合、メンバー文字列はメールアドレスです。
- ドメインの場合、メンバー文字列は有効なドメイン名です。
- プリンシパルの場合、メンバー文字列は有効なプリンシパルです。例: principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1
- プリンシパルセットの場合、メンバー文字列は有効なプリンシパルセットです。例: principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1
- ドメインとプリンシパルセットの場合、これらのドメインとプリンシパルセット内のすべてのユーザーの ID とグループに同じロールが割り当てられます。エージェントへの安全なアクセスを実現するには、個々のグループと制御されたドメインまたはプリンシパルセットを選択し、最小権限のロールを割り当てます。
[保存] をクリックします。

IAM ポリシーが更新され、ユーザーが権限付与されたユーザーのリストに追加されます。
割り当てられた権限を変更するには、 [アクション] をクリックして [変更] を選択し、次のいずれかを行います。
- 割り当てられたロールを変更します。
- 別のロールを追加します。
- [削除] をクリックして、ロールを削除します。ユーザーには少なくとも 1 つのロールを割り当てる必要があります。

インスタンスの動作状態を変更する

Data Insights エージェントインスタンスを作成すると、エージェントはデフォルトで有効になります。次の手順で、動作状態を [無効]、[一時停止]、[有効]、[削除済み] に変更できます。

コンソール

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

Gemini Enterprise に移動
Data Insights エージェントインスタンスを含むアプリを選択します。
メニューで [エージェント] をクリックします。

[エージェント] ページに、既存のエージェントが表示されます。
エージェントの [アクション] をクリックし、次のいずれかを選択します。
- [一時停止]: エージェントを一時的に使用できないようにします。ただし、アクセスエージェントに対する権限を持つユーザーは、引き続きエージェントを表示できます。
- 無効: エージェントを作成したユーザー以外のすべてのユーザーがエージェントを利用できないようにします。
- 有効: エージェントにアクセスする権限を持つすべてのユーザーがエージェントを利用できるようにします。
- [削除]: エージェントインスタンスを削除します。

エージェントを使用する

エージェントを使用してデータ分析情報を取得する手順は次のとおりです。

アプリ

アプリのナビゲーションメニューで、[エージェント] をクリックします。
[すべてのエージェントを表示] をクリックします。
Data Insights エージェントインスタンスを選択します。
エージェントが追加の承認を必要とする場合は、[承認] をクリックして承認の詳細を入力します。
[ファイルを追加] をクリックして、エージェントが使用する追加のデータソースとしてファイルを含めます。
[ソース] をクリックして、最も関連性の高いデータ分析情報を取得するためにエージェントが含める必要のあるソースを選択します。
質問またはプロンプトを入力し、Enter キーを押すか、[送信] をクリックします。

データ分析情報エージェントで分析情報を取得する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

データ分析エージェントに送信できるクエリの例

始める前に

BigQuery データへのアクセス権を付与する

ワークフロー

承認の詳細を取得する

Google Cloud コンソールを使用してエージェントを設定する

エージェント インスタンスを承認して作成する

REST API を使用してエージェントを設定する

エージェントを承認する

REST

レスポンス

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

REST

レスポンス

エージェントの高度な構成を追加する

インスタンスをデプロイする

REST

レスポンス

ユーザーとその権限を追加または変更する

コンソール

インスタンスの動作状態を変更する

コンソール

エージェントを使用する

アプリ

データ分析情報エージェントで分析情報を取得する

エージェントインスタンスを承認して作成する

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