会話型データ エージェントを使用すると、自然言語インターフェースを使用してデータベース データを操作できます。これらのエージェントを構築することで、ユーザーは「データと対話」できるようになり、複雑な 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 データベース認証でユーザーを管理するをご覧ください。
データ エージェントを作成する
以降のセクションでは、データ エージェントを作成する方法について説明します。 エージェントを作成したら、その設定を編集できます。
基本の構成
コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。 Google Cloud
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
[エージェント] タブをクリックします。
データベースを選択し、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 つのセクションで構成されています。
- [**自分のエージェント**]: 作成して公開したすべてのエージェントのリスト。公開したエージェントは、変更して他のユーザーと共有できます。
- [**マイ ドラフト エージェント**]: まだ公開していないエージェント。ドラフト エージェントは共有できません。
- [**組織内の他のユーザーが共有**]: 他のユーザーが作成して 共有したエージェント。他のユーザーから権限が付与されている場合は、これらの共有エージェントを編集できます。
データ エージェントを編集する
データ エージェントを編集する手順は次のとおりです。
コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。 Google Cloud
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [アクションを開く] をクリックし、エージェント カードの [編集] をクリックします。
必要に応じて、データ エージェントの構成を編集します。
公開せずに変更を保存するには、[保存] をクリックします。
変更を公開するには、[公開] をクリックします。[共有] ダイアログで、エージェントを他のユーザーと共有するか、[キャンセル] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを共有する
公開されたデータ エージェントを共有する手順は次のとおりです。ドラフト エージェントは共有できません。
コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。 Google Cloud
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
Identity and Access Management（IAM）認証を使用して [エージェント] にログインします。
[エージェント カタログ] タブをクリックします。
変更するデータ エージェントのエージェント カードを見つけます。
エージェント エディタでデータ エージェントを開くには、 [アクションを開く] > エージェント カードの [編集] をクリックします。
データ エージェントを他のユーザーと共有するには、[共有] をクリックします。
[共有権限] ペインで、[プリンシパルを追加] をクリックします。
[プリンシパルの追加] フィールドに、1 つ以上のプリンシパルを入力します。
[ロールを選択] をクリックします。
[ロール] リストで、次のいずれかのロールを選択します。
- Gemini データ分析データ エージェント ユーザー（
roles/geminidataanalytics.dataAgentUser）: データ エージェントとチャットする権限を付与します。 - Gemini データ分析データ エージェント編集者（
roles/geminidataanalytics.dataAgentEditor）: データ エージェントを編集する権限を付与します。 - Gemini データ分析データ エージェント閲覧者（
roles/geminidataanalytics.dataAgentViewer）: データ エージェントを表示する権限を付与します。
- Gemini データ分析データ エージェント ユーザー（
[保存] をクリックします。
エージェントの編集ページに戻るには、[閉じる] をクリックします。
[エージェント] ペインに戻るには、 [戻る] をクリックします。
データ エージェントを削除する
コンソールで、[Cloud SQL for PostgreSQL] ページに移動します。 Google Cloud
リストからインスタンスを選択します。
ナビゲーション メニューで、[エージェント] をクリックします。
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）ロールによってデータ エージェントを表示する権限が付与される仕組みについて確認する。