データ エージェントを構築し、データを使ってチャットする

デベロッパーは、geminidataanalytics.googleapis.com またはリージョン エンドポイントを介してアクセスできる Conversational Analytics API を使用して、人工知能（AI）を活用したチャット インターフェース（データ エージェント）を構築できます。この API は、自然言語を使用して BigQuery、Looker、データポータル、データベース データソース（AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL（v1beta のプレビュー版））の構造化データに関する質問に回答します。マルチターン チャットに加えて、QueryData メソッドを使用してシングルターン クエリを実行できます。

Conversational Analytics API を使用すると、データ エージェントにビジネス情報とデータ（コンテキスト）を提供し、SQL、Python、可視化ライブラリなどのツールへのアクセス権を付与できます。これらのエージェントの回答はユーザーに表示され、クライアント アプリケーションによってログに記録されるため、シームレスで監査可能なデータチャット エクスペリエンスを実現できます。

Gemini for Google Cloud がデータを使用する方法とタイミングに関する説明をご覧ください。

Conversational Analytics API を使ってみる

Conversational Analytics API の使用を開始するには、次のドキュメントを読み、利用可能な統合アプローチと主要なコンセプトを理解してください。

データ エージェントの構築を開始するには、設定と前提条件のドキュメントの手順を完了します。ガイド付きチュートリアル、サンプル アプリケーション、SDK、その他のデベロッパー ツールについては、Conversational Analytics API のチュートリアル、デモ、ツールをご覧ください。

設定と前提条件

API またはサンプルを使用する前に、次の手順を完了します。

  • Conversational Analytics API を有効にする: Conversational Analytics API を有効にするための前提条件について説明します。
  • IAM によるアクセス制御: Identity and Access Management を使用してデータ エージェントへのアクセスを共有および管理する方法について説明します。
  • データソースの認証と接続: API の認証と、BigQuery、Lakehouse、Looker、データポータル、データベース データソース（AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL）への接続の構成手順について説明します。
  • BigQuery に接続する: 必要なロールと、データ エージェントを BigQuery テーブルとグラフに接続する方法について説明します。
  • Looker に接続する: データ エージェントを Looker Explore に接続し、Looker インスタンスを認証する方法について説明します。
  • 顧客管理の暗号鍵（CMEK）: Cloud Key Management Service で独自の暗号鍵を使用して、データ エージェントと会話を保護する方法について説明します。
  • 組織のポリシーの制約: 事前定義された組織のポリシーの制約を使用して、組織、フォルダ、プロジェクト レベルでリソースを制御する方法について説明します。

データ エージェントを構築して操作する

上記の手順が完了したら、Conversational Analytics API を使用してデータ エージェントを作成し、次の操作を行います。

ベスト プラクティス

Conversational Analytics API を使用する際のベスト プラクティスについては、次のガイドをご覧ください。

API リファレンスとクライアント ライブラリ

主な API オペレーション

この API には、データ エージェントと会話を管理するための次のコア エンドポイントが用意されています。次の表の v1 エンドポイントは、BigQuery、Looker、データポータルのデータソースをサポートしています。データベース データソースは v1beta のプレビュー版であるため、データベース ソースに対応する /v1beta/ パスを指定します。

これらのパス（または対応する SDK リソース名）を作成するときは、ワイルドカード（*）をプロジェクト ID、ロケーション ID（global や us など）、リソース ID（エージェント ID や会話 ID など）に置き換えます。

