この Codelab について
1. 概要
AI を利用した構築を今すぐ始めるには、多くの場合、それは「このモデルは、私が考えていた問題の解決に実際に役立つだろうか？」というシンプルな質問から始まります。そこで役立つのが Google AI Studio です。あらゆるプロトタイプを迅速に作成できる場所です。キッチンを改装したいと思っていて、Gemini が役に立つと期待しています。私はエンジニアで、ゼネコンではありません。何を依頼すればよいかわからないほど、規制や設備など、考慮すべきことがたくさんあります。そこで、Gemini に詳細なプロンプトを生成してもらい、完全な改装計画を生成して、改装を可視化しましょう。でも、ビジネスの拡大を支援するにはどうすればよいですか？エージェントが登場します。
エージェントとは、AI モデルと対話して、エージェントが持つツールとコンテキストを使用して目標ベースの操作を実行する自律プログラムです。エージェントは、真実に基づく自律的な意思決定を行うことができます。
エージェント開発キット（ADK）
エージェント開発キット（ADK）は、AI エージェントの開発とデプロイを目的として設計された、柔軟性の高いモジュラー フレームワークです。ADK は、複数の個別のエージェント インスタンスをマルチエージェント システム（MAS）にコンポーズすることで、高度なアプリケーションの構築をサポートします。
ADK では、マルチエージェント システムとは、さまざまなエージェントが連携または調整して大きな目標を達成するアプリケーションです。エージェントは、階層を形成することがよくあります。このようにアプリケーションを構造化すると、モジュール性、特化、再利用性、メンテナンス性の向上、専用のワークフロー エージェントを使用して構造化された制御フローを定義する機能など、大きなメリットが得られます。
作成するアプリの概要
プロトタイプの PROMPT からエージェントの構築に移行する準備はできましたか？キッチン改装プロジェクトの提案書を作成するためのエージェントを作成します。このラボでは、次の作業を行います。
- ADK を使用してリノベーション提案書を生成するシンプルなエージェントを構築する
- 生成された改修提案書を Cloud Storage バケットに保存する
- Cloud Shell とエージェントのウェブ出力でエージェントをテストする
要件
2. 始める前に
プロジェクトを作成する
- Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
- Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
- また、Google Cloud の利用を開始して ADK を使用するのに役立つクレジットを取得したい場合は、こちらのリンクからクレジットを利用してください。
- こちらの手順に沿ってクーポンを利用できます。このリンクは、2025 年 7 月 15 日までのみ利用できます。
- このリンクをクリックして Cloud Shell を有効にします。Cloud Shell で対応するボタンをクリックすると、Cloud Shell ターミナル（クラウド コマンドの実行用）とエディタ（プロジェクトのビルド用）を切り替えることができます。
- Cloud Shell に接続したら、次のコマンドを使用して、認証が完了していることと、プロジェクトがプロジェクト ID に設定されていることを確認します。
gcloud auth list
- Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。
gcloud config list project
- プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。
gcloud config set project <YOUR_PROJECT_ID>
- Python 3.9 以降があることを確認します。
他の gcloud コマンドとその使用方法については、ドキュメントをご覧ください。
3. プロトタイプ
Google AI Studio に移動します。プロンプトを入力します。次のプロンプトを入力してみます。
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
右側のパラメータを調整して設定し、最適なレスポンスを得ます。
この簡単な説明に基づいて、Gemini はリノベーションを開始するための非常に詳細なプロンプトを作成しました。つまり、Gemini を使用して AI Studio とモデルからより優れた回答を得ています。ユースケースに応じて、使用するモデルを選択することもできます。
そのため、Gemini 2.5 Pro を選択しました。これは思考モデルであるため、長い分析や詳細なドキュメント用に、さらに多くの出力トークン（この場合は最大 65,000 トークン）が生成されます。Gemini 思考ボックスは、ネイティブ推論機能があり、長いコンテキスト リクエストを処理できる Gemini 2.5 Pro を有効にすると表示されます。
レスポンスのスニペットは次のとおりです。
AI Studio はデータを分析し、キャビネット、カウンタートップ、バックスプラッシュ、フローリング、シンク、統一感、カラーパレット、素材の選択など、さまざまなものを生成しました。Gemini は情報源を引用する機能も備えています。
別のプロンプトでアイデアを実現してみましょう。
- 次のプロンプトをコピーして、プロンプト エディタに貼り付けます。
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- 現在のキッチンの画像を添付します（キッチンのサンプル画像を使用することもできます）。
- モデルを [Gemini 2.0 Flash Preview Image Generation] に変更して、画像の生成にアクセスできるようにします。
出力は次のとおりです。
これが Gemini の力です。
動画の理解から、ネイティブな画像生成、Google 検索による実際の情報のグラウンディングまで、これらは Gemini でしか構築できないものです。
AI Studio からこのプロトタイプを取得し、API キーを取得して、Vertex AI ADK の機能を活用して完全なエージェント アプリケーションにスケーリングできます。
4. ADK の設定
では、[始める前に] セクションで有効にした Cloud Shell ターミナルに移動しましょう。
- 仮想環境を作成して有効にする（推奨）
Cloud Shell ターミナルから仮想環境を作成します。
python -m venv .venv
仮想環境を有効にします。
source .venv/bin/activate
- ADK をインストールする
pip install google-adk
5. プロジェクト構造
- Cloud Shell ターミナルで、目的のプロジェクト ロケーションにエージェント アプリのルート ディレクトリを作成します。
mkdir agentic-apps
- メイン ディレクトリ内に、現在のプロジェクトに固有のフォルダを 1 つ作成します。
mkdir renovation-agent
- Cloud Shell エディタに移動し、ファイルを作成して次のプロジェクト構造を作成します（最初は空です）。
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. ソースコード
- init.py に移動し、次の内容で更新します。
from . import agent
- agent.py に移動し、次のパスの次の内容でファイルを更新します。
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
agent.py では、必要な依存関係をインポートし、.env ファイルから構成パラメータを取得し、提案書ドキュメントを生成し、Cloud Storage バケットに保存する root_agent を定義します。Cloud Storage の手順では、store_pdf というツールを使用します。
- Cloud Storage バケットがあることを確認する
これは、エージェントが生成した提案書を保存するためのものです。作成してアクセスをプロビジョニングし、Vertex AI で作成したエージェント システムがアクセスできるようにします。手順は次のとおりです。
https://cloud.google.com/storage/docs/creating-buckets#console
バケットに「next-demo-store」という名前を付けます。別の名前を付ける場合は、.env ファイル（ENV 変数の設定手順）で STORAGE_BUCKET の値を更新してください。
- バケットへのアクセスを設定するには、Cloud Storage コンソールに移動し、ストレージ バケットに移動します（この例では、バケット名は「next-demo-storage」です。https://console.cloud.google.com/storage/browser/next-demo-storage）。
[権限] > [プリンシパルの表示] > [アクセス権を付与] に移動します。プリンシパルに「allUsers」、ロールに「ストレージ オブジェクト ユーザー」を選択します。
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- 依存関係リストを作成する
requirements.txt にすべての依存関係をリストします。これは repo からコピーできます。
単一エージェント システムのソースコードの説明
agent.py ファイルでは、エージェント開発キット（ADK）を使用して、キッチン改装マルチエージェント システムの構造と動作を定義します。主要なコンポーネントを分解してみましょう。
エージェントの定義
ルート エージェント（オーケストレーター）: proposal_agent
root_agent は、この単一エージェント システムのオケストレーターとして機能します。最初のリノベーション リクエストを受け取り、リクエストのニーズに基づいて呼び出すツールを決定します。
root_agent は、ツールからレスポンスを収集し、それらを組み合わせてユーザーに包括的なレスポンスを提供します。この例では、ツールは「store_pdf」のみです。
7. データフロー、主なコンセプト
ユーザーが ADK インターフェース（端末またはウェブ UI）からリクエストを開始します。
- リクエストは root_agent によって受信されます。
- root_agent はリクエストを分析し、必要に応じてツールに転送します。
- ツール「store_pdf」は、更新されたテキスト コンテンツを PDF ファイルに書き込んで、Google Cloud Storage にアップロードするように設計されています。
- その後、root_agent にレスポンスが返されます。
- root_agent はレスポンスを結合し、最終的な出力をユーザーに提供します。
LLM（大規模言語モデル）
これらのエージェントは、テキストの生成、質問への回答、推論タスクの実行に LLM を大きく依存しています。LLM は、エージェントがユーザーのリクエストを理解して応答する能力の「頭脳」です。このアプリケーションでは Gemini 2.5 を使用しています。
Google Cloud Storage
生成された改修提案書類を保存するために使用されます。バケットを作成して、エージェントがバケットにアクセスするために必要な権限を付与する必要があります。
Cloud Run（省略可）
OrderingAgent は、Cloud Run 関数を使用して AlloyDB とインターフェースします。Cloud Run は、HTTP リクエストに応答してコードを実行するサーバーレス環境を提供します。
AlloyDB
OrderingAgent を使用する場合は、注文情報を保存する AlloyDB データベースを設定する必要があります。
.env ファイル
.env ファイルには、API キー、データベース認証情報、バケット名などの機密情報が保存されます。このファイルを安全に保ち、リポジトリに commit しないことが重要です。また、エージェントと Google Cloud プロジェクトの構成設定も保存されます。通常、root_agent またはサポート関数はこのファイルから値を読み取ります。必要な変数がすべて .env ファイルで正しく設定されていることを確認します。これには、Cloud Storage バケット名が含まれます。
8. モデルの設定
エージェントがユーザーのリクエストを理解し、回答を生成する能力は、大規模言語モデル（LLM）によって強化されています。エージェントは、この外部 LLM サービスを安全に呼び出す必要があります。この場合、認証情報が必要です。有効な認証がないと、LLM サービスはエージェントのリクエストを拒否し、エージェントは機能しなくなります。
- Google AI Studio から API キーを取得します。
- 次のステップで .env ファイルを設定するときに、
<<your API KEY>>を実際の API キー値に置き換えます。
9. ENV 変数の設定
- このリポジトリのテンプレートの .env ファイルで、パラメータの値を設定します。私の .env には、次の変数があります。
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
プレースホルダは、独自の値に置き換えます。
10. エージェントを実行する
- ターミナルを使用して、エージェント プロジェクトの親ディレクトリに移動します。
cd agentic-apps/renovation-agent
- すべての依存関係をインストールする
pip install -r requirements.txt
- Cloud Shell ターミナルで次のコマンドを実行して、エージェントを実行できます。
adk run .
- 次のコマンドを実行して、ADK でプロビジョニングされたウェブ UI で実行できます。
adk web
- 次のプロンプトでテストします。
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
12. クリーンアップ
この投稿で使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の操作を行います。
- Google Cloud コンソールで、[リソースの管理] ページに移動します。
- プロジェクト リストで、削除するプロジェクトを選択し、[削除] をクリックします。
- ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。