Install & Compatibility
Where this runs
tested against v2.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 10.905s · 118.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 17.3s · import 6.547s · 120MB
194MB installed
● package 194MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from google.adk.agents import Agent
✗ from google.adk.agents.llm_agent 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.
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
adk --version
Debug
Known issues
breakingADK 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+.fixDo 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.
affects: 2.0.0a1+
breakingSchema 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.fixRegularly 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.
affects: 1.x (notably 1.14.0, 1.17.0, 1.19.0, 1.0+ async changes)
gotchaThe 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.fixAlways name your primary agent variable `root_agent`. Use `from google.adk.agents import Agent` for defining agents.
affects: All 1.x and 2.0 Alpha
gotchaTreating 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.fixInstead 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.
affects: All 1.x and 2.0 Alpha
gotchaBy 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.fixPlan 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).
affects: All 1.x and 2.0 Alpha
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.adk'
The `google-adk` package is either not installed, the Python virtual environment where it's installed is not activated, or there's an issue with the Python path.
fixEnsure you have installed the library using `pip install google-adk` and that your Python virtual environment is activated. If installed in a virtual environment, activate it using `source venv/bin/activate` (Linux/macOS) or `.\venv\Scripts\activate` (Windows).
adk: command not found
The `adk` command-line tool's executable path is not in your system's PATH environment variable, or the virtual environment where `google-adk` was installed is not activated.
fixActivate your Python virtual environment if you are using one, as `pip install google-adk` places the `adk` executable within the environment's scripts directory. If the issue persists, ensure `google-adk` is installed and consider reinstalling it within an activated virtual environment.
ValueError: Agent name cannot be 'user'
You have defined an `Agent` with the reserved name 'user' or included invalid characters (e.g., spaces, hyphens) in the agent's name.
fixChoose a different name for your agent that is not 'user' and ensures it is a valid Python identifier (starts with a letter or underscore, followed by letters, numbers, or underscores).
AttributeError: module 'google.cloud.aiplatform' has no attribute 'Agent'
You are attempting to import the `Agent` class from `google.cloud.aiplatform`, which is incorrect. The `Agent` class for the Google ADK is located within `google.adk.agents`.
fixModify your import statement to `from google.adk import Agent` or `from google.adk.agents import Agent` instead of trying to import it from `google.cloud.aiplatform`.
API key not valid (400) / Resource Exhausted (429) / Insufficient permissions
These errors typically indicate problems with your Google API key (invalid, missing, or incorrect), exceeding API quota limits, or insufficient permissions for the associated Google Cloud project or service account.
fixVerify that your `GOOGLE_API_KEY` is correctly set in your `.env` file or environment variables and is valid. Check your Google Cloud project's quotas and enable billing if necessary. Ensure the service account or user credentials have the required permissions for the Google AI services being accessed.
Upgrade
Version history
2.8.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10+ for stable v1.x, and 3.11+ for ADK 2.0 alpha.
google-genairequiredCore dependency for interacting with Google's generative AI models like Gemini.
pydanticrequiredUsed for data validation and settings management.
fastapirequiredUsed for creating API servers for agents, especially the `adk api_server` command.
httpxrequiredAsynchronous HTTP client used internally.
opentelemetry-sdkrequiredFor built-in observability and tracing.