はじめに
先日、a2iのセミナーでBigQuery会話分析の話をしました。そこでの主役は「エージェント」でした。データと文脈を与えたエージェントに自然言語で質問すると、SQLを書かずに、社内の、もしかするとマーケティング部以外のメンバーでも、精度の高い分析ができる、という内容です。
あのエージェントはBigQueryのユーザーインターフェースから作ったものですが、エージェントの作成方法として、実はもう一つ、ADK（Agent Development Kit）を利用してコードで作る方法があります。今回はそちらを試してみました。
前編ではADK版エージェントを作るところまで、後編では作ったエージェントのログをBigQueryで分析する「エージェント分析」をやってみます。
ADKとは
ADKは、Googleがオープンソースで提供している、AIエージェントをPythonのコードで構築するフレームワークです。VS CodeにPythonの環境をインストールしていれば、Pythonのライブラリとして利用することができます。
私は、VS Codeに、Claude Code拡張を入れてアプリを作ったりしていますので、Python環境はすでに整っていました。ADKのインストールは、Claude Codeに、「GoogleのADKを使ってエージェントを開発したい。」と言っただけで完了です。
エージェントの「仕様」もシンプルで、モデル・指示（instruction）・ツールを指定するだけ。BigQueryにクエリを投げるためのツールセットも標準で用意されています。そうした、エージェントの「仕様」についても、Claude Codeに自然言語で指示してエージェントを作ってもらいました。
UI版と同じ文脈を移植する
題材は、私がUIで作って使っている「自然検索からのコンバージョン分析・施策提案エージェント」です。Google Search ConsoleとGA4のデータ（それぞれ直近90日間のビュー）を参照して、自然検索からのコンバージョンを増やす施策を考えるためのエージェントです。
データは、UI版に与えていたものとまったく同じ、BigQueryのビューを2つ。UI版に与えていた文脈——手順、検証済みクエリ2件、用語集4語——も、そのままADK版のinstructionに移植しました。
ここでひとつ小技を。UI版エージェントの文脈は、Conversational Analytics API（geminidataanalytics）を叩くと丸ごと取得できます。手順も用語集も検証済みクエリもJSONで返ってくるので、手作業でコピペする必要はありませんでした。UI版の文脈が「エクスポート可能」というのは、ADK版をあとから作る場合に備え、覚えておいて損のない仕様だと思います。
コードの世界にも「安全装置」がある
BigQueryへのアクセスには、ADK標準のBigQueryツールセットを使います。注目したいのは、ここにも費用と安全の仕組みがあることです。エージェントがどんなSQLを書いても、データの書き込み・変更はできず、課金上限を超えるクエリは実行前に失敗します。セミナーでお伝えした「費用の暴走を起こさせない仕組み」は、コードの世界にもちゃんとありました。
今回は、1回のクエリが10GBを超えない。という制限を付けてもらいました。
動かしてみる
ADKには開発用のチャット画面が付属しているので、Claude Codeにそれを立ち上げてもらいます。完成したエージェントに自然言語でプロンプトを投入すると、回答の質はUI版と遜色ありませんでした。同じ文脈を与えているので、当然といえば当然かもしれません。
ひとつだけ、UI版に及ばない点がありました。グラフが描けないのです。UI版の会話分析はグラフ描画機能を内蔵していますが、素のADKエージェントはテキストで答えるだけです。
ここがADKの面白いところで、足りない機能はツールとして自分で足せます。matplotlibでグラフを描いて画像として保存するツールを実装し、エージェントに持たせました。もちろん、実装したのはClaude Codeで、私は「グラフを描けるようにして」とお願いしただけです。
日本語ラベル対応のグラフがチャット内に表示されるようになりました。UI版は「用意された機能を使う」、ADK版は「必要な機能を作る」。この違いは、そのまま両者の性格を表していると思います。
ユーザーがエージェントを利用したログがBigQueryへ
そしてADK版ならではのお楽しみが、BigQuery Agent Analyticsです。プラグインを数行組み込むだけで、エージェントのあらゆる行動——質問の受信、LLMの呼び出し、ツールの実行、応答——がBigQueryのテーブルに流れ込みます。
エージェントと何往復か会話したので、ログが溜まっているはずです。
後編では、このログを使った「エージェント分析」を実際にやってみます。誰が・何を質問し、エージェントが裏でどんなSQLを書き、何トークン消費したのか。そして「グラフが描けません」と答えていたエージェントが改善されるまでの一部始終が、全部ログに残っていました。