Create a data store and search app

Підтвердити виконання

/ 15

Debug your agent

Підтвердити виконання

/ 25

Set and utilize session state

Підтвердити виконання

/ 25

Deploy to Agent Runtime

Підтвердити виконання

/ 25

Configure a frontend to query your agent

Підтвердити виконання

/ 10

This lab may incorporate AI tools to support your learning.
This content is not yet optimized for mobile devices.
For the best experience, please visit us on a desktop computer using a link sent by email.
Google Cloud self-paced labs

Lab Information

Lab Manual Last Updated Date November 18, 2026
Last Tested Date and Time November 18, 2026, 05:06:22
Completion in Last 24 Hours 678

Overview

In this challenge lab, you demonstrate your ability to author and debug multi-agent applications using Agent Development Kit (ADK), ground an agent with an Agent Search data store, share session state across sub-agents, deploy your agent to Agent Runtime, configure service agent IAM permissions, and query your deployed agent from a Chainlit web app.

In a challenge lab you’re given a scenario and a set of tasks. Instead of following step-by-step instructions, you will use the skills learned from the labs in the quest to figure out how to complete the tasks on your own! An automated scoring system (shown on this page) will provide feedback on whether you have completed your tasks correctly.

When you take a challenge lab, you will not be taught new Google Cloud concepts. You are expected to extend your learned skills, like changing default values and reading and researching error messages to fix your own mistakes.

To score 100% you must successfully complete all tasks within the time period!

Simulated Console

In this lab you will use a simulated version of the Google Cloud Console. This allows you to:

  • Skip waiting for deployments and data ingestion by 'jumping ahead' in time to deployed, active services.
  • Be guided step-by-step within the simulated console window without needing to refer back to a separate lab instructions tab.

Objectives

In this lab, you:

  • Create an Agent Search data store and search app grounded on Cymbal Shops' paint product datasheet.
  • Build and debug an agent with Agent Development Kit (ADK) made up of a root agent and sub-agents.
  • Enable agents with an Agent Search tool (AgentTool) alongside Python function tools.
  • Store agent output in ToolContext.state and retrieve values using optional session state key templating.
  • Deploy your agent to Agent Runtime and grant least-privilege IAM roles to the AI Platform Reasoning Engine Service Agent.
  • Query the agent deployed to Agent Runtime through a Chainlit frontend.

Challenge scenario

Cymbal Shops logo

Cymbal Shops is an American retail chain headquartered in Minneapolis that sells housewares, electronics, and clothing.

Cymbal Shops has expanded into Europe and launched a new Paint Department. It plans to use its online presence to streamline how people shop for paint for DIY home renovation projects.

A coworker began developing Paint Agent to help customers:

  • Select a paint product based on Cymbal Shops' paint product datasheets (Cymbal_Shops_Paint_Datasheets.pdf).
  • Choose colors from the selected product line.
  • Determine how much paint is needed from room dimensions.
  • Calculate total bucket count and price based on the selected options.

Your coworker got stuck on a bug and left the organization. As a new ML Engineer at Cymbal Shops, you are tasked with completing and deploying Paint Agent:

Architecture diagram of Paint Agent

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources are made available to you.

This hands-on lab lets you do the lab activities in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

  • Access to a standard internet browser (Chrome browser recommended).
Note: Use an Incognito (recommended) or private browser window to run this lab. This prevents conflicts between your personal account and the student account, which may cause extra charges incurred to your personal account.
  • Time to complete the lab—remember, once you start, you cannot pause a lab.
Note: Use only the student account for this lab. If you use a different Google Cloud account, you may incur charges to that account.

Sign in to the Simulated Google Cloud Console

