このドキュメントでは、Conversational Analytics API（geminidataanalytics.googleapis.com）を使用するための重要なコンセプトについて説明します。この API を使用すると、自然言語を使用して構造化データに関する質問に回答するデータ エージェントを作成して操作できます。このドキュメントでは、エージェントの仕組み、一般的なワークフロー、会話モード、Identity and Access Management（IAM）ロール、複数のエージェントを含むシステムを設計する方法について説明します。
データ エージェントの仕組み
Conversational Analytics API データ エージェントは、提供されたコンテキスト（ビジネス情報とデータ）とツール（SQL や Python など）を使用して、自然言語の質問を解釈し、構造化データから回答を生成します。
次の図は、ユーザーが質問したときのエージェントのワークフローの各ステージを示しています。
図に示すように、ユーザーが質問すると、エージェントは次の段階でリクエストを処理します。
- ユーザー入力: ユーザーは、自然言語で質問を送信します。このとき、追加のコンテキストも送信できます。
- データソース: エージェントは Looker、BigQuery、Looker Studio のデータに接続して、必要な情報を取得します。
- 推論エンジン: エージェントの中核となる部分で、利用可能なツールを使用してユーザーの質問を処理し、回答を生成します。
- エージェントの出力: エージェントがレスポンスを生成します。レスポンスには、テキスト、データテーブル、グラフの仕様などを含めることができます。
エージェントの設計と使用のワークフロー
会話分析 API は、エージェント作成者（エージェントを構築して構成するユーザー）とエージェント コンシューマー（エージェントとやり取りするユーザー）のワークフローをサポートしています。
次の図は、エージェント作成者による初期設定からエージェント利用者による最終的なやり取りまでのエンドツーエンドのプロセスを示しています。
以降のセクションでは、エージェント作成者とエージェント利用者のワークフローについて詳しく説明します。
エージェント作成ワークフロー
エージェントの作成者は、エージェントの設定と構成を担当します。このワークフローには次の手順が含まれます。
- エージェントを作成する: 作成者は、新しいエージェントを作成し、システム指示やデータソースへの接続など、必要なコンテキストを指定します。このステップは、エージェントがユーザーの質問を効果的に理解して回答できるようにするために不可欠です。
- エージェントを共有する: エージェントが構成されると、作成者は他のユーザーと共有し、権限を管理するための適切なロールベースのアクセス制御を設定します。
エージェント コンシューマーのワークフロー
エージェント コンシューマーは通常、構成されたエージェントから回答を得る必要があるビジネス ユーザーです。このワークフローには次の手順が含まれます。
- エージェントを見つける: ユーザーは、自分と共有されているエージェントを見つけることから始めます。
- 質問する: ユーザーが自然言語で質問します。この質問は、単一のクエリにすることも、複数ターンの会話の一部にすることもできます。
- エージェントの「思考」: エージェントの推論エンジンが質問を処理します。推論エンジンは、エージェントの事前定義された知識と利用可能なエージェント ツール（SQL、Python、グラフなど）を「推論ループ」で使用して、質問に答える最適な方法を判断します。
- エージェントが応答する: エージェントが回答を返します。回答には、テキスト、データテーブル、グラフを含めることができます。
会話モード
Conversational Analytics API エージェントは、エージェントが会話履歴とインタラクション間のコンテキストの永続性を処理する方法を決定するさまざまな会話モードをサポートしています。次の会話モードを使用できます。
- ステートレス モード: エージェントは会話履歴を保存しません。各インタラクションは個別に処理されます。このモードは、複数のターンにわたってコンテキストを維持する必要がないアプリケーションに便利です。
- ステートフル モード: エージェントはコンテキストと会話履歴を保持し、よりコンテキストに沿ったインタラクションを可能にします。このモードは、複数のターンにわたってコンテキストを維持する必要があるアプリケーションに役立ちます。精度を高め、パーソナライズされた回答を得るには、ステートフル モードを使用することをおすすめします。
会話履歴とコンテキストの永続性に関するアプリケーションの要件に基づいて、会話モードを選択します。
IAM ロール
IAM ロールは、Conversational Analytics API エージェントの作成、管理、共有、操作を行うことができるユーザーを制御します。次の表に、Conversational Analytics API の主な IAM ロールを示します。
| ロール | 一般的なスコープ | ロールでできること | このロールを使用するユーザー |
|---|---|---|---|
Gemini データ分析データ エージェント作成者（roles/geminidataanalytics.dataAgentCreator） |
プロジェクト | エージェントを作成し、エージェントのオーナー権限を継承します。 | データ アナリスト |
Gemini データ分析データ エージェント オーナー（roles/geminidataanalytics.dataAgentOwner） |
プロジェクト、エージェント | 他のユーザーとエージェントを編集、共有、削除する。 | シニア データ アナリスト |
Gemini データ分析データ エージェント編集者（roles/geminidataanalytics.dataAgentEditor） |
エージェント、プロジェクト | エージェントの構成またはコンテキストを更新します。 | ジュニア データ アナリスト |
Gemini データ分析データ エージェント ユーザー（roles/geminidataanalytics.dataAgentUser） |
エージェント、プロジェクト | エージェントとチャットします。 | マーケター、店舗オーナー |
Gemini データ分析データ エージェント閲覧者（roles/geminidataanalytics.dataAgentViewer） |
プロジェクト、エージェント | エージェントを一覧表示して詳細を取得します。 | すべてのユーザー |
Gemini データ分析データ エージェント ステートレス ユーザー（roles/geminidataanalytics.dataAgentStatelessUser） |
プロジェクト | コンテキストや会話履歴を保存せずにエージェントとチャットします。 | すべてのユーザー |
複数のエージェントを含むシステム
複数の Conversational Analytics API エージェントを統合することで、複雑なシステムを設計できます。一般的なパターンは、販売データやマーケティング データなどの特定のドメインを処理する 1 つ以上の専門エージェントにタスクを委任するプライマリ「オーケストレーター」エージェントを使用することです。このアプローチでは、複数のエージェントの強みを組み合わせて、幅広い質問に対応できるシステムを構築できます。
次の図は、このマルチエージェント パターンを示し、プライマリ エージェントがデータに関する質問を専門の Conversational Analytics エージェントに委任する方法を示しています。
マルチエージェント システムの一般的なワークフローは次のとおりです。
- ビジネス ユーザーまたはデータ アナリストが、「収益上位 3 店舗を表示して」などの自然言語で質問します。
- メインの「オーケストレーター」エージェントが、リクエストを適切な専門エージェントに委任します。
- 専用のエージェントが委任されたリクエストを受け取り、関連するデータソースに接続し、ツールを使用して必要な SQL クエリとグラフを生成して、レスポンスを生成します。
- 専門のエージェントの回答がユーザーに返されます（「店舗 4、9、3 の収益が最も高いです。グラフは次のとおりです。」
次のステップ
Conversational Analytics API の基本的なコンセプトを理解したら、次の機能の実装方法を確認します。
- データソースの認証と接続の方法を確認する。
- HTTP を使用してエージェントを作成して構成する方法を学習する。
- Python を使用してエージェントを作成して構成する方法を学習する。
- 作成されたコンテキストでエージェントの動作をガイドする方法について学習する。
- Conversational Analytics API の IAM によるアクセス制御について理解する。