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