Tutorial
Google ADK Tutorial for Beginners
Google's Agent Development Kit (ADK) is an open-source framework for building AI agents in code. You define an agent as a Python object with a model, an instruction and a list of tools, then run it from the terminal or a built-in web UI. This tutorial builds a tool-using agent and a small multi-agent team with ADK in Python.
By Abdul Rahman Azam, founder of AI Season · Updated
Key facts
| Google ADK is | An open-source, code-first framework from Google for building, testing and deploying AI agents |
|---|---|
| Install | pip install google-adk |
| Languages | Python, TypeScript, Go, Java and Kotlin |
| Required element | A root_agent defined in agent.py |
| Run it | adk run my_agent in the terminal or adk web for the browser UI |
| Model | Built for Gemini; other models can be connected |
What is Google ADK?
Google ADK (Agent Development Kit) is an open-source framework for writing AI agents as code: you declare an agent's model, instructions and tools, and ADK runs the tool-calling loop, manages the session and gives you tools to test and deploy it. It is optimised for Gemini models and Google Cloud but is designed to work with other models and hosts too.
ADK's distinguishing features are its developer UI (adk web), which shows every event and tool call as you chat, and its two kinds of agents: LLM agents that reason, and workflow agents that run sub-agents in a fixed sequence, in parallel or in a loop.
Setup
pip install google-adk
# Create a project folder like this:
# my_agent/
# __init__.py -> from . import agent
# agent.py -> your agent code
# .env -> GOOGLE_API_KEY=your-keyGet a Gemini API key from Google AI Studio (it has a free tier) and put it in the .env file. ADK can also scaffold this structure for you with adk create my_agent.
Your first ADK agent with a tool
A tool in ADK is an ordinary Python function. ADK reads its name, type hints and docstring to describe it to the model, so write those carefully.
# my_agent/agent.py
from google.adk.agents import Agent
RATES = {"USD": 1.0, "PKR": 278.0, "INR": 84.0} # demo numbers
def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict:
"""Convert an amount of money between USD, PKR and INR.
Args:
amount: The amount to convert.
from_currency: Currency code of the amount: USD, PKR or INR.
to_currency: Currency code to convert into: USD, PKR or INR.
"""
if from_currency not in RATES or to_currency not in RATES:
return {"status": "error", "message": "Unsupported currency code."}
usd = amount / RATES[from_currency]
return {"status": "success", "result": round(usd * RATES[to_currency], 2)}
root_agent = Agent(
model="gemini-flash-latest",
name="currency_agent",
description="Converts money between USD, PKR and INR.",
instruction=(
"You help students convert currencies. Always use the convert_currency "
"tool for the calculation and never guess a rate."
),
tools=[convert_currency],
)The only required element is a variable named root_agent. Returning a dictionary with a status field is the ADK convention; it lets the model see errors as data and recover.
Run and test the agent
# from the folder that contains my_agent/
adk run my_agent # chat in the terminal
adk web # open the developer UI in your browserUse adk web while learning. Pick your agent from the list, ask "How much is 3000 PKR in Indian rupees?" and open the events panel: you will see the model's function call, the arguments, your function's return value and the final answer. Seeing those steps is the fastest way to understand tool calling.
Multi-agent systems with sub_agents
ADK builds multi-agent systems as a tree. A parent agent lists its children in sub_agents, and the model can hand a request to the child whose description fits best.
from google.adk.agents import LlmAgent
fees_agent = LlmAgent(
name="fees_agent",
model="gemini-flash-latest",
description="Answers questions about course fees and payment.",
instruction="Answer fee questions briefly. Use convert_currency for other currencies.",
tools=[convert_currency],
)
syllabus_agent = LlmAgent(
name="syllabus_agent",
model="gemini-flash-latest",
description="Explains what the course teaches, week by week.",
instruction="Explain course topics in simple language with one example each.",
)
root_agent = LlmAgent(
name="coordinator",
model="gemini-flash-latest",
description="Routes student questions to the right specialist.",
instruction="Send fee questions to fees_agent and topic questions to syllabus_agent.",
sub_agents=[fees_agent, syllabus_agent],
)Each agent instance can have only one parent. For fixed pipelines ADK also has workflow agents: SequentialAgent runs children in order, ParallelAgent runs them at once and LoopAgent repeats them until a condition is met. These map directly onto the agent design patterns of chaining, parallelisation and evaluator loops.
Sessions, state and deployment
- Sessions and state. ADK keeps each conversation in a session, with a
statedictionary that tools and agents can read and write. Swap the in-memory session service for a database-backed one in production. See agent memory. - MCP and A2A. ADK can use tools from MCP servers and talk to other agents over the A2A protocol, which Google originated.
- Evaluation.
adk evalruns saved test conversations against your agent. See agent evaluation. - Deployment. An ADK agent can be served as an API and deployed to Cloud Run, Vertex AI's agent runtime or any container host. See deploy an AI agent.
Google ADK vs LangGraph vs other SDKs
| Google ADK | LangGraph | OpenAI Agents SDK | Claude Agent SDK | |
|---|---|---|---|---|
| Mental model | A tree of agents and workflow agents | A graph of nodes with shared state | Agents with handoffs | A managed loop with built-in tools |
| Dev tooling | adk web UI and adk eval built in | LangGraph Studio, LangSmith | Built-in tracing | Hooks and Claude Code tooling |
| Default model | Gemini | Any | OpenAI | Claude |
| Good first choice when | You use Gemini or Google Cloud | You need custom control flow | You use OpenAI models | You build coding or file agents |
Related tutorials: LangGraph, OpenAI Agents SDK, Claude Agent SDK, and the full framework comparison.
ADK is updated often and model IDs change. Check the official ADK documentation at adk.dev for current names before you copy code.
How AI Season teaches agent SDKs
AI Season's founder Abdul Rahman Azam builds with Google ADK, and Session 9 of the curriculum, MCP and Agent SDK, shows how SDK-style agents relate to the raw loop and LangGraph graphs students have already built. Cohort 02 starts 1st January 2027.
Frequently asked questions
What is Google ADK?
Google ADK, the Agent Development Kit, is an open-source framework from Google for building AI agents in code. You define agents with a model, instructions and tools, and ADK handles the tool-calling loop, sessions, testing UI and deployment.
How do I install Google ADK?
Run pip install google-adk for Python. Then create a folder with an agent.py file that defines root_agent and a .env file containing your Gemini API key.
Is Google ADK free?
Yes, ADK is open source and free. You pay only for the model usage and any cloud hosting; Gemini has a free tier through Google AI Studio that is enough for learning.
Does Google ADK only work with Gemini?
No. It is optimised for Gemini but is model-agnostic, and other models can be connected through its model integrations.
What is the difference between Google ADK and LangGraph?
ADK organises a system as a hierarchy of agents and workflow agents with a built-in developer UI. LangGraph models it as a graph of nodes and edges with explicit state, giving finer control over flow.
How do I run an ADK agent?
From the parent folder, run adk run followed by your agent folder name to chat in the terminal, or adk web to open the browser-based developer UI.