adk

Getting Started with the ADK: Agent Develop Kit

Learn how to build custom agentic applications with Google's Agent Development kit (ADK).

Ryan Bannon

Ryan Bannon

— 7 min read
Getting Started with the ADK: Agent Develop Kit

All code and examples in this post can be found at the szns-adk-a2a GitHub repo

Many of us have become familiar with industry leading LLMs like Gemini over the past few years. These LLMs have demonstrated remarkable capabilities in researching, composing, and transforming data, acting as a personal assistant that can respond to your every command. However, this potential is limited by the time required to craft detailed instructions for the LLM to follow. What if there was a way to automate that as well?

This is where Google’s Agent Development Kit (ADK) comes in. The ADK is a development framework that allows you to orchestrate and deploy Agents, which are individual AI instances that can act and reason independently. By chaining together LLM calls and invoking predefined tools at-will, it’s possible to build intelligent data processing pipelines, complex task management, and more.

For now, we’re going to keep our goal simple to display the basics of creating a dynamic ADK application.

Agent Starter Pack

Prerequisites

Prerequisite commands to setup the Google Cloud project:

# Authenticate with gcloud CLI
gcloud auth login

# Authenticate for local development code (ADC)
gcloud auth application-default login

# Create a new Google Cloud project
gcloud projects create PROJECT_ID

# Set your project
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

# Enable necessary services
gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       aiplatform.googleapis.com \
                       compute.googleapis.com

We’re going to create a haiku generator with the ADK. Our application will act as a conversational chatbot that will ask you for a topic, and generate a haiku about it.

First, we need to instantiate an ADK project. Google fortunately offers a command line interface tool to streamline the creation of a “Hello World” ADK application, and the infrastructure needed to deploy it to the cloud.

We can install it through either uv or pip, whichever one that you’re most comfortable with.

uv Instructions:

# This single command downloads and runs the latest version
uvx agent-starter-pack create haiku-app

Or pip Instructions:

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# 2. Install the package
pip install agent-starter-pack

# 3. Run the create command
agent-starter-pack create haiku-app

The starter pack will offer you a handful of choices when creating your app. For simplicity, lets pick the following:

> Please select a agent to get started:
1. adk_base - A base ReAct agent built with Google's Agent Development Kit (ADK)
# Most basic implementation, easy for us to customize for a proof of concept

> Please select a deployment target:
2. Cloud Run - GCP Serverless container execution
# Versatile and mature service to host ADK application

> Please select a session type:
1. In-memory session - Session data stored in memory - ideal for stateless applications
# Requires no additional infrastructure

> Please select a CI/CD runner:
1. Google Cloud Build - Fully managed CI/CD, deeply integrated with GCP for fast, consistent builds and deployments.
# Perfect for tight coupling with GCP

Enter desired GCP region (Gemini uses global endpoint by default) (us-central1):
# Can leave blank to use the general purpose GCP region

Now, you will have a directory called haiku-app, which will contain a number of different directories including deployment scripts, tests, and utility functions. We want to navigate to the core of our ADK application, the root agent, and modify it to fit our needs. Find the file haiku-app/app/agent.py

def get_weather(query: str) -> str:
    """Simulates a web search. Use it get information on weather."""
    ...........

def get_current_time(query: str) -> str:
    """Simulates getting the current time for a city."""
    .........

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather, get_current_time],
)

Notice how we instantiated an Agent object with some metadata. We can define a name, a specific LLM model, a base prompt, and two functions for the LLM to invoke.

Before we make our haiku modifications, let’s run this out-of-the-box template.

# From project root, cd into haiku-app/
cd haiku-app/

make install
make playground

This will start a local server to interact with the ADK. If you navigate to the displayed URL, you will be presented with a chatbot interface. Make sure to look to the dropdown in the top right of the browser view and select app.

The ADK will hold a conversation with you and invoke it’s configured functions when you make a relevant request.

Haiku Generation

How can we modify this to our own needs? Let’s think back to our goal: to create a Haiku generator.

Open the file haiku-app/app/agent.py in your editor.

  • Delete the functions get_weather and get_current_time , and remove their references from the tool list in the Agent constructor.
  • Define a string called PROMPT . Pretend you are speaking directly to the LLM and give it instructions to generate a haiku. Set this prompt as the instruction value in the Agent constructor.
  • Define one tool to post-process your haiku string after it is generated. For example, we can create a function called louder_haiku that simply makes all the text uppercase.

