Building AI Agents with ADK: The Foundation

1. Before you begin

Welcome to the first part of the "Building AI Agents with ADK" series! In this hands-on codelab series, you'll embark on an exciting journey to create your very own intelligent AI agent using Google's Agent Development Kit (ADK).

We'll start with the absolute essentials, guiding you through setting up your development environment and crafting a foundational conversational agent. By the end of this codelab, you'll have built your first interactive AI, ready to be expanded upon in subsequent parts of this series as we transform it into a sophisticated Multi-Agent System (MAS).

You can complete this codelab in either your local environment or on Google Cloud. For the most consistent experience, we recommend using the Cloud Shell from Google Cloud environment. Cloud Shell also provides 5 GB of persistent storage in the $HOME directory. This is useful to store scripts, configuration files, or cloned repositories.

Note: If you choose to work locally, you may require additional setup, installation, and authentication steps, which are not covered by the environment setup section of this lab.

Prerequisites

• An understanding of the Generative AI concepts
• A basic proficiency in Python programming
• Familiarity with command line / terminal

What you'll learn

• How to set up a Python environment
• How to create a simple Personal Assistant Agent using ADK
• How to run, test, and debug the agent

What you'll need

• A working computer and reliable wifi
• A browser, such as Chrome, to access Google Cloud Console
• A Google Cloud Project with billing enabled
• A curious mind and eagerness to learn

2. Introduction

The world of Generative AI (GenAI) is evolving rapidly, and AI Agents are currently a hot topic. An AI agent is a smart computer program designed to act on your behalf, much like a personal assistant. It can perceive its digital environment, make decisions, and take actions to achieve specific goals without direct human control. Think of it as a proactive, autonomous entity that can learn and adapt to get things done.

At its core, an AI agent uses a large language model (LLM) as its "brain" to understand and reason. This allows it to process information from various sources, such as text, images, and sounds. The agent then uses this understanding to create a plan and execute a series of tasks to reach a predefined objective.

You can now easily build your own AI agents, even without deep expertise, due to ready-to-use frameworks like the Agent Development Kit (ADK). We will start this journey by constructing a personal assistant agent to help you with your tasks. Let's begin!

3. Setup Google Cloud Services

Create a Google Cloud Project

This Codelab assumes that you have already created a Google Cloud project with billing enabled. If you don't have a project yet, follow these steps to create one:

Select or Create a Google Cloud Project

• Navigate to the Google Cloud Console.
• At the top, click the project selector dropdown (next to the Google Cloud logo)
• Choose an existing project or create a new one.

Enable Billing

• Ensure that billing is enabled for your selected Google Cloud project.
• You can learn how to check if billing is enabled on a project by following the instructions in the Google Cloud Billing documentation.

Note: Billing must be enabled even for free tier services, as it's the mechanism Google Cloud uses to track resource usage. That being said, you will only be charged if your usage exceeds the free tier limits or if you use paid services.

Configure Cloud Shell

Now let's make sure you're set up correctly within Cloud Shell, a handy command-line interface directly within Google Cloud Console.

Launch Cloud Shell

In the upper right corner of your Google Cloud Console, you'll see an icon that looks like a terminal (>_). Click on it to activate Cloud Shell.

Authorize Access

If prompted, click Authorize to grant Cloud Shell the necessary permissions to interact with your Google Cloud project.

Verify Your Account:

Once Cloud Shell has loaded, let's confirm you're using the correct Google Cloud account. Run the following command:

gcloud auth list

You should see a similar command output in the terminal:

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Switch Accounts (If Necessary):

If the active account isn't the one you intend to use for this Codelab, switch to the correct account using this command, replacing <[e-mail]> with your actual email that you will use for this lab:

gcloud config set account <[e-mail]

Confirm Your Project

Next, let's verify that Cloud Shell is configured to use the correct Google Cloud Project. Run:

gcloud config list project

You'll see a configuration list. Look for the [core] section, and ensure the project value matches the ID of the Google Cloud Project you want to use for this Codelab:

[core]
project = <current-project-id>

Set Your Project (If Necessary)

If the project ID value is incorrect, set it to your desired project using the following command:

gcloud config set project <your-desired-project-id>

Enable required APIs