During lab startup, Terraform provisioned a dedicated Cloud Run service (console-simulator) in your Google Cloud project () that hosts the simulated Google Cloud console, Cloud Shell Editor and Terminal, ADK Dev UI, and Chainlit web app, and records your task progress for grading.

  1. Copy the Open Simulated Cloud Console URL from the left-hand lab panel and open it in a new browser tab:

    Notice the companion Lab Steps panel on the right side of the simulator window, which tracks your steps across all tasks and provides click-to-copy values.

  2. On the Sign in to your lab's simulated console page, sign in with your assigned Qwiklabs student credentials:

    • Email or username:
    • Password:
  3. Click Sign in.

  4. In the Welcome dialog inside the Simulated Cloud Console, select I agree to the Google Cloud Platform Terms of Service, click Agree and continue.

  5. Select your assigned project .

Task 1. Create an Agent Search app for paint product info

In this task, you deploy an Agent Search data store and search app inside the Simulated Cloud Console to import Cymbal Shops' paint datasheet (Cymbal_Shops_Paint_Datasheets.pdf) as the grounding data source for queries about Cymbal Shops paints.

  1. In the Google Cloud console, navigate to Agent Platform > Agents > Search & RAG, then click Search App.

  2. On the Agent Search page, click Create on the Custom search (general) card, configure your Search app with the following settings, and click Continue to proceed to 3 Data:

    Field Value
    App type Custom search (general)
    App name Paint Search
    Company name Cymbal Shops
    Location global (Global)
  3. Click + Create Data Store and configure your Agent Search data store with the following settings:

    Field Value
    Data source Cloud Storage (Add data source)
    Data type Documents
    Folder or File File
    File to import -bucket/Cymbal_Shops_Paint_Datasheets.pdf
    Location global
    Data store name Cymbal Paint
    Document parser Layout Parser (expand Document processing options)
    Enable table annotation Enabled
    Include ancestor headings in chunks Enabled
    Pricing model General pricing (click Create)
  4. Back on Create Search App > 3 Data, ensure the Cymbal Paint data store checkbox is selected and click Continue.

  5. On 4 Pricing, keep General pricing selected and click Create to launch your Paint Search app.

Click Check my progress to verify the objective. Create a data store and search app

Task 2. Install ADK and set up your environment

  1. Click Activate Cloud Shell (>_) in the top-right bar of the Simulated Cloud Console, click Authorize in the Authorize Cloud Shell dialog, and click Open in new window (Open in new window button) in the upper-right corner of the Cloud Shell panel to launch the standalone Cloud Shell tab.

  2. On the Cloud Shell Editor Welcome tab, click Open Home Directory (or select File > Open Home Directory) to open your home directory in the Explorer.

  3. Run the following command in the Cloud Shell Terminal to copy the starter files from Cloud Storage:

    gcloud storage cp -r gs://{{{project_0.project_id}}}-bucket/adk_challenge_lab .
  4. Update your PATH environment variable and install chainlit and the ADK project requirements in the Cloud Shell Terminal:

    export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install chainlit==2.11.1 python3 -m pip install -r adk_challenge_lab/requirements.txt
  5. Copy the following commands to a text file, replace YOUR_ID with the ID of the Paint Search app you created in Task 1 (found in AI Applications > Apps inside the Simulated Cloud Console), and run the edited commands in the Cloud Shell Terminal to create ~/adk_challenge_lab/.env:

    cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id}}} GOOGLE_CLOUD_LOCATION={{{project_0.startup_script.gcp_region}}} RESOURCES_BUCKET={{{project_0.project_id}}}-bucket MODEL=gemini-3.8-flash SEARCH_ENGINE_ID=YOUR_ID EOF

    Note: To view hidden files beginning with a period (such as .env) in Cloud Shell Editor, select View > Toggle Hidden Files in the editor menu bar.

  6. Copy .env into the paint_agent directory so your agent includes its configuration once deployed:

    cp .env paint_agent/.env

