From Prototypes to Agents with ADK

From Prototypes to Agents with ADK

About this codelab

Last updated Jun 12, 2025

Written by Author: Abirami Sukumaran

1. Overview

Where does building with AI start today? Well for most of us, it often starts with a simple question, "Can the model actually help solve this problem I have been thinking about?". That's exactly where Google AI Studio comes in. It's a place where you can rapidly prototype anything. I've been wanting to remodel my kitchen and I bet Gemini can help - but I'm an engineer, not a general contractor. I'm not even sure what to ask for - there's so much to consider: regulations, fixtures etc. So let's break this down and have Gemini generate a super detailed prompt for us, then generate a full renovation plan and also visualize the remodel! But wait. How can I actually help businesses scale, from here? Enter AGENTS!!!

An agent is an autonomous program that talks to an AI model to perform a goal-based operation using the tools and context it has and is capable of autonomous decision making grounded in truth!

The Agent Development Kit (ADK)

Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. ADK supports building sophisticated applications by composing multiple, distinct agent instances into a Multi-Agent System (MAS).

In ADK, a multi-agent system is an application where different agents, often forming a hierarchy, collaborate or coordinate to achieve a larger goal. Structuring your application this way offers significant advantages, including enhanced modularity, specialization, reusability, maintainability, and the ability to define structured control flows using dedicated workflow agents.

What you'll build

Ready to move from our prototype PROMPT to Building an agent??? We'll create an agent to help generate the proposal document for the kitchen renovation project. As part of this lab, you will:

1. Build a simple agent to generate Renovation Proposal Document with ADK
2. Store the generated Renovation Proposal Document in a Cloud Storage Bucket
3. Test the agent in Cloud Shell and in agent web output

Requirements

• A browser, such as Chrome or Firefox
• A Google Cloud project with billing enabled.

2. Before you begin

Create a project

1. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project .
3. Also if you are reading this and would like to get some credits to help you get started with Google Cloud and to use ADK, use this link to redeem credits.
4. You can follow the instructions here to redeem it. Please note that this link is valid only till July 15, 2025 for redemption.
5. Activate Cloud Shell by clicking this link. You can toggle between Cloud Shell Terminal (for running cloud commands) and Editor (for building projects) by clicking on the corresponding button from Cloud Shell.
6. Once connected to Cloud Shell, you check that you're already authenticated and that the project is set to your project ID using the following command:

gcloud auth list

5. Run the following command in Cloud Shell to confirm that the gcloud command knows about your project.

gcloud config list project

6. If your project is not set, use the following command to set it:

gcloud config set project <YOUR_PROJECT_ID>

7. Make sure to have Python 3.9+

Refer documentation for other gcloud commands and usage.

3. Prototype

Go to Google AI Studio. Start typing in your prompt. Here's my prompt:

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.

Adjust & configure the parameters on the right hand side to get optimal response.

Based on this simple description, Gemini made me an incredibly detailed prompt to kick off my renovation! In effect, we're using Gemini to get even better responses out of AI Studio and our models. You can also select different models to use, based on your use case.

We have chosen Gemini 2.5 Pro. This is a Thinking model, which means that we get even more output tokens, in this case up to 65K tokens, for long-form analyses and detailed docs. The Gemini thinking box comes when you enable Gemini 2.5 Pro which has native reasoning capabilities and can take in long context requests.

See the snippet of the response below:

AI Studio analyzed my data and produced all these things like cabinets, countertops, backsplash, flooring, sink, cohesion, color palette, and material selection. Gemini is even citing sources!

Now try to see the idea come to life with a different prompt.

1. Copy this prompt and paste it in the prompt editor:

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

2. Attach an image of your current kitchen (or you can use my sample kitchen image).
3. Change the model to "Gemini 2.0 Flash Preview Image Generation" so you have access to generate images.

I got this output:

That's the power of Gemini!

From understanding videos, to native image generation, to grounding real information with Google Search – there are things that can only be built with Gemini.

From the AI Studio, you can take this prototype, grab the API key, and scale it into a full agentic application using the power of Vertex AI ADK.

4. ADK setup

Now lets move to the Cloud Shell Terminal we activated in the "Before you begin" section:

1. Create & Activate Virtual Environment (Recommended)

From your Cloud Shell Terminal, create a Virtual Environment:

python -m venv .venv

Activate the Virtual Environment:

source .venv/bin/activate

2. Install ADK

pip install google-adk

5. Project Structure

3. From Cloud Shell Terminal, create a root directory for your agentic apps in your desired project location:

mkdir agentic-apps

4. Inside the main directory, create one folder specific to our current project:

mkdir renovation-agent

