データ分析

Conversational Analytics API を使用して BigQuery で会話型エージェントを構築する

2026年3月4日

David Tamaki Szajngarten

Developer Relations Engineer

Wei Hsia

Developer Advocate

Try Nano Banana 2

State-of-the-art image generation and editing

Try now

※この投稿は米国時間 2026 年 2 月 20 日に、Google Cloud blog に投稿されたものの抄訳です。

データを BigQuery に取り込むことで情報は一元化できますが、真の課題はそのデータを利用できるようにすることです。技術的な障壁のために、知りたいことがある人（経営幹部からアナリストまで）が必要な回答を得られない、ということが少なくありません。

Gemini を搭載した Conversational Analytics API を使用すれば、複雑なシステムを使わなくてもインサイトが得られます。この API は、自然言語を理解し、BigQuery データをクエリして、テキスト、テーブル、グラフで回答を提供する、コンテキスト認識型エージェントの構築を支援するよう設計されています。

現在、API と連携できるソリューションであれば、どのようなものでも構築できます。たとえば、Agent Development Kit（ADK）と統合してマルチエージェントシステムを構築したり、以下のようなデータ戦略を実装したりすることができます。

運用担当者向けのセルフサービストリアージ: サポートチームやセールスチームなどに、データに関する質問に即座に回答するエージェントを提供します。「Why did signups drop last week?（先週、登録者数が減ったのはなぜ？）」といった質問をチケットで問い合わせなくても、すぐに回答を得ることができます。
SaaS プロダクトを差別化: 優れたチャットインターフェースをプラットフォームに直接埋め込むことで、プラットフォームを差別化できます。お客様は平易な英語を使用して、独自の使用状況データをクエリ、可視化できます。
動的なレポート: 静的な PDF を超えるレポート機能です。核となるレポート機能を自動化し、レポートをリアルタイムの会話バージョンに効果的に置き換え、関係者が微妙なニュアンスのフォローアップの質問をしてより詳細な調査ができるようにします。

この投稿では、Conversational Analytics API を使用して BigQuery で会話型エージェントを構築する方法をご紹介します。

ステップ 1: エージェントを構成して作成する

データ分析エージェントをデプロイするには、最終的な作成呼び出しを行う前に、アクセス、コンテキスト、環境を構成する必要があります。

ご紹介する例では Python SDK を使用していますが、Conversational Analytics API はユーザーの好みや環境に応じて他の多くの言語にも対応しています。

クライアントを初期化し、BigQuery ソースを定義する

まず、API とのやり取りに必要なクライアント（DataAgentServiceClient）をインスタンス化します。このクライアントは、明示的な BigQueryTableReference オブジェクトと組み合わせて使用します。BigQueryTableReference オブジェクトは、エージェントが特定のテーブル（project_id、dataset_id、table_id で定義）にアクセスすることを承認します。こうした個々の参照は、bq フィールドの下の DatasourceReferences オブジェクトに集約されます。

読み込んでいます...

エージェントコンテキストを設定する

system_instruction（エージェントの動作 / ロールを定義）と datasource_references（エージェントがアクセスできるデータを定義）をバンドルして、コンテキストオブジェクトを構築します。完成したコンテキストは、最終オブジェクト DataAgent の DataAnalyticsAgent 構造体の中でネストされます。

文字列ベースのシステム指示を与えることもできますが、より堅牢なコンテキストオブジェクトを使用してエージェントに指示を与えることをおすすめします。さらに、オブジェクトに追加のシステム指示を与えて、補足ガイダンスを提供できるようにすることもできます。

読み込んでいます...

エージェントを作成する

data_agent_client.create_data_agent を呼び出します。このリクエストには、親リソースパス（projects/{billing_project}/locations/{location}）、一意のdata_agent_id、デプロイを完了できるようにすべて構成された data_agent オブジェクトが含まれます。

読み込んでいます...

これで、エージェントが作成され、published_context によって定義されます。

ステップ 2: 会話を作成する（ステートフルとステートレス）

Conversational Analytics API は、以下の 2 つの方法で会話を処理できます。

ステートレス: 質問とエージェントコンテキストを送信します。会話履歴は自身のアプリケーションで管理し、新しいリクエストごとに送信する必要があります。
ステートフル: サーバーで「会話」を作成します。API が履歴を管理します。これにより、ユーザーはフォローアップの質問をすることができます。

ここでは、ステートフルな会話を構成します。新しいエージェントに関連付けられた会話オブジェクトを作成します。

読み込んでいます...

ステップ 3: ストリーミングチャットループを作成する

インタラクティブな分析を可能にするため、会話フローを管理する関数 stream_chat_response を実装します。Data Analytics Agent API は、レスポンスをストリームとして返すように設計されています。この処理は、エージェントの最新の進捗状況をリアルタイムで提供するために不可欠です。

