Google Agent Development Kit (ADK)

1.28.1 · active · verified Thu Apr 09

The Google Agent Development Kit (ADK) is an open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents. It provides a flexible and modular approach to developing multi-agent systems, optimized for Gemini and the Google ecosystem but designed to be model-agnostic. Currently at version 1.28.1, ADK features a rich tool ecosystem, robust debugging capabilities, and support for orchestrating complex agent workflows. It maintains an active release cadence with frequent updates and new features.

Warnings

breaking ADK 2.0 Alpha introduces significant breaking changes, rendering it incompatible with ADK 1.x databases and sessions. APIs are subject to change without notice. It also raises the minimum Python requirement to 3.11+.
Fix: Do not use ADK 2.0 Alpha in production environments if backward compatibility is required. For new projects, ensure a Python 3.11+ virtual environment is used and install with `pip install google-adk --pre`. Do NOT share storage with ADK 1.x projects.
breaking Schema changes in minor versions (e.g., 1.14.0, 1.17.0, 1.19.0) have historically broken deployments without clear migration paths, particularly for database-backed sessions. Core service methods became async requiring `await` for calls to session, memory, and artifact services.
Fix: Regularly check release notes for migration instructions when upgrading. For database schema changes, manual migration scripts might be necessary, though Alembic adoption is planned to automate this. Ensure `await` is used for async service calls.
gotcha The main agent definition file must define an `Agent` instance named `root_agent` for ADK's CLI and web UI to automatically discover and run it. Importing older `LlmAgent` instead of `Agent` is also a common mistake.
Fix: Always name your primary agent variable `root_agent`. Use `from google.adk.agents import Agent` for defining agents.
gotcha Treating AI agent callbacks (hooks) as a dumping ground for heavy business logic, such as RAG operations or long-running tasks, can lead to timeouts and difficult-to-debug agents, breaking the event loop.
Fix: Instead of callbacks, use Tools for operations like RAG so the agent explicitly 'knows' it's retrieving data. For human-in-the-loop interactions, use the `require_confirmation` tool config. Implement deterministic `BaseAgent` instances for long-running tasks as workflow steps.
gotcha By default, ADK assumes a single root agent shared across users. Implementing multi-user support requires custom logic to create separate agents per user, which can lead to losing built-in debugging tools like the Web UI for these custom per-user agents.
Fix: Plan for custom multi-user implementations by creating separate agent instances per user. Be aware that the built-in Web UI might not support debugging these custom per-user agents, necessitating alternative debugging approaches (e.g., logging, custom interfaces).

Install

pip install google-adk Install stable version
pip install google-adk --pre Install ADK 2.0 alpha (breaking changes)

Imports

Agent
```
from google.adk.agents import Agent
```
The `Agent` class is the modern and recommended way to define agents. Directly importing from `google.adk.agents.llm_agent` might indicate usage of an older pattern which was superseded.
App
```
from google.adk.apps import App
```
The `App` class is used for centralized configuration and lifecycle management of agent workflows.
DatabaseSessionService
```
from google.adk.sessions import DatabaseSessionService
```
Used for persistent session storage in production environments.

Quickstart

This quickstart defines a simple conversational AI agent using the `Agent` class. It demonstrates how to set up the agent with a name, model, description, and instruction. The `root_agent` variable name is crucial for ADK to discover and run the agent. Users need to provide a Google API key (via `GOOGLE_API_KEY` environment variable) or configure Vertex AI access. The code includes a warning for missing authentication setup. Once saved in a proper project structure (e.g., `my_agent/agent.py` and `my_agent/__init__.py`), it can be run via the `adk CLI`.

import os
from google.adk.agents import Agent

# Ensure you have your Google AI Studio API key set as an environment variable
# For example: export GOOGLE_API_KEY='YOUR_API_KEY'
# If using Vertex AI, set GOOGLE_GENAI_USE_VERTEXAI='True'
if not os.environ.get('GOOGLE_API_KEY') and not os.environ.get('GOOGLE_GENAI_USE_VERTEXAI'):
    print("Warning: GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI environment variable not set.")
    print("Please set one to run the agent. You can get a free API key at aistudio.google.com/api")
    exit()

# Define your agent - the main agent MUST be named 'root_agent'
root_agent = Agent(
    name="hello_assistant",
    model="gemini-2.0-flash", # Or your preferred model, e.g., 'gemini-1.5-pro'
    description="A friendly AI assistant for general conversation",
    instruction=(
        "You are a warm and helpful assistant. "
        "Greet users enthusiastically and answer their questions clearly. "
        "Be conversational and friendly!"
    ),
)

# To run this agent, save it as `agent.py` in a directory (e.g., `my_agent/`)
# and ensure an empty `__init__.py` exists in the same directory (`my_agent/__init__.py`).
# Then, from the parent directory, run:
# adk run my_agent
# Or for the web UI:
# adk web --agent-dir my_agent

view raw JSON →