How to create a first Google ADK agent

Agent Development Kit (ADK) is designed to empower developers to quickly build, manage, evaluate, and deploy AI-powered agents. The get-started page says its quickstart guides get you set up and running a simple agent in less than 20 minutes. For Python, that page points to the Python quickstart: create your first Python ADK agent in minutes. The same index also lists TypeScript, Go, Java, Kotlin, and an Agents CLI quickstart. This article follows the Python page only.

The work is a local first run. You install the package, scaffold a project, put the documented root agent and mock tool in place, set a Gemini API key, and start a session from the terminal or the development web UI. The quickstart does not include a production deploy, and it warns that the web UI is not one.

Check Python

The Python quickstart lists two things to have installed before you start:

Python 3.10 or later
pip for installing packages

The page prints the install command next. It does not move from those two requirements straight into a virtual environment.

Install ADK

Install ADK by running the following command:

pip install google-adk

Recommended: create and activate a Python virtual environment. The quickstart places that recommendation after the install command. It does not say to run the install with the environment already active.

Create a Python virtual environment:

python3 -m venv .venv

Activate the Python virtual environment with the shell-specific command the quickstart prints.

Windows Command Prompt:

.venv\Scripts\activate.bat

Windows PowerShell:

.venv\Scripts\Activate.ps1

MacOS / Linux:

source .venv/bin/activate

The quickstart does not add further install commands for this first agent.

Scaffold the project with adk create

Start the project with the create command in the create-an-agent-project section:

adk create my_agent

The page shows this layout:

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

agent.py holds the main control code. The quickstart says that file contains a root_agent definition, and that definition is the only required element of an ADK agent. You can also define tools. In the tree, .env is the file for API keys or project IDs.

The create section does not state a required working directory. A later note does specify a directory, but only for the web command.

Put the documented tool in agent.py

The update section asks you to change the generated agent.py so the agent can use a get_current_time tool. The sample is a mock. Copy it completely, including the import, the function, and the root_agent assignment:

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

Treat that block as the whole definition for this exercise. The tool docstring says it returns the current time in a specified city, but the function body returns a fixed success payload. The time value is the literal in that return statement, not a system clock. The instruction in the same block tells the assistant to use the tool for that purpose.

The quickstart notes that ADK supports many generative models. For other models it points to a Models & Authentication page. Leave that for later. This first file should match the sample.

Set the Gemini API key

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.

Then write the key into an .env file as an environment variable. The page labels that step as an update for the env file in the new agent folder and shows a redirect that writes .env. It does not show a change-directory command, so run the echo where that file should be written. Keep the placeholder only until you substitute your own key.

On macOS, Linux, or Windows PowerShell, the quickstart shows:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > .env

On Windows Command Prompt, it shows a different quoting form:

echo GOOGLE_API_KEY="YOUR_API_KEY" > .env

Match the form to your shell. The page prints the single-quoted version for macOS, Linux, and Windows PowerShell, and the other version for Windows Command Prompt. No other key name appears in this section.

Run a local session

The run section gives two development options: an interactive command-line interface, or the ADK web user interface. Both are for testing and interacting with the agent.

For the command line, the page shows:

adk run my_agent

For the web interface, it shows:

adk web --port 8000

The note under that command matters. Run it from the parent directory that contains your my_agent/ folder. If the agent is inside agents/my_agent/, run the web command from agents/. 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.

Read the caution on the same page before you leave the session open: ADK Web is not meant for use in production deployments. Use it for development and debugging only. The broader get-started page names deploy as something ADK is designed to support, but this Python quickstart never shows how. Do not treat the web command as that step.

What the first run includes

After the steps the quickstart lists, you have the package from the install section, the project the create command scaffolds, and the mock time tool from the sample file. The instruction tells the agent to use that tool when telling the current time in cities. The tool still returns the mock payload until you change the function. The quickstart does not document a real time source, a second tool, authentication beyond the Gemini key in .env, or a hosted endpoint.

Next step

Talk to the agent with the documented run command, or open http://localhost:8000, select it at the upper left corner, and type a request. When that local session works, follow the quickstart's closing section, "Next: Build your agent," and use the build guides it links. If you want a model other than the one in the sample block, use the Models & Authentication page named in the quickstart rather than guessing new environment variables.