GENAI129

スコア: このチャレンジラボに合格するには、80% 以上のスコアを獲得する必要があります。

概要

このラボでは、Agent Development Kit（ADK）を使用してエージェントを作成し、そのエージェントを Agent Runtime にデプロイしてウェブアプリから使用するスキルを実証します。

目標

このラボでは、次の作業を行います。

• Agent Development Kit（ADK）を使用して、ルート エージェントとサブエージェントで構成されるエージェントを構築する
• エージェント検索ツールと、ツールとして使用される Python 関数を使用して、エージェントを有効にする
• エージェントの出力をセッションの state に保存し、それ以降のエージェントへの指示でセッションの state から値を取得する
• エージェントを Agent Runtime にデプロイする
• Agent Runtime にデプロイしたエージェントに対してクエリを実行する

関連する学習教材

このラボを最後まで行うために必要なスキルが身につくリソースをお探しの場合は、以下の教材の関連セクションをご覧ください。

カテゴリ	リソース
コース	- Agent Development Kit（ADK）と Agent Runtime を使用してマルチエージェント システムをデプロイする
学習ラボ	- Agent Development Kit（ADK）を使ってみる - ツールで ADK エージェントを強化 - ADK を使用してマルチエージェント システムを構築する - ADK エージェントを Agent Runtime にデプロイする - AI Applications を使用してエージェント検索アプリを構築する

設定と要件

[ラボを開始] ボタンをクリックする前に

こちらの説明をお読みください。ラボには時間制限があり、一時停止することはできません。タイマーは、Google Cloud のリソースを利用できる時間を示しており、[ラボを開始] をクリックするとスタートします。

このハンズオンラボでは、シミュレーションやデモ環境ではなく実際のクラウド環境を使って、ラボのアクティビティを行います。そのため、ラボの受講中に Google Cloud にログインおよびアクセスするための、新しい一時的な認証情報が提供されます。

このラボを完了するには、以下が必要です。

• 標準的なインターネット ブラウザ（Chrome を推奨）

注: このラボの実行には、シークレット モード（推奨）またはシークレット ブラウジング ウィンドウを使用してください。これにより、個人アカウントと受講者アカウント間の競合を防ぎ、個人アカウントに追加料金が発生しないようにすることができます。

• ラボを完了するための時間（開始後は一時停止できません）

注: このラボでは、受講者アカウントのみを使用してください。別の Google Cloud アカウントを使用すると、そのアカウントに料金が発生する可能性があります。

ラボを開始して Google Cloud コンソールにログインする方法

1. [ラボを開始] ボタンをクリックします。ラボの料金をお支払いいただく必要がある場合は、表示されるダイアログでお支払い方法を選択してください。 左側の [ラボの詳細] ペインには、以下が表示されます。

   • [Google Cloud コンソールを開く] ボタン
   • 残り時間
   • このラボで使用する必要がある一時的な認証情報
   • このラボを行うために必要なその他の情報（ある場合）

2. [Google Cloud コンソールを開く] をクリックします（Chrome ブラウザを使用している場合は、右クリックして [シークレット ウィンドウで開く] を選択します）。

   ラボでリソースがスピンアップし、別のタブで [ログイン] ページが表示されます。

   ヒント: タブをそれぞれ別のウィンドウで開き、並べて表示しておきましょう。

   注: [アカウントの選択] ダイアログが表示されたら、[別のアカウントを使用] をクリックします。

3. 必要に応じて、下のユーザー名をコピーして、[ログイン] ダイアログに貼り付けます。

   {{{user_0.username | "Username"}}}

   [ラボの詳細] ペインでもユーザー名を確認できます。

4. [次へ] をクリックします。

5. 以下のパスワードをコピーして、[ようこそ] ダイアログに貼り付けます。

   {{{user_0.password | "Password"}}}

   [ラボの詳細] ペインでもパスワードを確認できます。

6. [次へ] をクリックします。

   重要: ラボで提供された認証情報を使用する必要があります。Google Cloud アカウントの認証情報は使用しないでください。 注: このラボでご自身の Google Cloud アカウントを使用すると、追加料金が発生する場合があります。

7. その後、次のように進みます。

   • 利用規約に同意します。
   • 一時的なアカウントなので、復元オプションや 2 要素認証は設定しないでください。
   • 無料トライアルには登録しないでください。

その後、このタブで Google Cloud コンソールが開きます。

注: Google Cloud のプロダクトやサービスにアクセスするには、ナビゲーション メニューをクリックするか、[検索] フィールドにサービス名またはプロダクト名を入力します。

チャレンジ シナリオ

Cymbal Shops はミネアポリスに本社を置く米国の小売チェーンで、家庭用品、電子機器、衣料品を販売しています。

