Build your first agent

In this lesson you’ll scaffold and run a minimal Google ADK agent — a “hello world” style example that shows how to:

scaffold an agent,
register simple tools,
and let the LLM decide which tool to call based on natural language.

This step-by-step walkthrough covers creating a Python virtual environment, installing the Google ADK package, scaffolding a starter application, implementing two deterministic tools (get_current_time and get_current_weather), and running the agent interactively.

A presentation slide that says "Build Your First Agent" on the left with a large "Demo" label on a dark, curved shape on the right. A small "© Copyright KodeKloud" appears in the lower-left corner.

What we’ll do

Create and activate a Python virtual environment
Install google-adk
Scaffold an ADK app
Add two simple tools
Run the agent and interact with it

Create and activate a virtual environment (macOS / Linux shown):

# Create venv
python3 -m venv .venv

# Activate venv (macOS / Linux)
source .venv/bin/activate

# Your prompt should indicate the venv is active, e.g.:
# (.venv) jeremy@MACSTUDIO hello-world %

Install the Google ADK package inside the virtual environment:

(.venv) jeremy@MACSTUDIO hello-world % pip install google-adk

The package installs several dependencies; expect to download multiple MBs. Scaffold a new ADK application from your project root:

(.venv) jeremy@MACSTUDIO hello-world % adk create my_agent

Follow the interactive prompts. For this lesson choose the Gemini model and Google AI backend:

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

Don't have API Key? Create one in AI Studio: https://aistudio.google.com/apikey

Enter Google API key:

After entering your API key the scaffold creates a basic layout (files like __init__.py and agent.py). The generated agent.py is the canonical place to register your agent and tools. Example agent.py Below is a minimal agent.py that defines two deterministic tools and registers them with the root agent. These are intentionally hard-coded for clarity; replace them with real API calls in production.

# agent.py
from google.adk.agents.llm_agent import Agent

def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    # Hard-coded for demonstration
    return {"status": "success", "city": city, "time": "10:30 AM"}

def get_current_weather(city: str) -> dict:
    """Returns the current weather in a specified city."""
    # Hard-coded for demonstration
    return {"status": "success", "city": city, "weather": "Sunny, 75°F"}

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    description="Tells the current time or weather in a specific city.",
    instruction=(
        "You are a helpful assistant that can provide the current time and the current weather in cities. "
        "Use the 'get_current_time' tool to get the time and the 'get_current_weather' tool to get the weather."
    ),
    tools=[get_current_time, get_current_weather],
)

Why register tools this way?

instruction: The text given to the LLM that defines the agent’s behavior and available tools.
tools: A list of Python callables the model may invoke. The LLM chooses which tool to call based on the user query.

Run the agent from the project root:

(.venv) jeremy@MACSTUDIO hello-world % adk run my_agent

A typical interactive session:

Log setup complete: /tmp/agents_log/agent.log
/Users/jeremy/.../.venv/lib/python3.14/site-packages/google/adk/cli/cli.py:155: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice.
  credential_service = InMemoryCredentialService()
Running agent root_agent, type exit to exit.
[user]: What do you do?
[root_agent]: I can tell you the current time or weather in a specific city. Just ask me something like "What time is it in New York?" or "What's the weather like in London?"
[user]: What time is it in New York City?
[root_agent]: The current time in New York is 10:30 AM.
[user]: What is the weather in Tokyo?
[root_agent]: The weather in Tokyo is currently Sunny, 75°F.
[user]:

Key concepts and best practices

The LLM acts as a router: the instruction plus the user query determines which tool (if any) gets invoked.
Tools are plain Python callables and can wrap HTTP APIs, SDKs, or complex business logic.
For production, use real services (timezone APIs, weather APIs), robust error handling, timeouts, and non-blocking I/O when appropriate.
Keep tool signatures simple and well-documented (type hints and short docstrings improve the LLM’s ability to choose correctly).

Tooling at a glance

Component	Purpose	Example / Notes
Agent instruction	Tells the model what tools are available and how to behave	Use clear, concise language describing tools and when to use them
tools parameter	Registers Python callables the agent may invoke	Functions, API wrappers, async callables (if supported)
Model selection	Chooses the LLM that will act as the router and responder	gemini-2.5-flash used in this tutorial
Backend	Underlying runtime for the model	Google AI (AI Studio) or Vertex AI

Tip: Keep your tool interfaces simple and well-documented (type hints and concise docstrings help the LLM choose the right tool). In production, prefer non-blocking calls and proper error handling in tools.

Warning: Some ADK features are experimental and may emit warnings at runtime. Pay attention to those messages and review the ADK changelog when upgrading.

Why this structure matters

The model performs semantic routing: given the instruction and a user prompt, it decides which tool to call and how to format the call.
This approach separates decision-making (LLM) from execution (tools/APIs), enabling safer, auditable, and extensible agents.
It mirrors retrieval-augmented patterns: the LLM identifies the appropriate capability or data source and returns the result in natural language.

Summary

We created a Python virtual environment, installed google-adk, scaffolded a project, added two deterministic tools, and ran an interactive agent that uses the LLM to choose tools based on natural language.
To build a production-ready agent, replace the stub tools with real API integrations (timezone, weather, or other services), add robust error handling, and monitor agent behavior.

Links and references

Google ADK course
AI Studio: https://aistudio.google.com/apikey
For more on agent design patterns, consult the ADK documentation included with the package or the provider’s model docs.

Introduction

ADK Fundamentals

Deploying and Operating ADK Agents

Build your first agent

Watch Video