会話型データ エージェントを使用すると、自然言語インターフェースを使用してデータベース データとやり取りできます。これらのエージェントを構築することで、ユーザーは複雑な SQL クエリを記述することなく、オペレーショナル データベースから分析情報を取得できます。
データ エージェントは、ペルソナと、目的を達成するために不可欠な一連のビジネス知識にアクセスできるデータソースの組み合わせです。
アプリケーション デベロッパーにとって、これらのエージェントには次のようなメリットがあります。
- 高精度: 作成されたコンテキストを使用することで、特定のビジネスに関する質問に対して高い精度を実現できます。作成されたコンテキストは、エージェント作成者が精度を向上させるために使用できる主な要素です。 これには、スキーマの説明、システム指示、予想されるデータベース クエリに関する追加情報を提供する構造化されたコンテキストが含まれます。
- 複雑さの軽減: エージェントは、自然言語を SQL クエリ、実行、さらにはデータの要約や可視化に変換します。
- 柔軟性: 個人テスト用のエージェントを作成することも、公開してプロジェクト内の他のユーザーが利用できるようにすることも、API を使用してプログラムで利用できるようにすることもできます。
始める前に
-
Cloud SQL、Data Analytics API with Gemini、Gemini for Google Cloud API を有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限を含む Service Usage 管理者 IAM ロール（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?）。[ナレッジソース] セクションで、[ソースを追加] をクリックします。[データを追加] ページが開きます。
エージェントが質問に回答する際に焦点を当てるテーブルを選択します。他の ナレッジソースを表示するには、 [さらに表示] を選択します。
[追加] をクリックします。新しいエージェント ページが再度開きます。
テーブルとフィールドの説明をカスタマイズする
会話型データ エージェントの精度を高めるために、追加のテーブル メタデータを提供することもできます。このメタデータはデータ エージェントによってのみ使用されるもので、ソーステーブルには影響しません。次のメタデータを追加できます。
- スキーマの説明: テーブルと列の説明を追加して、エージェントがデータを理解できるようにします。説明を追加しない場合、エージェントはデータ定義のスキーマの説明を使用します。
テーブルとフィールドの説明を追加する際は、次のベスト プラクティスに従ってください。
- データ エージェントの定義だけでなく、データ定義にも説明を追加します。これにより、他のエージェントも説明を利用できるようになります。
- データ エージェントがデータを理解できるように適切な説明をプロトタイプするには、特定のエージェントに説明を追加します。説明が意図した効果をもたらしていることを確認したら、データ定義に説明を追加するかどうかを決定できます。
テーブルとフィールドの説明を構成する手順は次のとおりです。
- [エージェント カタログ] タブで、カスタマイズするエージェントを開きます。
- [エージェントを編集] をクリックします。
- [ナレッジソース] で、カスタマイズするテーブルを見つけて [カスタマイズ] をクリックします。
- テーブルの説明を入力します。
- フィールドの説明を編集するには、フィールドの横にある
[編集] をクリックします。[フィールドを編集] ペインが開きます。
- [ID] フィールドに、フィールドの説明を入力します。
- フィールドの説明を保存するには、[更新] をクリックします。
- 説明とフィールドの更新を保存するには、[更新] をクリックします。新しいエージェント ページが再度開きます。
- カスタマイズするテーブルごとに、この手順を繰り返します。
データ エージェントにラベルを追加する
[Agent Settings] セクションで、 ラベルを作成してリソースを整理できます。 Google Cloud ラベルは、関連するオブジェクトをまとめてグループ化したり、他の Google Cloud リソースと組み合わせてグループ化できる Key-Value ペアです。
- [エージェント カタログ] タブで、ラベルを追加するエージェントを開きます。
- [エージェントを編集] をクリックします。
- [エージェントの設定] セクションで、[ラベルを追加] をクリックします。[ラベルの管理] ペインが開きます。
- [ラベルを追加] をクリックします。
- [キー] フィールドと [値] フィールドに、ラベルの Key-Value ペアを入力します。
- ラベルを追加する場合は、[ラベルを追加] をもう一度クリックします。
- ラベルを削除するには、delete をクリックします。
- 完了したら、[追加] をクリックします。新しいエージェント ページが再度開きます。
次のセクションに進んで、エージェントをドラフト モードにするか、エージェントを公開します。
エージェントをプレビューして公開する
[プレビュー] セクションの [質問する] フィールドに質問の例を入力し、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 PostgreSQL] ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [アクションを開く] をクリックし、エ 1[編集] をクリックします。
必要に応じて、データ エージェントの構成を編集します。
公開せずに変更を保存するには、[保存] をクリックします。
変更を公開するには、[公開] をクリックします。[共有] ダイアログで、エージェントを他のユーザーと共有するか、[キャンセル] をクリックします。
[**戻る**] をクリックして、[**エージェント**] ペインに戻ります。
データ エージェントを共有する
公開されたデータ エージェントを共有する手順は次のとおりです。ドラフト エージェントは共有できません。
Google Cloud コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [Open actions] > エージェント カードで [Edit] をクリックします。
データ エージェントを他のユーザーと共有するには、[共有] をクリックします。
[共有権限] ペインで、[プリンシパルを追加] をクリックします。
[プリンシパルを追加] フィールドに、1 つ以上のプリンシパルを入力します。
[ロールを選択] をクリックします。
[ロール] リストで、次のいずれかのロールを選択します。
- Gemini データ分析データ エージェント ユーザー（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini データ分析データ エージェント編集者（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini データ分析データ エージェント ユーザー（
[保存] をクリックします。
エージェントの編集ページに戻るには、[閉じる] をクリックします。
[戻る] をクリックして、[エージェント] ペインに戻ります。
データ エージェントを削除する
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 コンソールのユーザーが利用できるようにする手順は次のとおりです。
コンソールで、[Gemini Enterprise] に移動します。 Google Cloud
エージェントを登録するアプリの名前をクリックします。
[エージェント] > [エージェントの追加] をクリックします。
[エージェント タイプの選択] セクションで、[A2A によるカスタム エージェント] の [追加] をクリックします。
[エージェント カードの JSON] フィールドに、データ アナリストから事前に受け取ったエージェント カードの詳細を JSON 形式で入力します。
[エージェントの詳細をプレビュー > 次へ] をクリックします。
エージェントがユーザーに代わって Google Cloud リソースにアクセスできるようにするには、 次の操作を行います。
[認可 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）ロールでデータ エージェントを表示する権限を付与する方法について詳細を確認する。