How to create a first agent with Google ADK

The official Agent Development Kit (ADK) get-started page is a set of first-agent quickstarts. It says those guides get you set up and running a simple agent in less than 20 minutes. The index lists Python, TypeScript, Go, Java, and Kotlin, plus an Agents CLI quickstart and a migrate path. The same page describes ADK as a way to build, manage, evaluate, and deploy AI-powered agents. This walkthrough does not follow that farther path.

It stays on the Python quickstart: install the SDK, scaffold a project, define one tool-using agent, and run it locally. The Python page treats the bundled web UI as a development and debugging tool, and it says that UI is not meant for production deployments.

What the Python quickstart requires

Before you start, have:

Python 3.10 or later
pip for installing packages

A virtual environment is recommended. Create one with:

python3 -m venv .venv

Activate it with the shell command the docs publish:

Windows Command Prompt: .venv\Scripts\activate.bat
Windows PowerShell: .venv\Scripts\Activate.ps1
macOS or Linux: source .venv/bin/activate

Install the package

Install ADK by running:

pip install google-adk

That is the full install command in the quickstart. It does not include a version pin.

Scaffold the agent project

Run:

adk create my_agent

The created project has this structure. agent.py holds the main control code. .env is for API keys or project IDs. __init__.py is listed, but the quickstart does not show what is inside it, so this walkthrough does not edit that file.

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

Define the root agent and one tool

agent.py 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 as published, rather than retyping individual fields:

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],
)

Read that block as one sample, not as separate commands:

The import brings in Agent from the module path on the first line.
The constructor names the agent root_agent.
The description says it tells the current time in a specified city.
The instruction says to use the get_current_time tool for that purpose.
The tools list in the constructor registers that function.
The model field is the Gemini model name written in the sample. The quickstart says ADK supports many generative AI models and points to a Models and Authentication page for other setups. This first agent does not change the sample model.
The function is marked as a mock. It takes a city string and returns a dict whose fields are status, city, and time. The time is the fixed string inside that return, not a reading from a live clock.

If the tool runs, the value it hands back is that mock return. The quickstart does not show a live time lookup.

Put the Gemini API key in the env file

This project uses the Gemini API, which requires an API key. If you do not already have one, create a key in Google AI Studio on the API Keys page. The quickstart does not include the steps for creating the key.

In a terminal, write the key into an .env file. The docs label the step as an update to the env file in the my_agent project. The commands themselves redirect into a file named .env.

macOS, Linux, and Windows PowerShell use the same command:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

Windows Command Prompt:

echo GOOGLE_API_KEY="YOUR_API_KEY" > .env

Replace the placeholder in the command you use with your key. Those commands write .env in the current directory, so run them where that file should land.

Run it in the terminal

The quickstart documents two local ways to test and interact with the agent: an interactive command-line interface, and the ADK web user interface.

For the command line:

adk run my_agent

The page includes a screenshot of that session. It does not print a sample user prompt, so the exact lines you type are not specified. A request for the current time in a city matches the instruction in the sample. The tool answer is the mock return from the function, not a live clock.

Run the local web UI

You can also start the ADK web interface:

adk web --port 8000

Run that command from the parent directory that contains your my_agent/ folder. If the 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 quickstart cautions that ADK Web is not meant for use in production deployments. You should use it for development and debugging purposes only.

After the first local run

The get-started index also links TypeScript, Go, Java, and Kotlin quickstarts, plus Agents CLI and a migrate guide, if you want a first agent in another language. Those pages are separate from the Python commands above. This article does not cover them.

The Python quickstart's own next section is "Next: Build your agent." It points at build guides once this first agent is running. This walkthrough stops at the local quickstart.

Try adk run my_agent and ask for the time in a city so you can see whether the mock tool is used. If you want the browser UI, start adk web --port 8000 from the parent of my_agent/ and open http://localhost:8000. Then follow "Next: Build your agent" on the Python Quickstart for ADK. The language index is Get started.