# Google ADK Tutorial for Beginners

URL: https://aiseason.tech/google-adk-tutorial

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.

| Fact | Value |
| --- | --- |
| 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

```bash
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-key
```

Get 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.

```python
# 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

```bash
# from the folder that contains my_agent/
adk run my_agent     # chat in the terminal
adk web              # open the developer UI in your browser
```

Use `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](https://aiseason.tech/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.

```python
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](https://aiseason.tech/ai-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 `state` dictionary that tools and agents can read and write. Swap the in-memory session service for a database-backed one in production. See [agent memory](https://aiseason.tech/ai-agent-memory).
- **MCP and A2A.** ADK can use tools from [MCP servers](https://aiseason.tech/mcp-course) and talk to other agents over the [A2A protocol](https://aiseason.tech/a2a-protocol), which Google originated.
- **Evaluation.** `adk eval` runs saved test conversations against your agent. See [agent evaluation](https://aiseason.tech/ai-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](https://aiseason.tech/deploy-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](https://aiseason.tech/langgraph-tutorial), [OpenAI Agents SDK](https://aiseason.tech/openai-agents-sdk-tutorial), [Claude Agent SDK](https://aiseason.tech/claude-agent-sdk-tutorial), and the full [framework comparison](https://aiseason.tech/ai-agent-frameworks).

> 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](https://aiseason.tech/abdul-rahman-azam) builds with Google ADK, and Session 9 of the [curriculum](https://aiseason.tech/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.

---

_Last updated: 2026-11-16. Canonical page: https://aiseason.tech/google-adk-tutorial. Source: AI Season (https://aiseason.tech/)._
