会話型データ エージェントを使用すると、自然言語インターフェースを使用してデータベース データを操作できます。これらのエージェントを構築することで、ユーザーは複雑な 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: クラウド リソースとしてデータベース インスタンスへのアクセスを制御します。これには、
executeSql権限を使用して接続、インスタンスの管理、SQL クエリの実行を行う権限が含まれます。 - データベース権限: テーブル、ビュー、スキーマなど、データベース内のオブジェクトへのアクセスを制御します。これらは、
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 が生成した候補を表示] をクリックします。
- [検証済みクエリの候補の確認] で、提案された検証済みクエリを確認します。
- ユースケースに適用されるクエリを選択します。
- [追加] をクリックして、クエリをコンテキストに追加します。
省略可。独自の検証済みクエリを作成するには、[検証済みクエリ] で [クエリを追加] をクリックします。
- [**質問**] に、検証済み クエリで回答できる質問を入力します。
- [SQL を生成] をクリックして、追加した質問に対応する検証済みクエリを Gemini に生成させます。
- [実行] をクリックし、クエリが想定どおりの結果を返すことを確認します。
- 回答を確認し、必要に応じて検証済みクエリを変更します。
- [追加] をクリックします。
この手順を繰り返して、検証済みクエリを追加します。
データ エージェントにラベルを追加する
[エージェントの設定] セクションで、 ラベルを作成してリソースを整理できます。 Google Cloud ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Google Cloud リソースと組み合わせてグループ化できる Key-Value ペアです。
- [エージェント カタログ] タブで、ラベルを追加するエージェントを開きます。
- [エージェントを編集] をクリックします。
- [エージェントの設定] セクションで、[ラベルを追加] をクリックします。[ラベルの管理] ペインが開きます。
- [ラベルを追加] をクリックします。
- [キー] フィールドと [値] フィールドに、ラベルの Key-Value ペアを入力します。
- ラベルを追加する場合は、[ラベルを追加] をもう一度クリックします。
- ラベルを削除するには、削除アイコンをクリックします。
- 完了したら、[追加] をクリックします。新しいエージェント ページが再度開きます。
次のセクションに進み、エージェントをドラフト モードにするか、エージェントを公開します。
エージェントをプレビューして公開する
[プレビュー] セクションの [質問する] フィールドに質問の例を入力し、Enter キーを押します。
データ エージェントが想定どおりのデータを返すことを確認するには、エージェントの回答を確認します。回答が想定どおりでない場合は、[エディタ] セクションで設定を変更して、満足のいく回答が得られるまでデータ エージェントの構成を調整します。エージェントのテストと修正を反復することで、エージェントの結果を改善できます。
[保存] をクリックします。
データ エージェントをドラフト モードにするには（後で再編集できます）、 [ 戻る] をクリックして [エージェント カタログ] ページに戻ります。 エージェントがドラフト モードになったため、[エージェント カタログ] タブの [マイ ドラフト エージェント] セクションに表示されます。
エージェントを公開するには、エージェント作成ページで次のステップに進みます。
[公開] をクリックしてデータ エージェントを公開し、プロジェクトでデータ エージェントを使用できるようにします。エージェントを公開すると、同じデータベース テーブルにアクセスできる他のユーザーが、作成した手順とコンテキストを利用してエージェントを表示して会話できるようになります。
コンソールの Google Cloud [エージェント] ページを使用して、 データ エージェントとの会話を作成できます。また、Conversational Analytics API を使用して、データ エージェントとチャットする独自のインターフェースを構築することもできます。
省略可: [エージェントが公開されました] ダイアログで [共有] をクリックして、データ エージェントを他のユーザーと共有します。
- [共有権限] ペインで、[プリンシパルを追加] をクリックします。
- [新しいプリンシパル] フィールドに、1 つ以上のプリンシパルを入力します。
- [ロールを選択] リストをクリックします。
- [ロール] リストで、次のいずれかのロールを選択します。
- Gemini Data Analytics Data Agent User（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini Data Analytics Data Agent Editor（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini Data Analytics Data Agent User（
- [保存] をクリックします。
省略可: データ エージェントを Gemini Enterprise に公開できます。詳細については、Gemini Enterprise でデータ エージェントを公開するをご覧ください。
新しいエージェント ページに戻るには、[閉じる] をクリックします。エージェントを保存または公開すると、[エージェント カタログ] に表示されます。
データ エージェントを管理する
既存のエージェントは、[エージェント カタログ] タブにあります。このタブは次の 3 つのセクションで構成されています。
- 自分のエージェント: 作成して公開したすべてのエージェントのリスト。公開したエージェントは変更して他のユーザーと共有できます。
- マイ ドラフト エージェント: まだ公開していないエージェント。ドラフト エージェントは共有できません。
- 組織内の他のユーザーが共有: 他のユーザーが作成して 共有したエージェント。他のユーザーから権限が付与されている場合は、これらの共有エージェントを編集できます。
データ エージェントを編集する
データ エージェントを編集する手順は次のとおりです。
Google Cloud コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [アクションを開く] をクリックし、エ 1[編集] をクリックします。
必要に応じて、データ エージェントの構成を編集します。
公開せずに変更を保存するには、[保存] をクリックします。
変更を公開するには、[公開] をクリックします。[共有] ダイアログで、エージェントを他のユーザーと共有するか、[キャンセル] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを共有する
公開されたデータ エージェントを共有する手順は次のとおりです。ドラフト エージェントは共有できません。
Google Cloud コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [Open actions] > エージェント カードで [Edit] をクリックします。
データ エージェントを他のユーザーと共有するには、[共有] をクリックします。
[共有権限] ペインで、[プリンシパルを追加] をクリックします。
[プリンシパルを追加] フィールドに、1 つ以上のプリンシパルを入力します。
[ロールを選択] をクリックします。
[ロール] リストで、次のいずれかのロールを選択します。
- Gemini Data Analytics Data Agent User（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini データ分析データ エージェント編集者（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini Data Analytics Data Agent Viewer（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini Data Analytics Data Agent User（
[保存] をクリックします。
エージェントの編集ページに戻るには、[閉じる] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを削除する
Google Cloud コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブを選択します。
[エージェント カタログ] タブの [エージェント] セクションで、削除するデータ エージェントのエージェント カードを見つけます。
[アクションを開く] > [削除] をクリックします。
[エージェントを削除しますか？] ダイアログで、[削除] をクリックします。エージェントを削除すると、プロジェクトから完全に削除されます。
エージェントを削除すると、既存の会話は表示専用モードで利用できます。 削除したエージェントに新しい質問をすることはできません。
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 とクライアント シークレット を入力します。
[認可 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 を使用して、Gemini Enterprise を特定の Cloud SQL for PostgreSQL データ エージェントとのセッションに直接開きます。
- Gemini Enterprise コアチャットで
@mentionなどの@sales_pipeline_agentを記述して、 エージェントを呼び出します。 - 「過去 3 か月間のセールス パイプラインの推移はどうですか？」などの一般的な分析に関する質問をして、Gemini Enterprise がクエリを関連するデータ エージェントに自動的にルーティングできるようにします。
エージェントを見つけたら、次のいずれかの方法で操作できます。
- 1 回限りの OAuth ログインを完了して、Cloud SQL for PostgreSQL に対して安全に認証します。
- 自然言語で質問します。会話型分析エージェントはリクエストを処理し、レスポンスをテキスト、Markdown、グラフ、テーブルとして Gemini Enterprise にストリーミングします。
- 会話履歴は履歴ペインに表示されます。会話は自動的に保存されます。
ロケーション
会話型分析はグローバルに運用されており、使用するリージョンを選択することはできません。
次のステップ
- Cloud SQL for PostgreSQL の会話型分析の詳細を確認する。
- Conversational Analytics API について詳細を確認する。
- 会話でデータを分析する。
- Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）ロールでデータ エージェントを表示する権限が付与される仕組みについて確認する。