5. Go to Cloud Shell editor and create the following project structure by creating the files (empty to begin with):

renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Source Code

6. Go to "init.py"and update with the following content:

from . import agent

7. Go to agent.py and update the file with following content from the following path:

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py

In agent.py, we import necessary dependencies, retrieve configuration parameters from the .env file and define the root_agent which generates a proposal document and stores it in a Cloud Storage Bucket. To do the Cloud Storage step, we use a tool called store_pdf.

8. Make sure you have the Cloud Storage Bucket

This is to store the proposal document that the agent generates. Create it and provision access so the agentic system we create with Vertex AI can access it. Here is how you can do it:

https://cloud.google.com/storage/docs/creating-buckets#console

Name your bucket "next-demo-store". If you name it something else, remember to update the value of STORAGE_BUCKET in the .env file (in the ENV Variables Setup step).

9. To set up access to the bucket, go to the Cloud Storage console and to your Storage Bucket (in our case the bucket name is "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.

Navigate to Permissions -> View Principals -> Grant Access. Select Principals as "allUsers" and Role as "Storage Object User".

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.

10. Create dependencies list

List all dependencies in requirements.txt. You can copy this from repo.

Single agent System Source Code Explanation

The agent.py file defines the structure and behavior of our kitchen renovation multi-agent system using the Agent Development Kit (ADK). Let's break down the key components:

Agent Definition

Root Agent (Orchestrator): proposal_agent

The root_agent acts as the orchestrator of this single-agent system. It receives the initial renovation request and determines which tools to invoke based on the request's needs.

The root_agent then collects the responses from the tools and combines them to provide a comprehensive response to the user. In this case we just have one tool "store_pdf".

7. Data Flow & Key Concepts

The user initiates a request through the ADK interface (either the terminal or the web UI).

1. The request is received by the root_agent.
2. The root_agent analyzes the request and routes it to the tool as and when required.
3. The tool "store_pdf" is designed to write the renovated text content to a PDF file, then upload it to Google Cloud Storage.
4. This then returns the response to the root_agent.
5. The root_agent combines the responses and provides a final output to the user.

LLMs (Large Language Models)

The agents rely heavily on LLMs to generate text, answer questions, and perform reasoning tasks. The LLMs are the "brains" behind the agents' ability to understand and respond to user requests. We are using Gemini 2.5 in this application.

Google Cloud Storage

Used to store the generated renovation proposal documents. You need to create a bucket and grant the necessary permissions for the agents to access it.

Cloud Run (Optional)

The OrderingAgent uses a Cloud Run function to interface with AlloyDB. Cloud Run provides a serverless environment to execute code in response to HTTP requests.

AlloyDB

If you're using the OrderingAgent, you'll need to set up an AlloyDB database to store order information.

.env file

The .env file stores sensitive information like API keys, database credentials, and bucket names. It's crucial to keep this file secure and not commit it to your repository. It also stores configuration settings for the agents and your Google Cloud project. The root_agent or supporting functions will typically read values from this file. Make sure all required variables are properly set in the .env file. This includes the Cloud Storage bucket name

8. Model Setup

Your agent's ability to understand user requests and generate responses is powered by a Large Language Model (LLM). Your agent needs to make secure calls to this external LLM service, which requires authentication credentials. Without valid authentication, the LLM service will deny the agent's requests, and the agent will be unable to function.

1. Get an API key from Google AI Studio.
2. In the next step where you set up the .env file, replace <<your API KEY>> with your actual API KEY value.

9. ENV Variables Setup

3. Set up your values for the parameters in the template .env file in this repo. In my case, the .env has these variables:

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>>

Replace placeholders with your values.

10. Run Your Agent

4. Using the terminal, navigate to the parent directory of your agent project:

cd agentic-apps/renovation-agent

5. Install all dependencies

pip install -r requirements.txt

6. You can run the following command in your Cloud Shell terminal to execute the agent:

adk run .

7. You can run the following to run it in an ADK provisioned web UI:

adk web

8. Test with the following prompts:

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.

11. Result

For the command adk run . result is as follows"

...

You can validate if the Renovation Proposal doc is created in the Cloud Storage Bucket.

12. Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this post, follow these steps:

1. In the Google Cloud console, go to the Manage resources page.
2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

13. Congratulations

Congratulations! You have successfully created and interacted with your multi-agent app using ADK! The multi-agent system is designed to streamline the kitchen renovation process by automating tasks such as proposal generation, permit checking, and order status tracking. Each agent has a specific role, and the root_agent coordinates their activities to provide a comprehensive solution. The system leverages LLMs, Google Cloud services, and potentially external APIs to deliver its functionality. Here is a link to the product documentation.