How to create and run a first agent with Google ADK for Python

The Python quickstart for Agent Development Kit (ADK) shows how to get up and running with ADK for Python. On the Get started page, ADK is the kit for developers who want to quickly build, manage, evaluate, and deploy AI-powered agents. That page says the quickstart guides get you set up and running a simple agent in less than 20 minutes, and it lists Python first: create your first Python ADK agent in minutes.

You can follow that path with one install, one scaffold, a short sample file, and a terminal session. This article stays on the Python quickstart. It covers the documented install, virtual environment, project scaffold, sample agent, API key file, terminal run, and development web UI. The model string in the sample is the string that page prints. Treat it as an example in the docs, not as a model announcement.

Prerequisites

Before you start, the quickstart requires:

Python 3.10 or later
pip for installing packages

Install ADK

Install ADK with this command:

pip install google-adk

A virtual environment is recommended. Create it with:

python3 -m venv .venv

Then activate it. The quickstart prints a different activation command for each shell.

Windows Command Prompt:

.venv\Scripts\activate.bat

Windows PowerShell:

.venv\Scripts\Activate.ps1

MacOS / Linux:

source .venv/bin/activate

Create the agent project

Start a new agent project with:

adk create my_agent

The created project has this structure. The quickstart says the agent.py file contains the main control code for the agent, and that .env is for API keys or project IDs. The page lists __init__.py but does not describe its contents:

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

Update agent.py with the sample tool

The agent.py file contains a root_agent definition. The quickstart says that definition is the only required element of an ADK agent. You can also define tools for the agent to use.

Update the generated agent.py so it includes a get_current_time tool. Copy the sample the page shows:

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-flash-latest',
    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],
)

The comment above the function calls it a mock tool implementation. It does not read a system clock. It takes a city string and returns a dictionary whose status is success, whose city is the value you passed, and whose time is the fixed string 10:30 AM.

root_agent is built with Agent, imported from google.adk.agents.llm_agent. In the sample, the model argument is gemini-flash-latest. That is the quickstart sample, not a release note. The name is root_agent. The description says the agent tells the current time in a specified city. The instruction says to be a helpful assistant that tells the current time in cities, and to use the get_current_time tool for that purpose. The tools list contains that one function.

The same page says ADK supports many generative AI models. For configuring other models, it points to a Models & Authentication page. This quickstart does not show those settings, so this article does not add them.

Set the Gemini API key

This project uses the Gemini API, which requires an API key. If you do not already have one, the quickstart says to create a key in Google AI Studio on the API Keys page.

In a terminal window, write your API key into an .env file as an environment variable. The page labels that update for the agent project, then shows a command that writes .env. It does not print a change-directory command. Run the echo from the agent project directory so you update the .env file the page names. Replace the YOUR_API_KEY placeholder with your key.

MacOS / Linux:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

Windows PowerShell, as printed on the same page:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

Windows Command Prompt:

echo GOOGLE_API_KEY="YOUR_API_KEY" > .env

Every one of those snippets sets GOOGLE_API_KEY. The quickstart does not show another variable name for this sample.

Run the agent in the terminal

The quickstart says you can run the agent with an interactive command-line interface, or with the ADK web user interface. Both options are for testing and interacting with the agent.

The command-line tool is:

adk run my_agent

The page includes a screenshot of that session. It does not include a transcript, so there is no official first message to paste. The sample instruction is about the current time in cities, and the mock tool always returns 10:30 AM.

Start the development web UI

The web interface is a separate command:

adk web --port 8000

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

The command starts a web server with a chat interface. Access it at http://localhost:8000. Select the agent at the upper left corner and type a request.

The page adds a caution: ADK Web is not meant for use in production deployments. Use ADK Web for development and debugging purposes only.

Where this leaves you

After these steps you have ADK installed, a my_agent project, one mock tool, and a root_agent the terminal or the dev UI can load. The Get started page presents this Python quickstart as the way to create your first Python ADK agent. It also lists quickstarts for other languages, plus an Agents CLI guide and a migrate guide. Those pages are separate. This article does not copy commands from them.

If a flag or value is not printed in the Python quickstart, do not invent it. The commands and the agent sample above are the ones that page shows.

Next step: create and activate the virtual environment, run the install command, scaffold my_agent, replace agent.py with the sample, and write your Gemini API key into the project's .env file using the echo snippet for your shell. Then run adk run my_agent and ask for the time in a city so you can see the mock answer. When that works, the Python quickstart points you to its build guides to replace this sample with an agent of your own. If you want a browser chat while you are still developing, start the documented web command from the parent of my_agent/ and open http://localhost:8000. Keep that UI off production.