会話型データ エージェントを使用すると、自然言語インターフェースを使用してデータベース データを操作できます。これらのエージェントを構築することで、ユーザーは複雑な SQL クエリを記述することなく、運用データベースから分析情報を取得できます。
大まかに言うと、データ エージェントは、ペルソナ、一連のデータソース、目的のために不可欠な一連のビジネス知識へのアクセスを組み合わせたものです。
アプリケーション デベロッパーにとって、これらのエージェントには次のようなメリットがあります。
- 高い精度: 作成されたコンテキストを使用することで、特定のビジネス上の質問に対して高い精度を実現できます。作成されたコンテキストは、エージェント作成者が精度を高めるために使用できる主な要素です。これには、スキーマの説明、システム指示、想定されるデータベース クエリに関する追加情報を提供する構造化されたコンテキストが含まれます。
- 複雑さの軽減: エージェントは、自然言語を SQL クエリ、実行、さらにはデータの要約や可視化に変換します。
- 柔軟性: 個人テスト用のエージェントを作成することも、公開してプロジェクト内の他のユーザーが利用できるようにすることも、API を使用してプログラムで利用できるようにすることもできます。
始める前に
-
Cloud SQL、Data Analytics API with Gemini、Gemini for Google Cloud APIs を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。
必要なロール
データ エージェントを操作するには、ユースケースに一致する IAM 権限が必要です。次の表に、エージェントの作成と公開、Gemini Enterprise でのエージェントのプロビジョニング、エージェントの検出と使用のいずれを行うかに基づいて、必要なロールを示します。詳細については、Conversational Analytics API の Identity and Access Management ロールをご覧ください。
| ユースケース | 必要なロール |
|---|---|
| エージェントの作成、編集、公開、共有、削除 |
|
| Gemini Enterprise でエージェントをプロビジョニングする |
公開されたエージェントを Gemini Enterprise のユーザーが利用できるようにするには、Gemini Enterprise 管理コンソールで A2A エージェントを登録して管理する権限が必要です。 |
| エージェントを見つけて使用する |
|
Cloud SQL for MySQL データベース リソースへのアクセスを管理する場合は、次の権限レイヤを考慮してください。
- Google Cloud IAM: クラウド リソースとしてデータベース インスタンスへのアクセスを制御します。これには、
executeSql権限を使用して接続、インスタンスの管理、SQL クエリの実行を行う権限が含まれます。 - データベース権限: テーブル、ビュー、スキーマなどのデータベース内のオブジェクトへのアクセスを制御します。これらは、
GRANTなどの SQL コマンドと、データベース固有のユーザーとロールのシステムを使用して管理されます。
Cloud SQL for MySQL の場合、インスタンスに接続してクエリを送信する権限を付与するには、適切な Cloud SQL IAM ロールが必要です。テーブルやビューなどのオブジェクトを操作するには、接続するデータベース ユーザーに、Cloud SQL for MySQL GRANT システムを使用して必要な権限が付与されている必要があります。詳細については、Cloud SQL for MySQL ユーザーについてをご覧ください。エージェントがサービス アカウントを使用している場合は、データベース ロールを割り当てることができます。たとえば、IAM データベース認証でユーザーを管理するをご覧ください。
データ エージェントを作成する
以降のセクションでは、データ エージェントを作成する方法について説明します。エージェントを作成したら、設定を編集できます。
基本の構成
Google Cloud コンソールで、Cloud SQL for MySQL ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで [エージェント] をクリックします。
[エージェント] タブをクリックします。
データベースを選択し、IAM アカウントを使用してログインします。
[新しいエージェント] をクリックします。[新しいエージェント] ページが開きます。
[エディタ] セクションの [エージェント名] フィールドに、データ エージェントのわかりやすい名前（
Q4 sales dataやUser activity logsなど）を入力します。[エージェントの説明] フィールドに、データ エージェントの説明を入力します。適切な説明を付けておくと、エージェントの動作や使用するデータがわかり、会話に使用するデータ エージェントとして適切かどうかを判断する際に役立ちます（例:
What are the top 10 selling products in Q2?）。[ナレッジ ソース] セクションで、[ソースを追加] をクリックします。[データを追加] ページが開きます。
エージェントが質問に回答する際に焦点を当てるテーブルを選択します。他のナレッジソースを表示するには、 [さらに表示] を選択します。
[追加] をクリックします。新しいエージェント ページが再度開きます。
テーブルとフィールドの説明をカスタマイズする
会話型データ エージェントの精度を高めるために、必要に応じて追加のテーブル メタデータを提供できます。このメタデータはデータ エージェントによってのみ使用されるもので、ソーステーブルには影響しません。次のメタデータを追加できます。
- スキーマの説明: エージェントがデータを理解できるように、テーブルと列の説明を追加します。説明を追加しない場合、エージェントはデータ定義のスキーマの説明を使用します。
テーブルとフィールドの説明を追加する際は、次のベスト プラクティスに従ってください。
- データ エージェントの定義だけでなく、データ定義にも説明を追加します。これにより、他のエージェントも説明のメリットを享受できます。
- データ エージェントがデータを理解するのに役立つ適切な説明をプロトタイプするには、特定のエージェントに説明を追加します。説明が意図した影響を与えていることを確認したら、データ定義に説明を追加するかどうかを決定できます。
テーブルとフィールドの説明を構成する手順は次のとおりです。
- [エージェント カタログ] タブで、カスタマイズするエージェントを開きます。
- [エージェントを編集] をクリックします。
- [ナレッジ ソース] で、カスタマイズするテーブルを見つけて [カスタマイズ] をクリックします。
- テーブルの説明を入力します。
- フィールドの説明を編集するには、フィールドの横にある [編集] をクリックします。[フィールドを編集] ペインが開きます。
- [ID] フィールドに、フィールドの説明を入力します。
- フィールドの説明を保存するには、[更新] をクリックします。
- 説明とフィールドの更新を保存するには、[更新] をクリックします。新しいエージェント ページが再度開きます。
- カスタマイズするテーブルごとに、この手順を繰り返します。
データ エージェントにラベルを追加する
[エージェント設定] セクションでは、 Google Cloud リソースを整理するためのラベルを作成できます。ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Google Cloudリソースと組み合わせてグループ化できる Key-Value ペアです。
- [エージェント カタログ] タブで、ラベルを追加するエージェントを開きます。
- [エージェントを編集] をクリックします。
- [エージェントの設定] セクションで、[ラベルを追加] をクリックします。[ラベルの管理] ペインが開きます。
- [ラベルを追加] をクリックします。
- [キー] フィールドと [値] フィールドに、ラベルの Key-Value ペアを入力します。
- ラベルをさらに追加する場合は、[ラベルを追加] をもう一度クリックします。
- ラベルを削除するには、[削除] をクリックします。
- 完了したら、[追加] をクリックします。新しいエージェント ページが再度開きます。
次のセクションに進んで、エージェントをドラフト モードにするか、エージェントを公開します。
エージェントをプレビューして公開する
[プレビュー] セクションの [質問する] フィールドに質問の例を入力し、Enter キーを押します。
データ エージェントが想定どおりのデータを返したことを確認するには、エージェントのレスポンスを確認します。回答が適切でない場合は、[エディタ] セクションで設定を変更して、満足のいく回答が得られるまでデータ エージェントの構成を調整します。エージェントのテストと修正を反復することで、エージェントの結果を改善できます。
[保存] をクリックします。
データ エージェントを後で再編集できる下書きモードにするには、 [戻る] をクリックして [エージェント カタログ] ページに戻ります。エージェントが下書きモードになったため、[エージェント カタログ] タブの [マイ下書きエージェント] セクションに表示されます。
エージェントを公開するには、エージェントの作成ページで次の手順に進みます。
データ エージェントを公開してプロジェクトで使用できるようにするには、[公開] をクリックします。エージェントを公開すると、同じデータベース テーブルにアクセスできる他のユーザーが、作成した手順とコンテキストを利用して、エージェントを表示し、会話できるようになります。
データ エージェントとの会話は、 Google Cloud コンソールの [エージェント] ページを使用して作成できます。また、Conversational Analytics API を使用して、データ エージェントとチャットする独自のインターフェースを構築することもできます。
省略可: [エージェントが公開されました] ダイアログで [共有] をクリックして、データ エージェントを他のユーザーと共有します。
- [共有権限] ペインで、[プリンシパルを追加] をクリックします。
- [新しいプリンシパル] フィールドに、1 つ以上のプリンシパルを入力します。
- [ロールを選択] リストをクリックします。
- [ロール] リストで、次のいずれかのロールを選択します。
- Gemini データ分析データ エージェント ユーザー（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini データ分析データ エージェント編集者（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini データ分析データ エージェント ユーザー（
- [保存] をクリックします。
省略可: データ エージェントを Gemini Enterprise に公開できます。詳細については、Gemini Enterprise でデータ エージェントを公開するをご覧ください。
新しいエージェント ページに戻るには、[閉じる] をクリックします。エージェントを保存または公開すると、エージェント カタログに表示されます。
データ エージェントを管理する
既存のエージェントは [エージェント カタログ] タブで確認できます。このタブは次の 3 つのセクションで構成されています。
- エージェント: 作成して公開したすべてのエージェントのリスト。公開したエージェントは、変更して他のユーザーと共有できます。
- 下書きのエージェント: まだ公開していないエージェント。ドラフト エージェントを共有することはできません。
- 組織内の他のユーザーが共有: 他のユーザーが作成して共有したエージェント。他のユーザーから権限が付与されている場合は、これらの共有エージェントを編集できます。
データ エージェントを編集する
データ エージェントを編集する手順は次のとおりです。
Google Cloud コンソールで、Cloud SQL for MySQL ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで [エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して Agents にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、エージェント カードで [アクションを開く] をクリックし、[編集] をクリックします。
必要に応じて、データ エージェントの構成を編集します。
変更を公開せずに保存するには、[保存] をクリックします。
変更を公開するには、[公開] をクリックします。[共有] ダイアログで、エージェントを他のユーザーと共有するか、[キャンセル] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを共有する
公開されたデータ エージェントを共有する手順は次のとおりです。下書きエージェントは共有できません。
Google Cloud コンソールで、Cloud SQL for MySQL ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで [エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して Agents にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [アクションを開く] > エージェント カードの [編集] をクリックします。
データ エージェントを他のユーザーと共有するには、[共有] をクリックします。
[共有権限] ペインで、[プリンシパルを追加] をクリックします。
[プリンシパルの追加] フィールドに、1 つ以上のプリンシパルを入力します。
[ロールを選択] をクリックします。
[ロール] リストで、次のいずれかのロールを選択します。
- Gemini データ分析データ エージェント ユーザー（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini データ分析データ エージェント編集者（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini データ分析データ エージェント ユーザー（
[保存] をクリックします。
エージェントの編集ページに戻るには、[閉じる] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを削除する
Google Cloud コンソールで、Cloud SQL for MySQL ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで [エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して Agents にログインします。
[エージェント カタログ] タブを選択します。
[エージェント カタログ] タブの [エージェント] セクションで、削除するデータ エージェントのエージェント カードを見つけます。
[アクションを開く] > [削除] をクリックします。
[エージェントを削除しますか？] ダイアログで、[削除] をクリックします。エージェントを削除すると、プロジェクトから完全に削除されます。
エージェントを削除すると、既存の会話は表示専用モードで利用できます。削除されたエージェントに新しい質問をすることはできません。
Gemini Enterprise でデータ エージェントを公開する
データ エージェントの公開には、データ アナリスト、Gemini Enterprise 管理者、ビジネス ユーザー間のコラボレーションが必要です。これらのユーザーに必要なロールについては、必要なロールをご覧ください。
エージェントを作成して公開する
エージェントを作成、編集、公開する手順は次のとおりです。
- Cloud SQL for MySQL でデータ エージェントを作成または編集します。
- エージェントを公開します。エージェントを公開するときに、公開オプションとして [Gemini Enterprise] を選択します。
- A2A エンドポイント JSON をコピーするには、[JSON をコピー] をクリックします。
- A2A エンドポイント JSON とユーザーのリストを Gemini Enterprise 管理者と共有します。これにより、管理者は Google Cloud コンソールでカスタム エージェントを登録し、アクセス権限を構成できます。詳細については、エージェントをプロビジョニングするをご覧ください。
- アクセス権限が必要なユーザーとグループとエージェントを共有します。
エージェントをプロビジョニングする
公開したエージェントを Google Cloud コンソールのユーザーが利用できるようにする手順は次のとおりです。
Google Cloud コンソールで、[Gemini Enterprise] に移動します。
エージェントを登録するアプリの名前をクリックします。
[エージェント] > [エージェントの追加] をクリックします。
[エージェント タイプの選択] セクションで、[A2A によるカスタム エージェント] の [追加] をクリックします。
[エージェント カードの JSON] フィールドに、データ アナリストから以前に受け取ったエージェント カードの詳細を JSON 形式で入力します。
[エージェントの詳細をプレビュー] > [次へ] をクリックします。
エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにするには、次の操作を行います。
認可の詳細を構成するで生成したクライアント ID とクライアント シークレットを入力します。
[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 に置き換えます。
[トークン URI] フィールドに、次のように入力します。
https://oauth2.googleapis.com/token
[スコープ] フィールドに、次のように入力します。
https://www.googleapis.com/auth/cloud-platform
[完了] をクリックします。
ユーザーまたはグループとエージェントを共有します。
詳細については、A2A エージェントを登録して管理するをご覧ください。
エージェントを検索して使用する
Gemini Enterprise でデータ エージェントを見つけて使用するには、次のいずれかの方法を使用します。
- Agent Gallery でエージェントを見つけて、専用のチャットを開始します。
- エージェントの専用 URL を使用して、特定の Cloud SQL for MySQL データ エージェントとのセッションで Gemini Enterprise を直接開きます。
- Gemini Enterprise コアチャットで
@mention（@sales_pipeline_agentなど）を記述して、エージェントを呼び出します。 - 「過去 3 か月間の販売パイプラインの傾向はどうですか？」などの一般的な分析に関する質問をすると、Gemini Enterprise がクエリを関連するデータ エージェントに自動的に転送します。
エージェントを見つけたら、次のいずれかの方法で操作できます。
- 1 回限りの OAuth ログインを完了して、Cloud SQL for MySQL に対して安全に認証します。
- 自然言語で質問します。会話分析エージェントはリクエストを処理し、レスポンスをテキスト、マークダウン、グラフ、表として Gemini Enterprise にストリーミングします。
- 会話の履歴は、履歴ペインで確認できます。会話は自動的に保存されます。
ロケーション
会話型分析はグローバルに運用されており、使用するリージョンを選択することはできません。
次のステップ
- Cloud SQL for MySQL の会話分析について学習する。
- Conversational Analytics API について詳細を確認する。
- 会話でデータを分析する。
- Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）ロールがデータ エージェントを表示する権限を付与する方法について学習する。