Python Quickstart for ADK¶

This guide shows you how to get up and running with Agent Development Kit (ADK) for Python. Before you start, make sure you have the following installed:

Python 3.10 or later
pip for installing packages

Installation¶

Recommended: create and activate a Python virtual environment

Create a Python virtual environment:

python -m venv .venv

Activate the Python virtual environment:

Windows CMDWindows PowershellMacOS / Linux

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

source .venv/bin/activate

Install ADK by running the following command:

pip install google-adk

Create an agent project¶

Run the adk create command to start a new agent project.

adk create my_agent

Explore the agent project¶

The created agent project has the following structure, with the agent.py file containing the main control code for the agent.

my_agent/
    agent.py      # main agent code
    .env          # API keys or project IDs
    __init__.py

Update your agent project¶

The agent.py file contains a root_agent definition which is the only required element of an ADK agent. You can also define tools for the agent to use. Update the generated agent.py code to include a get_current_time tool for use by the agent, as shown in the following code:

from google.adk.agents.llm_agent import Agent

# Mock tool implementation
def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

Authentication¶

This guide uses a Gemini model for your agent. The ADK supports both Vertex AI API (available via Google Cloud Console) and Gemini API (available via Google AI Studio) to access Gemini models. See Choosing Vertex AI API or Gemini API for guidance.

Vertex AI (Google Cloud)Gemini API (Google AI Studio)Vertex AI Express Mode

The standard way to authenticate to Vertex AI is using Application Default Credentials (ADC). Ensure you have completed the project prerequisites and follow the steps below to set it up in your local development environment.

Install the gcloud CLI: Follow the official installation instructions.
Create local authentication credentials: This gcloud command opens a browser to authenticate your user account for local development.
```
gcloud auth application-default login
```

Set environment variables: Create or validate that a .env file or .properties (Java) is in your project's root directory and add the following lines. ADK will automatically load this file.

GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
GOOGLE_GENAI_USE_VERTEXAI=TRUE # Explicitly tell the library to use Vertex AI

Note: See ADC documentation to get more details and understand how ADC works.

Using the Gemini API (Google AI Studio) is the simplest and fastest method to use Gemini models and is recommended for getting started quickly by using API Keys for authentication.

Get an API key: Obtain your key from Google AI Studio.
Set environment variables: Create or validate that a .env file or .properties (Java) is in your project's root directory and add the following lines. ADK will automatically load this file.
```
GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
GOOGLE_GENAI_USE_VERTEXAI=FALSE
```

Vertex AI also offers Vertex AI Express Mode, a simplified, API-key-based setup designed for rapid prototyping. This allows new users to quickly access Gemini models for a 90-day period without the immediate need for full Google Cloud project configuration.

Sign up for Express Mode and get your API key.
Set environment variables: Create or validate that a .env file or .properties (Java) is in your project's root directory and add the following lines. ADK will automatically load this file.
```
GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
```

Using other AI models with ADK

ADK supports the use of many generative AI models. For more information on configuring other models in ADK agents, see Models & Authentication.

Run your agent¶

You can run your ADK agent with an interactive command-line interface using the adk run command or the ADK web user interface provided by the ADK using the adk web command. Both these options allow you to test and interact with your agent.

Run with command-line interface¶

Run your agent using the adk run command-line tool.

adk run my_agent

Run with web interface¶

The ADK framework provides web interface you can use to test and interact with your agent. You can start the web interface using the following command:

adk web --port 8000

Note

Run this command from the parent directory that contains your my_agent/ folder. For example, if your agent is inside agents/my_agent/, run adk web from the agents/ directory.

This command starts a web server with a chat interface for your agent. You can access the web interface at (http://localhost:8000). Select the agent at the upper left corner and type a request.

Caution: ADK Web and ADK run for development only

ADK Web and ADK run are not meant for use in production deployments. You should use ADK Web and ADK run for development and debugging purposes only.

Next: Build your agent¶

Now that you have ADK installed and your first agent running, try building your own agent with our build guides:

Build your agent