Task 3. Debug the Paint Agent

  1. In the Cloud Shell Terminal (~/adk_challenge_lab), run the current version of the agent:

    adk run paint_agent
  2. When the [user]: prompt appears, enter hello and then yes. Observe the error output:

    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'}}
  3. Open adk_challenge_lab/paint_agent/agent.py and explore paint_agent/sub_agents/ in Cloud Shell Editor to uncover which sub-agent invokes VertexAiSearchTool.

  4. Because a search tool cannot be combined directly with non-search tools (including implicit transfer_to_agent sub-agent transfers), ADK provides AgentTool to wrap an isolated search agent as a tool:

    • In adk_challenge_lab/paint_agent/agent.py, wrap that isolated search sub-agent in an AgentTool() inside root_agent's tools list, setting agent to the sub-agent you uncovered and skip_summarization to False.
    • Remove that sub-agent from root_agent's sub_agents list.
  5. In the Cloud Shell Terminal, run adk run paint_agent again, ask the agent for the prices of EcoGreens and Forever Paint (for example, What are the prices of EcoGreens and Forever Paint?, verifying they are €35.00 and €40.00 per 2.5L container), and then type exit to end the CLI conversation.

Click Check my progress to verify the objective. Debug your agent

Task 4. Save and utilize shared state