To use Google Cloud services, you must first activate their respective APIs for your project. Running the commands below in the Cloud Shell terminal enables all the services that you will need for this Codelab:

gcloud services enable aiplatform.googleapis.com

If the operation was successful, you'll see Operation/... finished successfully printed in your terminal.

4. Create a Python virtual environment

Before starting any Python project, it's good practice to create a virtual environment. This isolates the project's dependencies, preventing conflicts with other projects or the system's global Python packages. Since the Agent Development Kit (ADK) requires Python 3.9 or higher, we'll use a tool like uv to manage both the virtual environment and ensure the correct Python version is used.

uv is a modern, fast, and efficient tool for managing Python projects and environments, combining functionalities traditionally found in tools like pip, venv, pip-tools, and pipx. It's written in Rust for speed.

Cloud Shell already has uv available so we can get started right away.

Verify if uv is installed correctly

uv --version

Create a new project folder for your AI agent

uv init ai-agents-adk
cd ai-agents-adk

Create a virtual environment with Python 3.12

uv venv --python 3.12

Install the Google ADK library within your virtual environment

uv add google-adk

Check if you have install google-adk package successfully

uv pip list | grep google-adk

If you see an output line with google-adk and its version, you are good to proceed to the next step.

5. Create an agent

Now that your development environment is set up and ready, it's time to lay the foundation for your AI agent. The Agent Development Kit (ADK) simplifies this process, requiring just a few essential files to define your agent's core logic and configuration.

These three files work together to make your agent discoverable, runnable, and configurable:

• agent.py: This is the heart of your agent. It contains the primary Python code that defines your agent's behavior, including its name, the large language model (LLM) it uses as its "brain," and the core instructions that guide its responses.
• __init__.py: In Python, the __init__.py file marks a directory as a Python package. For ADK, it's crucial because it helps the framework discover and load your agent definition from agent.py. In simple ADK projects, it often contains a single line to import your agent module, making your agent accessible to the ADK runner.
• .env: This file (short for "environment") is used to store sensitive information and configuration variables that your agent needs, such as API keys, project IDs, and geographical locations. Keeping these details in a separate .env file is a best practice for security and portability, as it prevents hardcoding sensitive data directly into your code. It also allows you to easily change configurations without modifying your main agent logic.

Use the commands below to create these files within a dedicated folder for your personal assistant agent:

uv run adk create personal_assistant

Once the command is executed, you will be asked to choose a few options to configure your agent. For the first step, choose option 1 to use the gemini-2.5-flash model, a fast and efficient model perfect for conversational tasks.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

For the second step, choose Vertex AI (option 2), Google Cloud's powerful, managed AI platform, as the backend service provider.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Lastly, you'll be asked to confirm your Google Cloud project ID and region. If the pre-filled values (current-project-id and current-region) are what you intend to use, just press Enter for each question.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

You should see a similar output in your terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Now, click the Open Editor button at the top of your Cloud Shell window. Clicking that button will take you to the Editor window, which makes it much easier to explore the content of your files. The switch might take a moment; if you're stuck on a loading screen for more than a few minutes, try refreshing your browser.

Note: You're welcome to use a command-line editor like Vim, but you'll need to know the commands to open and exit Vim on your own.

Once the Editor window is fully loaded, navigate to the personal-assistant folder. You will see the necessary files as mentioned above (agent.py, __init__.py, and .env). Let's explore the content.

If you don't see the .env file in the folder, go to the menu bar at the top, click on View, and then select Toggle Hidden Files. This is a common setting as .env files are often hidden by default to prevent accidental exposure.

Let's explore the content of each file.

agent.py

This file instantiates your agent using the Agent class from the google.adk.agents library.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: This line imports the necessary Agent class from the ADK library.
• root_agent = Agent(...): Here, you're creating an instance of your AI agent.
• name="personal_assistant": A unique identifier for your agent. This is how ADK will recognize and refer to your agent.
• model="gemini-2.5-flash": This crucial parameter specifies which Large Language Model (LLM) your agent will use as its underlying "brain" for understanding, reasoning, and generating responses. gemini-2.5-flash is a fast and efficient model suitable for conversational tasks.
• description="...": This provides a concise summary of the agent's purpose or capabilities. The description is more for human understanding or for other agents in a multi-agent system to understand what this particular agent does. It's often used for logging, debugging, or when displaying information about the agent.
• instruction="...": This is the system prompt that guides your agent's behavior and defines its persona. It tells the LLM how it should act and what its primary purpose is. In this case, it establishes the agent as a "helpful assistant." This instruction is key to shaping the agent's conversational style and capabilities.

