
Before you begin
- Labs create a Google Cloud project and resources for a fixed time
- Labs have a time limit and no pause feature. If you end the lab, you'll have to restart from the beginning.
- On the top left of your screen, click Start lab to begin
Run the agent using the ADK's Web UI
/ 25
Run an agent programmatically
/ 25
Chat with an agent via the command-line interface
/ 25
Preview a multi-agent example
/ 25
Agent Development Kit offers several key advantages for developers building agentic applications:
SequentialAgent
, ParallelAgent
, and LoopAgent
) for predictable pipelines, or leverage LLM-driven dynamic routing (LlmAgent
transfer) for adaptive behavior.While other Gen AI SDKs or agent frameworks also allow you to query models and even empower them with tools, dynamic coordination between multiple models requires a significant amount of work on your end.
Agent Development Kit offers a higher-level framework than these tools, allowing you to easily connect multiple agents to one another for complex but easy-to-maintain workflows.
Additionally, it allows you to deploy these complex systems of agents to a fully-managed endpoint in Agent Engine, so you can focus on the agents' logic while infrastructure is allocated and scaled for you.
In this lab, you will create a single agent that can use a search tool. You will test agents in ADK’s browser UI, from a CLI chat interface, and programmatically from within a script.
You will consider:
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 will be made available to you.
This Qwiklabs hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that you use to sign in and access Google Cloud for the duration of the lab.
To complete this lab, you need:
Note: If you already have your own personal Google Cloud account or project, do not use it for this lab.
Note: If you are using a Pixelbook, open an Incognito window to run this lab.
Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the left is the Lab Details pane with the following:
Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).
The lab spins up resources, and then opens another tab that shows the Sign in page.
Tip: Arrange the tabs in separate windows, side-by-side.
If necessary, copy the Username below and paste it into the Sign in dialog.
You can also find the Username in the Lab Details pane.
Click Next.
Copy the Password below and paste it into the Welcome dialog.
You can also find the Password in the Lab Details pane.
Click Next.
Click through the subsequent pages:
After a few moments, the Google Cloud console opens in this tab.
With your Google Cloud console window selected, open Cloud Shell by pressing the G key and then the S key on your keyboard. Alternatively, you can click the Activate Cloud Shell button () in the upper right of the Cloud console.
Click Continue.
When prompted to authorize Cloud Shell, click Authorize.
In the upper right corner of the Cloud Shell Terminal panel, click the Open in new window button .
In the Cloud Shell Terminal, enter the following to open the Cloud Shell Editor to your home directory:
Update your PATH
environment variable and install ADK by running the following commands in the Cloud Shell Terminal. Note: You will specify the version to ensure that the version of ADK that you install corresponds to the version used in this lab:
Paste the following commands into the Cloud Shell Terminal to copy a file from a Cloud Storage bucket, and unzip it, creating a project directory with code for this lab:
Install additional lab requirements with:
Google ADK is built around a few core concepts that make it powerful and flexible:
Session
), including its history (Events
) and the agent's working memory for that conversation (State
).In the Cloud Shell Editor's file explorer pane, find the adk_project folder. Click it to toggle it open.
This directory contains three other directories: my_google_search_agent, app_agent, and llm_auditor. Each of these directories represents a separate agent. Separating agents into their own directories within a project directory provides organization and allows Agent Development Kit to understand what agents are present.
Click on the my_google_search_agent to explore an agent directory.
Notice that the directory contains an __init__.py
file and an agent.py
file. An __init__.py
file is typically used to identify a directory as a Python package that can be imported by other Python code. Click the init.py file to view its contents.
Notice that the __init__.py
file contains a single line, which imports from the agent.py
file. ADK uses this to identify this directory as an agent package:
Now click on the agent.py
file. This file consists of a simple agent. You will equip it with a powerful tool: the ability to search the internet using Google Search. Notice a few things about the file:
google.adk
: the Agent
class and the google_search
tool from the tools
moduleTo use the imported google_search
tool, it needs to be passed to the agent. Do that by pasting the following line into the agent.py
file where indicated at the end of the Agent
object creation:
Save the file.
Tools enable an agent to perform actions beyond generating text. In this case, the google_search
tool allows the agent to decide when it would like more information than it already has from its training data. It can then write a search query, use Google Search to search the web, and then base its response to the user on the results. When a model bases its response on additional information that it retrieves, it is called "grounding," and this overall process is known as "retrieval-augmented generation" or "RAG."
You can learn more about how to use tools with ADK in the lab Empower ADK agents with tools.
ADK includes a development UI designed to run locally to help you develop and test your agents. It can help you visualize what each agent is doing and how multiple agents interact with one another. You will explore this interface in this task.
When you run an agent, the ADK needs to know who is requesting the model API calls. You can provide this information in one of two ways. You can:
In this lab, you will take the Vertex AI approach.
In the Cloud Shell Editor menus, select View > Toggle Hidden Files to view or hide your hidden files (files with a period at the start of their filename are hidden by default in most file systems). You may need to scroll down in this menu to find the Toggle Hidden Files option.
In the Cloud Shell Editor file explorer pane, navigate to the adk_project/my_google_search_agent directory.
Select the .env file in the my_google_search_agent directory.
Paste these values over what is currently in the file to update the file to include your project ID:
Save the file.
These variables play the following roles:
GOOGLE_GENAI_USE_VERTEXAI=TRUE
indicates that you will use Vertex AI for authentication as opposed to Gemini API key authentication.GOOGLE_CLOUD_PROJECT
and GOOGLE_CLOUD_LOCATION
provide the project and location with which to associate your model calls.MODEL
is not required, but is stored here so that it can be loaded as another environment variable. This can be a convenient way to try different models in different deployment environments.When you test your agent using ADK's dev UI or the command-line chat interface, they will load and use an agent's `.env` file if one is present or else look for environment variables with the same names as those set here.
In the Cloud Shell Terminal, ensure you are in the adk_project directory where your agent subdirectories are located by running:
Launch the Agent Development Kit Dev UI with the following command:
Output
To view the web interface in a new tab, click the http://127.0.0.1:8000 link in the Terminal output, which will link you via proxy to this app running locally on your Cloud Shell instance.
A new browser tab will open with the ADK Dev UI.
From the Select an agent dropdown on the left, select my_google_search_agent.
In the chat input field in the bottom right, begin the conversation with:
The agent should respond. In order to encourage the agent to use its Google Search tool, enter the question:
You will notice from the results that the agent is able to use Google Search to get up-to-date information, rather than having its information stop on the date when its model was trained.
Click the agent icon () next to the agent's response (or an event from the list on the Events pane) to inspect the event returned by the agent, which includes the content
returned to the user and grounding_metadata
which details the search results that the response was based on.
When you are finished exploring the dev UI, close this browser tab and return to your browser tab with the Cloud Shell Terminal, click on the terminal's pane, and press CTRL + C
to stop the web server.
Click Check my progress to verify the objective.
While the dev UI is great for testing and debugging, it is not suitable for presenting your agent to multiple users in production.
To run an agent as part of a larger application, you will need to include a few additional components in your agent.py script that the web app handled for you in the previous task. Proceed with the following steps to open a script with these components to review them.
In the Cloud Shell Terminal run the following commands to export environment variables. You can use this approach to set environment variables for all of your agents to use if they do not have a .env
file in their directory:
In the Cloud Shell Editor file browser, select the adk_project/app_agent directory.
Select the agent.py file in this directory.
This agent is designed to run as part of an application. Read the commented code in agent.py, paying particular attention to the following components in the code:
Component | Feature | Description |
---|---|---|
InMemoryRunner() |
Oversight of agent execution | The Runner is the code responsible for receiving the user's query, passing it to the appropriate agent, receiving the agent's response event and passing it back to the calling application or UI for rendering, and then triggering the following event. You can read more in the ADK documentation about the event loop. |
runner.session_service.create_session() |
Conversation history & shared state | Sessions allow an agent to preserve state, remembering a list of items, the current status of a task, or other 'current' information. This class creates a local session service for simplicity, but in production this could be handled by a database. |
types.Content() and types.Part()
|
Structured, multimodal messages | Instead of a simple string, the agent is passed a Content object which can consist of multiple Parts. This allows for complex messages, including text and multimodal content to be passed to the agent in a specific order. |
Notice that the script includes a hardcoded query, which asks the agent: "What is the capital of France?"
Run the following command in the Cloud Shell Terminal to run this agent programmatically:
Selected Output:
You can also define specific input and/or output schema for an agent.
You will now add imports for the Pydantic schema classes BaseModel
and Field
and use them to define a schema class consisting of just one field, with a key of "capital" and a string value intended for the name of a country's capital city. You can paste these lines into your app_agent/agent.py file, just after your other imports:
Within your root_agent
's Agent
definition, add these parameters to disable transfers (as you are required to do when using an output schema) and to set the output to be generated according to the CountryCapital
schema you defined above:
Run the agent script again to see the response following the output_schema
:
Selected Output:
Click Check my progress to verify the objective.
You can also chat with an agent in your local development environment by using the command line interface. This can be very handy for quickly debugging and testing agents as you develop them.
Like the web interface, the command line interface also handles the creation of the session service, artifact service, and runner for your agent.
To run an interactive session using the command line interface:
Run the following in Cloud Shell Terminal:
Output:
Input the following message:
Example output (yours may be a little different):
When you are finished chatting with the command line interface, enter exit
at the next user prompt to end the chat.
Click Check my progress to verify the objective.
You will learn more about building multi-agent systems in the lab Build multi-agent systems with ADK, but because multi-agent capabilities are core to the Agent Development Kit experience, you can explore one multi-agent system now.
This agentic system evaluates and improves the factual grounding of responses generated by LLMs. It includes:
- a critic_agent
to serve as an automated fact-checker
- a reviser_agent
to rewrite responses if needed to correct inaccuracies based on verified findings
To explore this agent:
To explore this multi-agent system's code, use the Cloud Shell Editor file explorer to navigate to the directory adk_project/llm_auditor.
Within the llm_auditor directory, select the agent.py file.
Here are a few things to notice about this multi-agent example:
SequentialAgent
class. This is an example of a workflow class which passes control of the conversation from one agent to the next in order without awaiting a user turn in-between. When you run the agent, you will see responses from both the critic_agent
and the reviser_agent
, in that order, without waiting for a user turn.sub_agents
directory.__init__.py
and agent.py
files like those you explored in the directory structure earlier, along with a prompt.py
file, which provides a dedicated place for a complete, well-structured prompt to be stored and edited before it is imported into the agent.py
file.Create a .env file for this agent and launch the dev UI again by running the following in the Cloud Shell Terminal:
adk web
session, the default port of 8000 will be blocked, but you can launch the Dev UI with a new port by using adk web --port 8001
, for example.
Click the http://127.0.0.1:8000 link in the Terminal output. A new browser tab will open with the ADK Dev UI.
From the Select an agent dropdown on the left, select llm_auditor.
Start the conversation with the following false statement:
You should see two responses from the agent in the chat area:
critic_agent
checking the truthfulness of the statement based on fact-checking with Google Search.reviser_agent
with a corrected version of your false input statement, for example, "Earth is closer to the Sun than Mars."Next to each response, click on the agent icon () to open the event panel for that response (or find the corresponding numbered event on the Events panel and select it). At the top of the event view, there is a graph that visualizes the relationships between the agents and tools in this multi-agent system. The agent responsible for this response will be highlighted.
Feel free to explore the code further or ask for other fact-checking examples in the dev UI. Another example you can try is:
If you would like to reset the conversation, use the + New Session link at the top right of the ADK Dev UI to restart the conversation.
When you are finished asking questions of this agent, close the browser tab and press CTRL + C in the Terminal to stop the server.
Even though this example uses a SequentialAgent
workflow agent, you can think of this pattern as a human-in-the-loop pattern. When the SequentialAgent
ends its sequence, the conversation goes back to its parent, the llm_auditor
in this example, to get a new input turn from the user and then pass the conversation back around to the other agents.
Click Check my progress to verify the objective.
In this lab, you’ve learned:
To learn more about building and deploying agents using Agent Development Kit, check out these labs:
Find more information about ADK in the documentation and GitHub repository:
adk-docs
GitHub repository adk-docs
...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.
Manual Last Updated May 29, 2025
Lab Last Tested May 29, 2025
Copyright 2023 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.
This content is not currently available
We will notify you via email when it becomes available
Great!
We will contact you via email if it becomes available
One lab at a time
Confirm to end all existing labs and start this one