この度、Cymbal Shops はヨーロッパに進出し、新たに塗料部門を立ち上げました。同社は、新しいオンライン プレゼンスを利用して、DIY で家をリフォームする人々が塗料を購入する方法を合理化しようと計画しています。

あなたの同僚が、ユーザーの次の作業を手伝うエージェント「Paint Agent」の開発に着手しました。

• Cymbal Shops の塗料製品データシートに基づいて塗料製品を選択する
• 選択した商品ラインから色を選択する
• 部屋の寸法から必要な塗料の量を割り出す
• 選択したオプションに基づいて価格を計算する

しかし、同僚はバグに行き詰まり、そのまま退職してしまいました。

あなたは Cymbal Shops の新しい ML エンジニアです。Paint Agent のデプロイを完了させるという任務を託されました。エージェントは次のように構成されています。

タスク 1. 塗料製品情報用のエージェント検索アプリを作成する

このタスクでは、エージェント検索データストアをデプロイします。このデータストアは、Cymbal Shops の塗料について説明したデータシート（シークレット ウィンドウのタブを使用して https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf でプレビューできます）をインポートします。このデータシートは、ユーザーからの塗料についての質問に対するグラウンディング データソースとして使用されます。

データストアと検索アプリにより、エージェントは組織のコンテンツをすばやく見つけることができます。その後、その情報を使用して、データに基づいてユーザーに適切な回答を提供できます。

1. Google Cloud コンソールで、[Agent Platform] > [エージェント] > [検索] に移動します。

2. 次の構成でエージェント検索アプリを作成します。

   フィールド	値
   アプリの種類	カスタム検索（一般）
   アプリ名	Paint Search
   会社名	Cymbal Shops
   ロケーション	グローバル

3. 次の構成でエージェント検索データストアを作成します。

   フィールド	値
   データソース	Cloud Storage
   データ型	ドキュメント
   フォルダまたはファイル	ファイル
   インポートするファイル	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   ロケーション	グローバル
   データストア名	Cymbal Paint
   ドキュメント パーサー	レイアウト パーサー
   表のアノテーションを有効にする	有効
   チャンクに上位の見出しを含める	有効

4. アプリとデータストアの両方で、[料金モデル] として [全般] を選択します。