一般的なレスポンスストリームには、以下のような個別のコンポーネントが含まれます。

スキーマ: テーブルの解像度の確認。
データ（クエリ）: 生成された SQL クエリ（デバッグと透明性の確保に適しています）。
データ（結果）: 結果のデータ構造体（Pandas のような DataFrame など）。
グラフ: データ可視化のための Vega-Lite JSON 仕様。
テキスト: 合成された自然言語での最終的な要約。

関数を定義する

この関数は、ユーザーの質問を受け付けるように定義されています。内部では、DataChatServiceClient を初期化し、ストリーミング完了後にグラフをレンダリングする必要があるかどうかを追跡するための単純なフラグ（chart_generated_flag）を定義します。ユーザーの質問は、API リクエストに必要な Message オブジェクトにラップされます。

読み込んでいます...

ストリームを処理する

ConversationReference は必須です。ステートフルな会話に関連付け、先ほど作成した特定の data_agent にリンクします。親パス、メッセージ、参照を使ってリクエストオブジェクトを完全に構築したら、data_chat_client.chat を呼び出します。

次に、返されたストリームを反復処理します。ここでは、ユーティリティ関数 show_message を使用して、さまざまなレスポンスタイプ（テキスト、グラフ、データ）を解析し、ユーザーに合わせて適切にフォーマットしています。最後に、ストリーム内で chart_generated_flag が設定されていた場合は、後処理ユーティリティ（preview_in_browser）が可視化のレンダリングを処理します。

読み込んでいます...

# Reference the stateful conversation and the created Data Agent
    conversation_reference = geminidataanalytics.ConversationReference(
        conversation=data_chat_client.conversation_path(
            billing_project, location, conversation_id
        ),
        data_agent_context=geminidataanalytics.DataAgentContext(
            data_agent=data_chat_client.data_agent_path(
                billing_project, location, data_agent_id
            ),
        ),
    )
    
    # Prepare the chat request
    request = geminidataanalytics.ChatRequest(
        parent=f"projects/{billing_project}/locations/{location}",
        messages=messages,
        conversation_reference=conversation_reference,
    )
    
    # Process the streaming response
    stream = data_chat_client.chat(request=request)
    for response in stream:
        # 'show_message' is a utility function that formats
        # and prints the different response types (text, data, chart)
        show_message(response, chart_generated_flag)

# If a chart was generated, 'preview_in_browser'
    # is a utility to save and serve it as HTML
    if chart_generated_flag[0]:
        preview_in_browser()

ステップ 4: エージェントと会話する

質問する

では、成果を見てみましょう。stream_chat_response 関数を使用して会話できます。

コンテキストを確認する

まず、エージェントがそのコンテキストを理解しているかどうかを確認しましょう。

Python

読み込んでいます...

エージェントは、system_instruction で指定した説明を使用して、top_terms テーブルと top_rising_terms テーブルの概要を返します。

自然言語から SQL、そしてグラフへ

今度は、複雑なクエリを見てみましょう。平易な英語でグラフをリクエストしていることに注目してください。

Python

読み込んでいます...

エージェントは、このプロセスを以下のようにストリーミングします。

生成された SQL クエリを表示します。このクエリは、top_terms テーブルにアクセスし、dma_name = 'New York NY' と直近の 1 週間でデータをフィルタします。
結果のデータをテーブルとして出力します。
Vega グラフの仕様を生成します。
preview_in_browser ユーティリティがこれを、縦棒グラフを表示する index.html ファイルとして提供します。

ステートフルなフォローアップ

ここで、ステートフルな会話（ステップ 2）が力を発揮します。

Python

読み込んでいます...

エージェントは、「these search terms（これらの検索語句）」が質問 2 の結果を指していることを記憶しています。新しいクエリを生成し、今回は（join_instructions の指示に沿って）top_terms テーブルと top_rising_terms テーブルを INNER JOIN して、同じ語句リストの percent_gain を取得します。

ステップ 5: エージェントを管理する

エージェントとメッセージのライフサイクル管理について詳しくは、Conversational Analytics API ドキュメントの、実行できるさまざまな API リクエスト（HTTP / Python）に関するページをご確認ください。エージェントの管理方法、SetIAM API、GetIAM API 経由で新たにユーザーを招待して共同作業を行う方法などについても説明しています。

上級者向けのヒント: データと人のギャップを埋める

明確なシステム指示とスキーマ説明を与えることで、単なる会話型エージェントではなく、該当分野のエキスパートとなるエージェントを構築できます。このインタラクティブなアプローチは、静的なダッシュボードを越え、真に利用できるデータ分析を実現します。