「重複集計の罠」をInstructionsで封じる——BigQuery＋FlaskでゼロからAIデータエージェントを構築する方法

8月7日、Towards Data Scienceが「I Built an AI Data Agent Which Can Query Data and Answer Business Questions. Here's How.」と題した記事を公開した。単に「自然言語でSQLを発行する」だけでなく、データの構造的な罠（重複集計・誤った平均算出）をInstructions設計によって封じる実装の巧妙さが読みどころだ。Google Cloud（BigQuery）とFlaskを使い、SQLを書けないビジネスユーザーが自然言語でデータに問い合わせられるエージェントをゼロから構築する手順が詳解されている。

構築アプローチの選択

データエージェントの構築には2つの方針がある。

スクラッチ実装: LangGraph/LangChain、CrewAI、LlamaIndexなどのオーケストレーションフレームワークを使用。メモリ構造や複雑なマルチエージェントループを完全制御できる。
クラウドプラットフォームの活用: Snowflake Cortex Agents、Databricks Genie、Microsoft Fabric Data Agentsなど、主要クラウドが提供するマネージドのデータエージェント機能を使う。習得コストが低く、実装が速い。

この記事ではGoogle Cloud Platform（BigQuery）を選択している。理由は無料トライアルでConversational Analytics機能にフルアクセスでき、個人のGoogleアカウントで手軽にセットアップできるためだ。データにはKaggleのアボカド価格データセット（CC BY 4.0ライセンス）を使用し、「アボカド販売分析エージェント（Avocado Sales Analytics Agent）」として実装している。

※編集部の考察：BigQueryのConversational Analytics機能は、現在Gemini in BigQueryの一部として提供されており、BigQuery DataFramesを使ったコード生成機能とも連携が進んでいる。Snowflake Cortex AgentsやDatabricks Genieと同じ「マネージド型データエージェント」カテゴリに属するが、BigQueryはGUIによるノーコード操作からAPI経由のアプリ組み込みまで段階的に試せる点が特徴的だ。

最大のポイント：「Instructions」の書き方

BigQueryのコンソールからエージェントを作成し、データセットをKnowledgeソースとして指定するところまではGUIで完結する。しかしエージェントの品質を左右するのはInstructions（指示文）の設計だ。

記事では以下の原則が挙げられている。

明確に書く: 曖昧な表現を避け、シンプルで正確な言葉を使う
例を与える: 良いクエリと回答の例を示す
境界を設定する: エージェントがやるべきこととやってはいけないことを明示する
役割を定義する: エージェントが誰で、ユーザーが誰かを明確にする

実際に書かれたInstructionsの核心は「よくある間違いの防止」にある。このデータセットにはリージョンの階層が混在している（都市・地域・"TotalUS"）ため、単純にSUM(Total Volume) GROUP BY regionとすると重複集計が発生する。この罠をInstructionsで明示的に防いでいる。

G. Geographical Data Quality Note
The region column contains multiple overlapping geographical levels 
(cities, state regions, and "TotalUS"). Do NOT sum or aggregate data 
across these different region types.

If a user asks for a "national total," use the specific 'TotalUS' region 
(e.g., WHERE region = 'TotalUS'). This is the only correct way to get 
a national aggregate.

価格計算も同様だ。AVG(AveragePrice)を使うと販売量の違いを無視した誤った結果になる。正しくは販売量で重み付けした加重平均（SUM(Total Volume * AveragePrice) / SUM(Total Volume)）を使う必要があり、その旨もInstructionsに明記されている。

こうした「データの罠」を人間のアナリストがあらかじめ把握し、Instructionsに落とし込んでおく作業こそが、LLMが生成するSQLの品質を左右する。単に「BigQueryと繋ぐ」だけではなく、ドメイン知識をプロンプト設計に反映させる手間を惜しまないことが実用的なエージェント構築の肝だ。

Verified Queriesでさらに精度を高める

Instructionsに加えて、Verified Queries（検証済みクエリ）の登録もエージェントの回答精度に直結する。これは「この質問にはこのSQLが正解」というペアをエージェントに教え込む仕組みだ。

たとえば「2017年のカリフォルニアの平均アボカド価格は？」という質問に対して、単純平均ではなく加重平均を使うSQLを登録しておくことで、エージェントは同様の質問に対して一貫して正しいクエリを生成できるようになる。InstructionsとVerified Queriesの組み合わせが、エージェントの"信頼性"を担保する二重の安全網として機能する。

BigQueryにアクセスできないユーザー向け：Flaskアプリの構築

BigQueryのコンソールを直接使えないユーザー向けに、記事ではFlaskアプリからConversational Analytics APIを呼び出す実装も解説されている。

avocado-agent-app/
├── app.py
├── requirements.txt
├── .env
├── service-account-key.json
└── templates/
    └── index.html

APIとの接続はGoogleのgeminidataanalyticsライブラリで行う。

from google.cloud import geminidataanalytics
client = geminidataanalytics.DataChatServiceClient()

def get_agent_path():
    return f"projects/{PROJECT_ID}/locations/{AGENT_LOCATION}/dataAgents/{AGENT_ID}"

※編集部の考察：geminidataanalyticsは元記事が執筆時点で使用しているパッケージ名だが、Google Cloudのライブラリは正式リリース前後でパッケージ名や名前空間が変更されることがある。実際に試す際はGoogle Cloud Python クライアントライブラリの公式一覧で最新のパッケージ名を確認することを推奨する。

会話セッションはconversationオブジェクトとして管理され、複数の質問をまたいでコンテキストが保持される。

実装上の注意点として、APIはデフォルトで中間推論ステップ（THOUGHT）も返してくる問題がある。「Albanyの2015年の総販売量は？」と聞くと、最終回答だけでなく「Alright, the user wants to know...」といった思考過程がそのまま返ってくる。これを解消するにはtext_type == 1（THOUGHT）のメッセージを除外し、text_type == 2（FINAL_RESPONSE）のみを表示する処理が必要だ。なお、text_typeの値（1=THOUGHT、2=FINAL_RESPONSE）はAPIの仕様上定義された列挙値であり、元記事もその仕様に従って実装している。

# THOUGHT(1)を除外し、FINAL_RESPONSE(2)のみを取り出す例
messages = [m for m in response.messages if m.text_type == 2]

完全なコードはGitHubリポジトリで公開されている。

AIデータエージェントとは何か——改めて整理する

ここで改めて概念を整理しておく。データエージェントとは、ビジネスユーザーが自然言語で質問を投げると、データウェアハウスへの問い合わせ結果を直接届けるAI駆動の会話インターフェースだ。

A data agent is an AI-powered conversational interface that enables business users to ask questions in plain language and receive accurate answers by querying data stored in a data warehouse.

「Southeast Asiaの昨年のTPVは？」と聞けば「$60 Billion」と返ってくる——そういった仕組みを、SQLを書ける人間を介さずに実現する。BigQueryのコンソール操作からFlask APIの実装まで段階的に構成されており、BigQueryの無料トライアルがあれば個人でも再現できる。また、LangGraphなどフレームワークを使ったスクラッチ実装との使い分けや発展的な学習に関心がある読者は、LangGraphの公式ドキュメントも合わせて参照するとよい。

詳細はI Built an AI Data Agent Which Can Query Data and Answer Business Questions. Here's How.を参照していただきたい。