デベロッパーは、geminidataanalytics.googleapis.com を介してアクセスできる Conversational Analytics API を使用して、BigQuery、Looker、Looker Studio の構造化データに関する質問に自然言語で回答する人工知能（AI）を活用したチャット インターフェース（データ エージェント）を構築できます。Conversational Analytics API を使用すると、データ エージェントにビジネス情報とデータ（コンテキスト）を提供し、SQL、Python、可視化ライブラリなどのツールへのアクセス権を付与できます。これらのエージェントの回答はユーザーに表示され、クライアント アプリケーションによってログに記録されるため、シームレスで監査可能なデータチャット エクスペリエンスを実現できます。
Gemini for Google Cloud がデータを使用する方法とタイミングに関する説明をご覧ください。
Conversational Analytics API を使ってみる
会話分析 API の使用を開始するには、まずアーキテクチャと主要なコンセプトのドキュメントを確認して、エージェントがリクエストを処理する方法、エージェント作成者とユーザーのワークフロー、会話モード、Identity and Access Management（IAM）ロールについて理解します。データ エージェントの構築を開始するには、クイックスタート、Codelab、ノートブック、エージェント開発キット（ADK）と MCP ツールボックスを使用したガイド付きの方法か、設定と前提条件の手順に沿って自身で進める方法を選択できます。
クイックスタート
Streamlit クイックスタート アプリを使用して、ローカル テスト環境で Conversational Analytics API と統合します。
Codelabs
Conversational Analytics API Codelab で、Python SDK を BigQuery データで使用する方法を段階的に説明するチュートリアルをご覧ください。
ノートブック
次の Conversational Analytics API Colaboratory ノートブックを使用して、ガイド付きの操作で Conversational Analytics API を使ってみましょう。
- HTTP Colaboratory ノートブック: HTTP リクエストを使用して環境を設定し、データ エージェントを構築して API 呼び出しを行うためのインタラクティブなガイドを提供します。
- Python SDK Colaboratory ノートブック: Python SDK を使用して環境を設定し、データ エージェントを構築し、API 呼び出しを行うためのインタラクティブなガイドを提供します。
Agent Development Kit（ADK）と MCP Toolbox
エージェント開発キット（ADK）で ask_data_insights 関数を使用して、データに関する質問に自然言語で回答する方法について説明します。
Conversational Analytics API の機能を紹介し、実用的な統合パターンを提供する Conversational Analytics のデモとツールを確認します。
設定と前提条件
API またはサンプルを使用する前に、次の手順を完了します。
- Conversational Analytics API を有効にする: Conversational Analytics API を有効にするための前提条件について説明します。
- IAM を使用した Conversational Analytics API のアクセス制御: Identity and Access Management を使用してデータ エージェントへのアクセスを共有および管理する方法について説明します。
- Conversational Analytics API を使用してデータソースの認証と接続を行う: API の認証と、BigQuery、Looker、Looker Studio データへの接続の構成手順について説明します。
データ エージェントを構築して操作する
上記の手順が完了したら、Conversational Analytics API を使用してデータ エージェントを作成し、次の操作を行います。
- HTTP を使用してデータ エージェントを構築する: Python で直接 HTTP リクエストを使用してデータ エージェントを構築し、操作する詳細な例を示します。
- Python SDK を使用してデータ エージェントを構築する: Python SDK を使用してデータ エージェントを構築し、操作する詳細な例を示します。
- 作成されたコンテキストでエージェントの動作をガイドする: 作成されたコンテキストを提供して、エージェントの動作をガイドし、レスポンスの精度を高める方法について説明します。作成済みコンテキストの例は、BigQuery データソースと Looker データソースでも確認できます。
- Conversational Analytics API エージェントのレスポンスを可視化としてレンダリングする: Python SDK と Vega-Altair ライブラリを使用して、API レスポンスからグラフ仕様を処理し、可視化としてレンダリングする例を示します。
ベスト プラクティス
Conversational Analytics API の使用に関するベスト プラクティスについては、次のガイドをご覧ください。
- エージェントのために BigQuery の費用を管理する: プロジェクト レベル、ユーザーレベル、クエリレベルで利用上限を設定することで、Conversational Analytics API エージェントにかかる BigQuery の費用をモニタリング、管理する方法について説明します。
- 効果的な質問をする: エージェントが会話分析 API を最大限に活用できるように、効果的な質問を作成する方法を学びます。
- 会話分析 API エラーのトラブルシューティング: 一般的な会話分析 API エラーのトラブルシューティングを行います。
- 既知の制限事項: クエリ、データ、可視化、質問の制限事項など、会話分析 API の既知の制限事項に関する詳細情報を提供します。
主な API オペレーション
この API には、データ エージェントと会話を管理するための次のコア エンドポイントが用意されています。
| オペレーション | HTTP メソッド | エンドポイント | 説明 |
|---|---|---|---|
| エージェントを作成する | POST |
/v1beta/projects/*/locations/*/dataAgents |
新しいデータ エージェントを作成します。 |
| エージェントを取得する | GET |
/v1beta/projects/*/locations/*/dataAgents/* |
特定のデータ エージェントの詳細を取得します。 |
| Identity and Access Management ポリシーを取得する | POST |
/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy |
特定のデータ エージェントに対して各ユーザーに割り当てられている Identity and Access Management 権限を取得します。データ エージェント オーナーのロールを持つユーザーは、このエンドポイントを呼び出して、setIAMpolicy エンドポイントを使用してデータ エージェントを他のユーザーと共有する前に、データ エージェントの Identity and Access Management ポリシーを表示できます。 |
| Identity and Access Management ポリシーを設定する | POST |
/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy |
特定のデータ エージェントの Identity and Access Management ポリシーを設定します。データ エージェント オーナーのロールを持つユーザーは、このエンドポイントを呼び出してデータ エージェントを他のユーザーと共有する必要があります。これにより、これらのユーザーの Identity and Access Management の権限が効果的に更新されます。 |
| エージェントを更新する | PATCH |
/v1beta/projects/*/locations/*/dataAgents/* |
既存のデータ エージェントを変更します。 |
| エージェントのリスト表示 | GET |
/v1beta/projects/*/locations/*/dataAgents |
プロジェクトで使用可能なデータ エージェントを一覧表示します。 |
| アクセス可能なエージェントを一覧表示する | GET |
/v1beta/projects/*/locations/*/dataAgents:listaccessible |
プロジェクトでアクセス可能なデータ エージェントを一覧表示します。この API を呼び出すユーザーがエージェントに対する get 権限を持っている場合、データ エージェントはアクセス可能と見なされます。creator_filter フィールドを使用して、このメソッドが返すエージェントを管理できます。
|
| エージェントを削除する | DELETE |
/v1beta/projects/*/locations/*/dataAgents/* |
データ エージェントを削除します。 |
| 会話を作成する | POST |
/v1beta/projects/*/locations/*/conversations |
新しい永続的な会話を開始します。 |
| 会話を参照してチャットする | POST |
/v1beta/projects/*/locations/*:chat |
既存の会話とその関連するエージェント コンテキストを参照するチャット メッセージを送信して、ステートフルな会話を継続します。マルチターンの会話の場合、 Google Cloud が会話履歴を保存して管理します。 |
| データ エージェントを参照してチャットする | POST |
/v1beta/projects/*/locations/*:chat |
コンテキストの保存済みデータ エージェントを参照するステートレス チャット メッセージを送信します。マルチターンの会話では、アプリケーションが会話履歴を管理し、各リクエストで会話履歴を提供する必要があります。 |
| インライン コンテキストを使用してチャットする | POST |
/v1beta/projects/*/locations/*:chat |
保存されたデータ エージェントは使用せず、リクエストでコンテキストを直接提供してステートレスなチャット メッセージを送信します。マルチターンの会話では、アプリケーションが会話履歴を管理し、各リクエストで会話履歴を提供する必要があります。 |
| 会話を取得する | GET |
/v1beta/projects/*/locations/*/conversations/* |
特定の会話の詳細を取得します。 |
| スレッドのリストを取得 | GET |
/v1beta/projects/*/locations/*/conversations |
特定のプロジェクト内の会話を一括で取得します。 |
| 会話内のメッセージを一覧で取得する | GET |
/v1beta/projects/*/locations/*/conversations/*/messages |
特定の会話内のメッセージの一覧を取得します。 |
| 会話を削除する | DELETE |
/v1beta/projects/*/locations/*/conversations/* |
特定の会話を削除します。このエンドポイントを呼び出すには、トピック管理者の Identity and Access Management ロールまたは少なくとも cloudaicompanion.topics.delete の Identity and Access Management 権限が必要です。 |
フィードバックを送信
次のリンクを使用して、バグを報告したり、機能をリクエストしたりできます。
参考情報
Conversational Analytics API REST リファレンス: リクエストとレスポンスの構造のメソッド、エンドポイント、型定義の詳細な説明です。