オペレーション HTTP メソッド エンドポイント 説明
エージェントを作成する POST /v1/projects/*/locations/*/dataAgents 新しいデータ エージェントを作成します。
エージェントを同期的に作成する POST /v1/projects/*/locations/*/dataAgents:createSync 新しいデータ エージェントを同期的に作成します。
エージェントを取得する GET /v1/projects/*/locations/*/dataAgents/* 特定のデータ エージェントの詳細を取得します。
Identity and Access Management ポリシーを取得する POST /v1/projects/*/locations/*/dataAgents/*:getIamPolicy 特定のデータ エージェントに対して各ユーザーに割り当てられている Identity and Access Management 権限を取得します。Data Agent Owner ロールを持つユーザーは、このエンドポイントを呼び出して、setIAMpolicy エンドポイントを使用してデータ エージェントを他のユーザーと共有する前に、データ エージェントの Identity and Access Management ポリシーを表示できます。
Identity and Access Management ポリシーを設定する POST /v1/projects/*/locations/*/dataAgents/*:setIamPolicy 特定のデータ エージェントの Identity and Access Management ポリシーを設定します。Data Agent Owner ロールを持つユーザーは、このエンドポイントを呼び出してデータ エージェントを他のユーザーと共有する必要があります。これにより、これらのユーザーの Identity and Access Management の権限が効果的に更新されます。
エージェントを更新する PATCH /v1/projects/*/locations/*/dataAgents/* 既存のデータ エージェントを変更します。
エージェントを同期的に更新する PATCH /v1/projects/*/locations/*/dataAgents/*:updateSync 既存のデータ エージェントを同期的に変更します。
エージェントのリスト表示 GET /v1/projects/*/locations/*/dataAgents プロジェクトで使用可能なデータ エージェントを一覧表示します。
アクセス可能なエージェントのリスト表示 GET /v1/projects/*/locations/*/dataAgents:listaccessible プロジェクトで使用可能なデータ エージェントを一覧表示します。この API を呼び出すユーザーがエージェントに対する get 権限を持っている場合、データ エージェントはアクセス可能と見なされます。creator_filter フィールドを使用して、このメソッドが返すエージェントを管理できます。
  • NONE（デフォルト）: エージェントの作成者に関係なく、ユーザーがアクセスできるすべてのデータ エージェントを返します。
  • CREATOR_ONLY: ユーザーがアクセスでき、そのユーザーが作成したデータ エージェントのみを返します。
  • NOT_CREATOR_ONLY: ユーザーがアクセスでき、他のユーザーが作成したデータ エージェントのみを返します。
エージェントを削除する DELETE /v1/projects/*/locations/*/dataAgents/* データ エージェントを削除します。
エージェントを同期的に削除する DELETE /v1/projects/*/locations/*/dataAgents/*:deleteSync データ エージェントを同期的に削除します。
会話を作成する POST /v1/projects/*/locations/*/conversations 新しい永続的な会話を開始します。
会話を参照してチャットする POST /v1/projects/*/locations/*:chat 既存の会話とその関連するエージェント コンテキストを参照するチャット メッセージを送信して、ステートフルな会話を継続します。マルチターンの会話の場合、 Google Cloud が会話履歴を保存して管理します。
データ エージェントを参照してチャットする POST /v1/projects/*/locations/*:chat コンテキストの保存済みデータ エージェントを参照するステートレス チャット メッセージを送信します。マルチターンの会話では、アプリケーションが会話履歴を管理し、各リクエストで会話履歴を提供する必要があります。
インライン コンテキストを使用してチャットする POST /v1/projects/*/locations/*:chat 保存されたデータ エージェントは使用せず、リクエストでコンテキストを直接提供してステートレスなチャット メッセージを送信します。マルチターンの会話では、アプリケーションが会話履歴を管理し、各リクエストで会話履歴を提供する必要があります。
会話を取得する GET /v1/projects/*/locations/*/conversations/* 特定の会話の詳細を取得します。
スレッドのリストを取得 GET /v1/projects/*/locations/*/conversations 特定のプロジェクト内の会話を一括で取得します。
会話内のメッセージを一覧で取得する GET /v1/projects/*/locations/*/conversations/*/messages 特定の会話内のメッセージの一覧を取得します。
会話を削除する DELETE /v1/projects/*/locations/*/conversations/* 特定の会話を削除します。このエンドポイントを呼び出すには、トピック管理者の Identity and Access Management ロールまたは少なくとも cloudaicompanion.topics.delete の Identity and Access Management 権限が必要です。
データのクエリ POST /v1beta/projects/*/locations/*/conversations:queryData 自然言語を使用して、AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL データベースのデータをクエリします。
エージェント カードを取得する（A2A） GET /v1/a2a/projects/*/locations/*/agents/*/v1/card A2A プロトコルを使用して、組み込みまたはカスタムのデータ エージェントの機能、スキル、サポートされている拡張機能を取得します。
メッセージを送信（A2A） POST /v1/a2a/projects/*/locations/*/agents/*/v1/message:send A2A プロトコルを使用してデータ エージェントにメッセージを送信します。
ストリーミング メッセージを送信する（A2A） POST /v1/a2a/projects/*/locations/*/agents/*/v1/message:stream A2A プロトコルを使用してデータ エージェントにストリーミング メッセージを送信し、リアルタイムの推論の進行状況と構造化されたアーティファクト（SQL クエリやグラフの可視化など）を返します。

サポートとフィードバック

サポートが必要な場合や、問題を報告する場合は、カスタマーケアにお問い合わせください。サポートケースの作成と管理のガイダンスに沿って、サポートケースを開きます。ケースを作成する際は、次のガイドラインに沿って対応してください。

  • BigQuery での Conversational Analytics API のサポートについては、[プロダクトを選択] リストで [BigQuery] を選択し、[機能] フィールドで [AI と ML::BigQuery の Conversational Analytics API] を選択します。
  • Looker での Conversational Analytics API のサポートについては、[プロダクトを選択] リストで [Looker（オリジナル）] を選択し、[機能] フィールドで [Gemini in Looker::Conversational Analytics API] を選択します。

会話分析 API に関する一般的なフィードバックやご質問がある場合は、conversational-analytics-api-feedback@google.com 宛てにメールをお送りください。メールでのご連絡に対して返信を保証するものではありませんが、メールを拝見し、ロードマップの計画時にこのフィードバックを参照します。

Conversational Analytics API の新機能に関する機能リクエストを送信することもできます。