Google ADK Samples

What it is

Agent Development Kit (ADK) is Google’s open-source framework for building, evaluating, and deploying AI agents. It is the same framework Google uses internally for Agentspace and parts of Gemini, factored out and released under Apache-2.0. The headline pieces:

• google/adk-python — the Python SDK. v2.1.0 as of 23 May 2026; releases land roughly every two weeks; 19.9k stars on GitHub.
• google/adk-samples — a sibling repository with ready-to-run sample agents across six languages: Python, TypeScript, Go, Java, Kotlin, and Android. 9.5k stars, 2.6k forks, 748 commits on main, Apache-2.0.
• Sister SDKs in Java, Go, Kotlin and TypeScript — the samples repo doubles as their canonical example library.

The samples are not toy hello-worlds — they ship as proper packages with their own dependencies, tests, and eval suites. Categories include academic research, customer service, data science, financial advisory, medical pre-authorization, personalized shopping, RAG, travel concierge, software bug assistance, supply chain, and a marketing agency multi-agent. They are designed to be cloned and bent into shape, not just read.

Architecture / How it works

ADK 2.0 is built around three concepts:

• Agent — a model + instruction + set of tools + (optionally) sub-agents. Defined as a Python object.
• Workflow runtime — graph-based execution with routing, loops, retry, and human-in-the-loop. New in 2.0.
• Task API — structured agent-to-agent delegation, so a coordinator agent can hand off to a specialist agent and wait for a typed result.

Models are pluggable. The default is Gemini (the docs lead with gemini-2.5-flash), with first-class support for Vertex AI deployments and broader provider support via LiteLLM. Tools are plain Python functions decorated for the runtime — the model gets the signature and docstring as the tool spec.

The samples repo mirrors the SDK’s structure: one top-level folder per language (python/, typescript/, go/, java/, kotlin/, android/), each with an agents/ subdirectory containing one self-contained project per agent. Python dominates by a wide margin — ~30 sample agents under python/agents/, against single-digit counts in every other language.

Install / Setup

The Python SDK is one pip install. Python 3.11 or newer is required.

# 1. Create a clean virtualenv (uv is fastest; venv works too)
python3 -m venv .venv
source .venv/bin/activate

# 2. Install the SDK
pip install google-adk

# Or, with optional integrations (Vertex AI, extra connectors):
pip install "google-adk[extensions]"

# 3. Authenticate to a model provider
#    Gemini API key (fastest path):
export GOOGLE_API_KEY="your-key-here"

#    Or Vertex AI on GCP:
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# 4. Clone the samples repo for working examples
git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents

# 5. Pick a sample and follow its local README
#    (most use Poetry; install if you don’t have it: pipx install poetry)
cd customer-service
poetry install

The three CLI entry points the SDK ships with:

# Interactive REPL chat with an agent
adk run path/to/my_agent

# Local web UI — opens a chat surface with traces & tool calls
adk web path/to/agents_dir

# Local API server — useful for wiring an agent into other apps
adk api_server path/to/agents_dir

Usage examples

Example 1 — the minimum viable agent. Three files: an __init__.py, an agent.py with the agent object, and a .env with the API key. adk run picks it up automatically.

# my_agent/agent.py
from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

# Run it
adk run my_agent

# Or open the web UI on http://localhost:8000
adk web .

Example 2 — an agent with a tool. Tools are plain Python functions. ADK introspects the signature and docstring to build the tool spec the model sees.

# weather_agent/agent.py
from google.adk import Agent
import requests

def get_weather(city: str) -> dict:
    """Return the current temperature in Celsius for a city."""
    r = requests.get(
        "https://api.open-meteo.com/v1/forecast",
        params={"latitude": 52.52, "longitude": 13.41, "current": "temperature_2m"},
    )
    return r.json()

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction=(
        "You are a concise weather assistant. "
        "When the user asks about weather, call get_weather and report "
        "the temperature in plain English."
    ),
    tools=[get_weather],
)

Example 3 — running a real sample from the repo. The customer-service agent under python/agents/ is a multi-turn agent with a sub-agent for order lookups. The full path from clone to chat:

git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/customer-service

# Install deps (this sample uses Poetry)
poetry install

# Copy and fill in the env
cp .env.example .env
# … edit .env to add GOOGLE_API_KEY or Vertex settings

# Run it
poetry run adk run customer_service

# Or load all samples into the local web UI at once
cd ../..
adk web agents

Once adk web is up you get a chat surface, a live trace of every model call and tool invocation, and the ability to switch between agents from a dropdown — useful for comparing approaches across samples without restarting anything.

What’s new / latest version

The 2.0 release in early 2026 was the rewrite that took ADK from “framework for one agent” to “framework for an agent system.” The highlights:

• Workflow runtime — graph execution with routing, loops, retry, dynamic nodes, nested workflows, and explicit human-in-the-loop steps.
• Multi-turn Task API — structured delegation between agents with typed task envelopes; replaces the looser sub-agent calls in 1.x.
• Evaluation — a first-class eval suite (adk eval) for scoring an agent against a JSON dataset of expected behaviours; the samples ship their own eval files alongside the agent code.
• Deployment — one-line packaging for Cloud Run, Vertex AI Agent Engine, and Kubernetes via adk deploy.

Version 2.1.0 (23 May 2026) is the current release; the repo cuts a new tag roughly every two weeks. 62+ versions are available on PyPI — pin to a minor (google-adk~=2.1) if you care about reproducibility.

Why it matters / where I use it

Agent frameworks have been multiplying for two years. ADK is interesting for three pragmatic reasons. First, it ships the same way Google ships its own agent infrastructure — the Apache-2.0 release is the same engine, not a marketing fork, which means the samples are stress-tested by Google’s internal users before they appear on GitHub. Second, the language coverage matters — if your stack is Go or Kotlin, you don’t have to port from a Python-only framework. Third, the workflow runtime fills the gap most chat-style agent frameworks leave open: retries, branching, and explicit human approval steps that aren’t just “ask the model to ask the user.”

I’ve cloned the samples repo at ~/Desktop/Workspace/03-Personal/agent-garden/ and routed ~30 of the Python agents into a Bot-UI dispatcher (marvis-one.vercel.app) with bulk dispatch, voice intent, a Cmd+K palette, and live SSE traces. The samples are the seed catalog — new agents I write follow the same shape (agent.py + tools + eval dataset) so they slot into the dispatcher with no glue code.

Source

Samples repo: github.com/google/adk-samples — Apache-2.0, 9.5k stars, 748 commits.
Python SDK: github.com/google/adk-python — v2.1.0 (2026-05-23), 19.9k stars.
Docs & getting started: google.github.io/adk-docs.