Your root_agent imports and uses set_session_value from adk_challenge_lab/paint_agent/tools.py to store SELECTED_PAINT, COVERAGE_RATE, and PRICE in the session state dictionary, but it is not yet implemented.

  1. Open adk_challenge_lab/paint_agent/tools.py in Cloud Shell Editor:

    • Store key-value pairs in tool_context's state dictionary.
    • Update the return value to return a dictionary where key 'status' has value f"stored '{value}' in '{key}'" ({"status": f"stored '{value}' in '{key}'"}).
  2. Open adk_challenge_lab/paint_agent/sub_agents/room_planner/sub_agents/coverage_calculator/agent.py:

    • Update its instruction to replace the ALL CAPS placeholders (COVERAGE_RATE and PRICE) with ADK optional key templating syntax (for example, {SELECTED_PAINT?}) so the agent loads session state values safely.
  3. Launch the ADK Dev UI from ~/adk_challenge_lab (--allow_origins allows Cloud Shell's dynamic *.cloudshell.dev Web Preview proxy origin to communicate with the local ADK server):

    adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
  4. Click http://127.0.0.1:8000 in the terminal output (or Web Preview > Preview on port 8000), click Select an app and choose paint_agent, and have the following conversation:

    You Agent Response
    hello Offers to share information about Cymbal Shops' paints.
    yes Shares information about EcoGreens, Forever Paint, Project Paint, and SureCoverage.
    I'd like to use EcoGreens Updates the State tab (SELECTED_PAINT, COVERAGE_RATE, PRICE), renders the EcoGreens swatches, and asks how many rooms and their names.
    Just one room, my office Asks you to select a color for your office.
    Deep Ocean Transfers to coverage_calculator_agent and asks for room dimensions.
    3m by 4m. 3m high. 1 door, 2 windows. Estimates 37 square meters for one coat and asks to confirm two coats.
    Two coats. Calculates 74 square meters (7.4 liters, 3 buckets, 105.00 €).
  5. Switch back to the Cloud Shell tab and press Ctrl+C (or click Stop Server (Ctrl+C)) to shut down the server.

Click Check my progress to verify the objective. Set and utilize session state

Task 5. Deploy to Agent Runtime

  1. In the Cloud Shell Terminal, verify you are in ~/adk_challenge_lab:

    cd ~/adk_challenge_lab
  2. Deploy Paint Agent to Agent Runtime using adk deploy agent_engine with the following arguments:

    Parameter Argument
    --display_name "Paint Agent"
    Final positional argument The directory of the agent you are deploying
  3. Switch to the Google Cloud console tab inside the simulator and navigate to IAM & Admin > IAM:

    • Select Include Google-provided role grants.
    • Click the Edit principal (pencil) icon on (AI Platform Reasoning Engine Service Agent — be careful not to select the lookalike gcp-sa-aiplatform Vertex AI Service Agent without -re!).
    • Click + Add another role to grant both Agent Platform User and Discovery Engine User, then click Save.
  4. Return to Cloud Shell and note the deployed agent engine resource name (projects/.../locations/<REGION>/reasoningEngines/...) printed to the terminal.

Click Check my progress to verify the objective. Deploy to Agent Runtime

Task 6. Query the deployed agent

  1. In Cloud Shell Editor, open adk_challenge_lab/chainlit_ui/app.py and replace YOUR_AGENT_RESOURCE_NAME in the line below with your deployed agent's resource name from the Cloud Shell Terminal output:

    agent = client.agent_engines.get(name="YOUR_AGENT_RESOURCE_NAME")
  2. Run the Chainlit frontend from ~/adk_challenge_lab/chainlit_ui:

    cd ~/adk_challenge_lab/chainlit_ui python3 -m pip install opentelemetry-exporter-otlp-proto-grpc==1.41.1 chainlit run app.py
  3. Click http://localhost:8000 in the terminal output to open the Cymbal Shops Paint Dept. tab, and have the following conversation with your deployed agent:

    You Agent Response
    hello Offers to share information about Cymbal Shops' paints.
    yes Shares information about EcoGreens, Forever Paint, Project Paint, and SureCoverage.
    I'd like to use Forever Paint Displays the Forever Paint color swatches and asks how many rooms and their names.
    Two rooms. The living room and a baby's room. Asks you to pick a color for each room.
    "Sunlight through a canvas tent" for the baby's room and "Coffee Cream" for the living room. Requests dimensions for the living room.
    The living room is 5m by 4m. 2.5m high. 1 door, 3 windows. Estimates 38.5 square meters for one coat and asks how many coats to apply.
    Always two coats. Calculates 77 square meters (4 buckets, €160.00) for the living room, notes your two-coat preference, and requests dimensions for the baby's room.
    The baby's room is 3m by 3m. 2.5m high. 1 door, 1 window. Calculates 26.5 square meters for one coat and 53 square meters (3 buckets, €120.00) for two coats (7 buckets / €280.00 total).

Click Check my progress to verify the objective. Configure a frontend to query your agent

Congratulations!

In this lab, you have:

  • Created an Agent Search data store and search app grounded on Cymbal Shops' paint datasheet.
  • Built and debugged an agent with Agent Development Kit (ADK) using AgentTool alongside Python function tools.
  • Stored agent output in a session state dictionary and retrieved values using optional key templating.
  • Deployed your agent to Agent Runtime and granted least-privilege IAM roles to the AI Platform Reasoning Engine Service Agent.
  • Queried the deployed agent from a Chainlit web application.

End your lab

When you have completed your lab, click End Lab. Qwiklabs removes the resources you’ve used and cleans the account for you.

You will be given an opportunity to rate the lab experience. Select the applicable number of stars, type a comment, and then click Submit.

The number of stars indicates the following:

  • 1 star = Very dissatisfied
  • 2 stars = Dissatisfied
  • 3 stars = Neutral
  • 4 stars = Satisfied
  • 5 stars = Very satisfied

You can close the dialog box if you don't want to provide feedback.

For feedback, suggestions, or corrections, please use the Support tab.

Copyright 2026 Google LLC. All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.

Before you begin

  1. Labs create a Google Cloud project and resources for a fixed time
  2. Labs have a time limit and no pause feature. If you end the lab, you'll have to restart from the beginning.
  3. On the top left of your screen, click Start lab to begin

Use private browsing

  1. Copy the provided Username and Password for the lab
  2. Click Open console in private mode

Sign in to the Console

  1. Sign in using your lab credentials. Using other credentials might cause errors or incur charges.
  2. Accept the terms, and skip the recovery resource page
  3. Don't click End lab unless you've finished the lab or want to restart it, as it will clear your work and remove the project

This content is not currently available

We can notify you via email when it becomes available

Great!

We can contact you via email if it becomes available

One lab at a time

Confirm to end all existing labs and start this one

Use private browsing to run the lab

Using an Incognito or private browser window is the best way to run this lab. This prevents any conflicts between your personal account and the Student account, which may cause extra charges incurred to your personal account.