[進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 データストアと検索アプリを作成する。

タスク 2. ADK をインストールして環境を設定する

このラボ環境では、Agent Platform API が有効になっています。ご自身のプロジェクトでこれらの手順を行う場合は、Agent Platform に移動し、プロンプトに沿って有効にしてください。

Cloud Shell エディタタブを準備する

1. Google Cloud コンソールのタイトルバーで、[Cloud Shell をアクティブにする]（）をクリックします。

   注: または、コンソールのブラウザタブを選択し、G キー、S キーの順に押して Cloud Shell ターミナルを開きます。

2. [続行] をクリックします。

3. Cloud Shell を承認するよう求められたら、[承認] をクリックします。

4. Cloud Shell ターミナル パネルの右上にある「新しいウィンドウで開く」ボタン（）をクリックします。

5. ペインの上部にある [エディタを開く]（鉛筆アイコン ）をクリックしてファイルを表示します。

6. 左側のナビゲーション メニューの上部にあるエクスプローラ アイコン（）をクリックして、ファイル エクスプローラを開きます。

7. [Open Folder] ボタンをクリックします。

8. 表示された [Open Folder] ダイアログで [OK] をクリックし、Qwiklabs 受講者アカウントのホームフォルダを選択します。

9. 画面の右側に表示される追加のチュートリアルや Gemini のパネルを閉じると、コードエディタのウィンドウをより広く使用できます。

10. このラボの残りの部分では、このウィンドウを Cloud Shell エディタと Cloud Shell ターミナルを備えた IDE として使用できます。

ADK とこのラボ用のコードサンプルをダウンロードしてインストールする

1. 次のコマンドを Cloud Shell ターミナルに貼り付けて、Cloud Storage バケットからファイルをコピーし、このラボ用のコードが入ったプロジェクト ディレクトリを作成します。

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null
2. gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null
   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1
3. Cloud Shell ターミナルで次のコマンドを実行して、PATH 環境変数を更新し、ADK とその他のラボ要件をインストールします。

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. 次のコマンドをテキスト ファイルにコピーします。SEARCH_ENGINE_ID の値を YOUR_ID から、先ほど作成した検索エンジンの ID（paint-search_1756... のような形式で、[Agent Platform] > [エージェント] > [検索] のアプリリストに表示されます）に更新します。

5. cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF
   cp .env paint_agent/.env
編集したコマンドを Cloud Shell ターミナルで実行して、モデルの認証と構成のための変数を含む .env ファイルを作成します。[注: ピリオドで始まる隠しファイルを表示するには、Cloud Shell エディタのメニューで [表示] > [隠しファイルを切り替える] を有効にしてください]

.env ファイルをエージェント ディレクトリにコピーして、エージェントがデプロイされたら必要になる認証構成情報をエージェントに提供します。

cp .env paint_agent/.env

タスク 3. Paint Agent をデバッグする

adk run paint_agent
6. 同僚は Paint Agent の構築を始めたものの、行き詰まってしまいました。このエージェントを完成させてデプロイするには、残されたバグを修正するなど、同僚が中断した作業を再開する必要があります。
   hello
   yes

   Cloud Shell ターミナルで、次のコマンドを使用して現在のバージョンのエージェントを実行します。

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   adk run paint_agent

7. [user]: プロンプトが表示されたら、次のように入力します。

8. 続けて、エージェントから Cymbal Shops の塗料について詳しく知りたいですかと尋ねられたら、次のように返事します。

   はい

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   これから、このエラーを解決していきます。

9. adk_challenge_lab/paint_agent/agent.py ファイルを開き、root_agent が使用しているサブエージェントとツールのリストを確認します。サブエージェントが含まれていることに注目してください。サブエージェントへの転送によって暗黙的な transfer_to_agent ツールが呼び出されます。

   root_agent のツールは検索ツールではないため、少なくとも 1 つのサブエージェントが検索ツールを呼び出す必要があります。
   sub_agents ディレクトリにあるサブエージェントを調べて、使用されている検索ツール（この場合は VertexAiSearchTool）を見つけます。
   • https://github.com/google/adk-python/blob/main/src/google/adk/tools/vertex_ai_search_tool.py
   • 理解度チェック:（解答は先に進むと明らかになります）:

10. 1 つのエージェント内で検索ツールと他の非検索ツールを組み合わせて使用することはできません（このケースのようにサブエージェントの中で使用している場合でも同様です）。ただし、ADK には、検索ツールを使用する孤立したエージェントをラップできる AgentTool というツールが用意されています。ラップすると、そのエージェントをツールとして扱い、他のツールと組み合わせて使用することができます。

11. https://github.com/google/adk-python/blob/main/src/google/adk/tools/agent_tool.py

    root_agent のファイル adk_challenge_lab/paint_agent/agent.py に戻り、root_agent のツールリストに AgentTool() を追加します。この AgentTool() に次の引数を渡します。

    agent: この引数には、search_agent（先ほど調べた検索ツールを使用しているサブエージェント）を設定する必要があります。

    skip_summarization: この引数は、False に設定する必要があります。これは、検索ツールが返した内容をエージェントに報告させるためです。

12. 問題のサブエージェントを sub_agents リストから削除します。

    adk run paint_agent

13. ファイルを保存します。
    注: 必ず、データストアが作成され、ドキュメントのインデックスが作成された後に、この先に進んでください。このステータスは、[Agent Platform] > [エージェント] > [検索] > [データストア] > [Cymbal Paint] データストアの [ドキュメント] タブでモニタリングできます。

    実際には、ステータスが [Ready] になった後に数分待ってからエージェントに対してクエリを実行すると、より信頼性の高い出力が得られます。

14. Cloud Shell ターミナルで、次のコマンドを使用してエージェントをもう一度実行します。

    adk run paint_agent

これで、エージェントとチャットして、Cymbal Shops の塗料に関する情報を取得できるようになりました。

エージェントに EcoGreens と Forever Paint の価格を教えてもらいます。

1. 価格はそれぞれ 35 ユーロと 40 ユーロになります。

   
   

2. [進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 エージェントをデバッグする。

3. コマンドライン インターフェースでエージェントとの会話が終了したら、「exit」と入力して終了します。

4. タスク 4. 共有する state を保存して利用する

   root_agent は adk_challenge_lab/paint_agent/tools.py から set_session_value ツールをインポートして使用します。ユーザーから SELECTED_PAINT や COVERAGE_RATE などの情報を収集し、セッションに保存して、マルチターン チャットで使用することを目的としています。ただし、完全には実装されていません。

5. adk_challenge_lab/paint_agent/tools.py ファイルの set_session_value 関数を更新して、ToolContext の state ディクショナリに key と value のペアを保存します。

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

6. 関数のレスポンスを更新して、ステータス メッセージ「f"stored '{value}' in '{key}'"」を返すようにします。

7. coverage_calculator_agent（root_agent のサブエージェントである room_planner のサブエージェント）に関連付けられている agent.py ファイルを開きます。

   これで、エージェントと次の会話ができるようになります。エージェントの回答[Cymbal Shops の塗料に関する情報を提供すると伝えます][Project Paint、EcoGreens、SureCoverage、Forever Paint などの塗料製品に関する情報を提供します。][[State] タブに、更新された state 値が表示されます。部屋数と各部屋の名前を尋ねます。][オフィスに使う色を選択するよう求めます。]

   エージェントへの指示で、state ディクショナリの値が正しく読み込まれていないことに注目してください。指示を更新して、すべて大文字で表記した用語を削除し、ADK のキー テンプレートを使用して state 値を指示に読み込むように変更します。state キーが設定される前にエージェントが呼び出された場合にエージェントがクラッシュしないように、オプションの構文（{SELECTED_PAINT?} など）を使用します。	https://google.github.io/adk-docs/sessions/state/#using-key-templating	次のコマンドを実行してエージェントをテストします。	adk web --allow_origins "regex:https://.*\.cloudshell\.dev"	paint_agent を選択します。
   あなた
   こんにちは
   はい
   EcoGreens を使いたいのですが
   オフィスの一室だけです

8. ディープ オーシャンにします

   [部屋の寸法を尋ねます。]

9. 3 m × 4 m で、高さは 3 m です。ドアが 1 つ、窓が 2 つあります。

   [何回塗りにするのか確認します。]

2 回塗りにします。

[74 平方メートルの塗料が必要であることを計算します。]

注: 製品の画像が正しく表示されるようにするには、ブラウザの設定でこのドメインのサードパーティ Cookie を有効にして、ページを更新してください。

cd ~/adk_challenge_lab

11. エージェントとの会話が終わったら、開発 UI のブラウザタブを閉じます。

    [進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 セッションの state を設定して利用する

    	Cloud Shell ターミナル パネルを選択し、Ctrl+C キーを押してサーバーをシャットダウンします。

タスク 5. Agent Runtime にデプロイする Cloud Shell ターミナルで、adk_challenge_lab ディレクトリに移動します。
15. cd ~/adk_challenge_lab

16. adk deploy agent_engine コマンドを使用して、エージェントを Agent Runtime にデプロイします。エージェント ディレクトリを最後の位置引数として含める必要があります（現在そのディレクトリにいる場合など）。次の引数を使用します。

    パラメータ

引数
--display_name
17. "Paint Agent"
    agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')
18. 注: デプロイ コマンドが完了するまでに 5～10 分かかることがあります。
    cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

    エージェントのデプロイ時に、 サービス アカウントに対して、Agent Platform ユーザーと Discovery Engine ユーザーの IAM ロールを付与します。

    2025-08-25 12:30:00 - Your app is available at http://localhost:8000

19. デプロイが完了すると、デプロイしたエージェントのリソース名がコンソールに出力されます。

20. [進行状況を確認] をクリックして、目標に沿って進んでいることを確認します。 Agent Runtime にデプロイする

タスク 6. デプロイしたエージェントに対してクエリを実行するファイル adk_challenge_lab/chainlit_ui/app.py で、次の行を見つけて、デプロイしたエージェントのリソース名に更新し、リモート エージェントが読み込まれるようにします。次のコマンドを使用して UI を実行します。 2025-08-25 12:30:00 - Your app is available at http://localhost:8000 あなたこんにちははいForever Paint を使いたいのですが部屋は 2 つです。リビングルームと子ども部屋です。子ども部屋は「Sunlight through a canvas tent」、リビングルームは「Coffee Cream」にします。

		agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')		cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py	想定される出力:		http://localhost:8000 のリンクをクリックして、新しいブラウザタブで開きます。	デプロイしたエージェントと次の会話をします。
エージェントの回答
[Cymbal Shops の塗料に関する情報を提供すると伝えます]
[Project Paint、EcoGreens、SureCoverage、Forever Paint などの塗料製品に関する情報を提供します。]
[部屋数と各部屋の名前を尋ねます。]
[リビングルームと子ども部屋に使う色を選択するよう求めます。]

[部屋の寸法を尋ねます]

リビングルームは 5 m × 4 m で、高さは 2.5 m です。ドアが 1 つ、窓が 3 つあります。

[塗装回数を尋ねます。]

2 回塗りにします。

[子ども部屋の寸法を尋ねます。]

子ども部屋は 3 m × 3 m で、高さは 2.5 m です。ドアが 1 つ、窓が 1 つあります。

[1 回塗りの場合の見積もり額を伝え、塗装回数を確認します。]

どちらも 2 回塗りにします。

[リビングルームには 77 平方メートル、子ども部屋には 53 平方メートルの塗料が必要であることを計算します。]

エージェントと新しい会話を開始するには、左上のアイコンをクリックして [Create a New Chat] を選択します。