Your agent.py should look like this below the environment variables:

import os

import google.auth
from google.adk.agents import Agent

_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

PROMPT = """
You are a haiku generator. 
Ask the user for a topic or an idea to create a haiku.
Do your best to follow the 5-7-5 syllable structure.
If the user asks you to say or repeat the haiku in a louder voice, use the louder_haiku tool.
"""

def louder_haiku(text: str) -> str:
    """Converts the entire text block to uppercase."""
    return text.upper()

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    instruction=PROMPT,
    tools=[louder_haiku],
)

Save the file and return to the haiku-app/ directory.

# From project root, cd into haiku-app/
cd haiku-app/
make playground

With minimal and intuitive modifications to one file, we’ve adapted the ADK to fit our needs.

Haiku Validation, Multi-Agent

Now that we have our base haiku generator, we can add another agent into the application to further extend the functionality.

Let’s give this agent a simple analysis job. It will validate the haiku that was previously generated and give it a score between 1 and 100. Invalid haikus will score as zero.

Create a sub_agents folder, a haiku_validator folder, an empty __init__.py and an agent.py.

# From the project root
cd haiku-app/app
mkdir sub_agents
cd sub_agents
mkdir haiku_validator
cd haiku_validator
touch __init__.py agent.py

Your project tree should look like this:

├── haiku-app
    ├── app
        ├── __init__.py
        ├── agent.py   # Root agent, haiku generator
        ├── sub_agents
            └── haiku_validator
                ├── __init__.py
                └── agent.py # Sub-agent, haiku validator

Your validator haiku-app/app/sub_agents/haiku_validator/agent.py should contain this:

from google.adk.agents import Agent

PROMPT = """
You are a haiku validator.
You will be given an input and must determine if it:
1. Has three lines
2. Follows the 5-7-5 syllable structure.

You will also judge the haiku on its literary excellence, and give it a score from 0 to 100, with 100 being the best.
Invalid haikus should receive a score of 0.

Return your response in the following format:
{
    "is_valid": true,
    "score": 85,
    "feedback": "This haiku is well-structured and follows the 5-7-5 syllable pattern."
}
"""

haiku_validator_agent = Agent(
    name="haiku_validator_agent",
    model="gemini-2.5-flash",
    instruction=PROMPT,
    output_key="haiku_validator_agent_output",
)

In your root generator agent haiku-app/app/agent.py, you should make the following modifications:

import os

import google.auth
from google.adk.agents import Agent
# UPDATE: Import AgentTool
from google.adk.tools.agent_tool import AgentTool

_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

# UPDATE: Import the validator sub-agent
from .sub_agents.haiku_validator.agent import haiku_validator_agent

# UPDATE: Additional instruction line at the end of the prompt
PROMPT = """
You are a haiku generator. 
Ask the user for a topic or an idea to create a haiku.
Do your best to follow the 5-7-5 syllable structure.
If the user asks you to say or repeat the haiku in a louder voice, use the louder_haiku tool.

If the user asks you to validate the haiku, use the haiku_validator_agent tool.
"""

def louder_haiku(text: str) -> str:
    """Converts the entire text block to uppercase."""
    return text.upper()

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    instruction=PROMPT,
    tools=[
        # UPDATE: Add validator agent as an AgentTool
        AgentTool(agent=haiku_validator_agent),
        louder_haiku
        ],
)

Now cd back to haiku-app/ and run make playground

Now we can invoke a separate agent entirely, and let it handle dedicated functionality, like a standalone AI microservice.

Our final code repository with all modifications can be found at https://github.com/SZNS/szns-adk-a2a.

Conclusion

From here, we can build out additional functionality through custom tool functions (like we saw with louder_haiku ) and additional sub-agents (like the haiku_validator_agent). In our next tutorial, we will build off our work by leveraging the A2A (Agent2Agent) and MCP (Model Context Protocol) frameworks. We will walk through deploying our haiku generator to Google’s Cloud Run, and also create a MCP REST service for managing the haikus with an in-memory SQLite database.

Read more