init.py

This file is necessary for Python to recognize personal-assistant as a package, allowing ADK to correctly import your agent.py file.

from . import agent

• from . import agent: This line performs a relative import, telling Python to look for a module named agent (which corresponds to agent.py) within the current package (personal-assistant). This simple line ensures that when ADK tries to load your personal-assistant agent, it can find and initialize the root_agent defined in agent.py. Even if empty, the presence of __init__.py is what makes the directory a Python package.

.env

This file holds environment-specific configurations and sensitive credentials.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: This tells the ADK that you intend to use Google's Vertex AI service for your Generative AI operations. This is important for leveraging Google Cloud's managed services and advanced models.
• GOOGLE_CLOUD_PROJECT: This variable will hold the unique identifier of your Google Cloud Project. ADK needs this to correctly associate your agent with your cloud resources and to enable billing.
• GOOGLE_CLOUD_LOCATION: This specifies the Google Cloud region where your Vertex AI resources are located (e.g., us-central1). Using the correct location ensures your agent can communicate effectively with the Vertex AI services in that region.

6. Run the agent on the Terminal

With all three files in place, you're ready to run the agent directly from the terminal. To do this, you need to open the Terminal window. Clicking on Terminal in the menu bar, then choosing the New Terminal does the job!

Once the terminal is available, you can start the agent using the adk run command. Since this is a new terminal window and we're using uv, you'll first need to navigate into the ai-agent-adk folder and then prefix the adk run command with uv run.

Type these commands into the terminal:

cd ai-agents-adk
uv run adk run personal_assistant

If everything's set up correctly, you'll see similar output in your terminal.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

Go ahead and chat with the agent! You'll notice the output is sometimes formatted with Markdown, which can be difficult to read in the terminal. In the next step, we'll use the Development UI for a much richer, chat-application-like experience.

7. Run the agent on the Development UI

The Agent Development Kit also offers a convenient way to launch your agent as a chat application using its development UI. Simply use the command adk web instead of adk run.

If you're still in the previous session, just type exit in the terminal to close it. Once the previous session is closed, type the following command in the terminal:

uv run adk web

You should see a similar output in the terminal:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

You have two options to access the development UI:

1. Open via Terminal

• Ctrl + Click or Cmd + Click on the URLs (e.g., http://localhost:8000) from the terminal.

2. Open via Web Preview

• Click the Web Preview button,
• Select Change Port.
• Enter the port number (e.g., 8000)
• Click Change and Preview

You'll then see the chat application-like UI appear in your browser. Go ahead and chat with your personal assistant through this interface! You'll notice that Markdown formatting now displays correctly, and this UI also lets you debug and investigate each messaging event, the agent's state, user requests, and much more. Happy chatting!

8. Clean Up

Since this codelab doesn't involve any long-running products, simply stopping your active agent sessions (e.g., the adk web instance in your terminal) by pressing Ctrl + C in the terminal is sufficient.

Caution: DO NOT proceed with these steps if you plan to continue the codelab series, as they will cause you to repeat some actions in the next codelab.

Delete Agent Project Folders and Files

If you only want to remove the code from your Cloud Shell environment, use the following commands:

cd ~
rm -rf ai-agents-adk

Disable Vertex AI API

To disable the Vertex AI API that was enabled earlier, run this command:

gcloud services disable aiplatform.googleapis.com

Shut Down the Entire Google Cloud Project

If you wish to fully shut down your Google Cloud project, refer to the official guide for detailed instructions.

9. Conclusion

Congratulations! You've successfully built a simple personal assistant agent using the Agent Development Kit (ADK).

As you might have noticed, this personal assistant agent isn't yet very capable (for instance, it can't access the internet for the latest information). In the next codelab of this "Building AI Agents with ADK" series, you'll learn how to empower your personal assistant agent with functions and tools. See you there!