デベロッパーは、geminidataanalytics.googleapis.com を介してアクセスできる Conversational Analytics API を使用して、BigQuery、Looker、Looker Studio の構造化データに関する質問に自然言語で回答する人工知能（AI）を活用したチャット インターフェース（データ エージェント）を構築できます。Conversational Analytics API を使用すると、データ エージェントにビジネス情報とデータ（コンテキスト）を提供し、SQL、Python、可視化ライブラリなどのツールへのアクセス権を付与できます。これらのエージェントの回答はユーザーに表示され、クライアント アプリケーションによってログに記録されるため、シームレスで監査可能なデータチャット エクスペリエンスを実現できます。
Gemini for Google Cloud がデータを使用する方法とタイミングに関する説明をご覧ください。
Conversational Analytics API を使ってみる
Conversational Analytics API の使用を始める前に、アーキテクチャと主要なコンセプトのドキュメントを読み、エージェントがリクエストを処理する方法、エージェント作成者とユーザーのワークフロー、会話モード、Identity and Access Management（IAM）ロールについて理解してください。Conversational Analytics API の概要と主な機能については、こちらの動画をご覧ください。
データ エージェントの構築を始める場合は、クイックスタート、Codelab、ノートブック、エージェント開発キット（ADK）と MCP Toolbox のガイドを利用しながら進めることも、設定と前提条件の説明に従って自身で作業を行うこともできます。
クイックスタート
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
Agent Development Kit（ADK）の ask_data_insights 機能を使用して、データに関する質問に自然言語で回答する方法について学習します。
Conversational Analytics のデモとツールを利用して、Conversational Analytics API の機能と実用的な統合パターンを確認します。
MCP Toolbox for Databases には、Conversational Analytics API を使用して自然言語でデータソースにクエリを実行するための次のツールが用意されています。
- BigQuery 会話型分析ツール（
bigquery-conversational-analytics）: BigQuery データにクエリを実行します。 - Looker 会話分析ツール（
looker-conversational-analytics）: Looker データをクエリします。
クライアント ライブラリ
次の Conversational Analytics API クライアント ライブラでに、インストール手順とリファレンス ドキュメントが用意されています。
設定と前提条件
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 の費用をモニタリング、管理する方法について説明します。
- 効果的な質問をする: エージェントが Conversational Analytics API を最大限に活用できるように、効果的な質問を作成する方法について説明します。
- Conversational Analytics API エラーのトラブルシューティング: 一般的な Conversation Analytics API エラーのトラブルシューティングを行います。
- 既知の制限事項: クエリ、データ、可視化、質問の制限事項など、Conversational Analytics 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 リファレンス: メソッド、エンドポイント、リクエストとレスポンス構造の型定義の詳細な説明を提供します。