Google ADK Tutorial: Build Your First AI Agent in 30 Minutes

Google’s Agent Development Kit (ADK) is the open-source Python framework behind a growing share of production Gemini agents. It is also, unfortunately, surrounded by tutorials that stop at “hello world.” A hello-world agent is a chat window with extra steps. The interesting part starts when your agent can call a tool.

This tutorial gets you there in about 30 minutes: a working agent folder, one custom tool, the ADK dev UI, and a testing checklist. I write docs for the official ADK repository (my pull requests live in the open source section), so accuracy here is not optional — if something below is wrong, it is worth a PR.

What you need

• Python 3.10+ (3.12 is a safe choice).
• A Google AI Studio API key for Gemini — free tier is enough for this tutorial.
• A terminal, a text editor, and 30 uninterrupted minutes.

1. Create a clean project

One folder, one virtual environment, no global pollution:

mkdir my-first-adk-agent && cd my-first-adk-agent — then python -m venv .venv, activate it (source .venv/bin/activate on macOS/Linux, .venv\Scripts\activate on Windows), and install the framework: pip install google-adk.

2. Let ADK find your agent (folder structure)

ADK discovers agents by convention: each agent lives in its own folder, and the folder name becomes the agent’s name on the command line. Inside my-first-adk-agent create:

travel_agent/
__init__.py
agent.py
.env (the .env sits next to the folders, in the project root)

In .env add GOOGLE_API_KEY=your-key-here. Nothing else for now.

3. Write the agent

In travel_agent/__init__.py export the agent so ADK can import it:

from .agent import agent # ADK reads the name “agent” by convention

In agent.py define it with a strict instruction — this is where personality and boundaries live:

from google.adk.agents import LlmAgent

agent = LlmAgent(
name="travel_agent",
model="gemini-2.5-flash",
instruction=("You are a travel planner. Answer briefly, "
"always use the available tools before "
"guessing, and say when you do not know."),
description="Plans trips and looks up sample flights.",
) — use any Gemini model id your key supports; the pattern is what matters.

4. Give it a tool — this is the whole point

A tool is just a Python function with type hints and a docstring. ADK builds the function schema from your type hints and the parameter descriptions from your docstring — which is why vague docstrings produce vague tool calls.

Add this to agent.py and register it:

def lookup_flights(from_city: str, to_city: str) -> dict:
"""Looks up sample flights between two cities.

Args:
from_city: Departure city name.
to_city: Arrival city name.
"""
return {"flights": [{"airline": "Demo Air", "price": 189,
"from": from_city, "to": to_city}]}

agent = LlmAgent(..., tools=[lookup_flights])

The fake data is fine for learning — the point is watching the model decide to call your function, pass arguments, and use the result.

5. Run the dev UI

From the project root: adk web. Open the URL it prints (localhost:8000), pick travel_agent, and say something like “find me a flight to Lisbon.”

The UI is the best teacher ADK ships: the events panel shows each turn — model response, tool call with arguments, tool result — and the session panel shows what persisted between messages. When your agent behaves strangely, that panel is the debugger.

6. Test like it matters

Five minutes of real testing beats an hour of reading:

• Ask for a flight — then open the events panel and check it actually called lookup_flights with both cities, not just narrated one.
• Ask something off-topic and see whether the instruction holds the line.
• Ask for a flight to a city you invented — a good agent hesitates or asks; a bad one invents a price with confidence.
• Reload and check the session panel — what survived, what reset, and whether that matches what your use case needs.
• Tweak one line of the instruction and re-run the same prompt. Watching what one sentence controls teaches you more than any architecture diagram.

What to learn next

Once the loop above is boring, these are the next real skills:

• Sessions and state — how conversation history and working memory persist between turns, and what to put in each.
• Multi-agent — split the job: a planner agent that routes to a weather agent or a booking agent instead of one prompt doing everything.
• Callbacks and guardrails — validate tool arguments before they touch a real system.
• Evaluation — ADK ships tooling to run scripted conversations against your agent. Run it before production, not after the first bad reply.
• Deployment — Cloud Run or Vertex AI Agent Engine when the local version stops changing.

A tutorial ends where real work begins: the moment your agent calls a tool and uses the result, you are no longer reading about agents — you are debugging one.

Stuck? The usual three

• ImportError or the agent does not appear: launch adk web from the folder that contains travel_agent/, and confirm __init__.py really exports agent.
• Auth errors: .env must sit next to where you launch the command, with a key from AI Studio — not a screenshot from someone’s tutorial.
• Model not found: the model id has to match what your key can call — check quota and the current model list before blaming the framework.

When the tutorial version works

The gap between this and something you ship is mostly structure: more tools, guardrails, evaluation, and honest review of real conversations after launch. If you have a workflow worth automating and would rather start from a production-shaped foundation than a tutorial, let’s talk. And if you find a doc bug while following along — I contribute to the ADK docs and the fix route is open.