Get Started with ADK: Build Your First Python Agent

In Part 1, we defined a service-status assistant. In this tutorial, we will create its first runnable version: an assistant that explains operations concepts and acknowledges that it cannot yet check service health.

By the end, you will have a local project you can run through the terminal or a browser. Part 3 will add the lookup tools.

Prerequisites

Use Python 3.10 or newer and a Gemini API key from Google AI Studio. This setup follows the installation, package layout, and local execution approach in Google's Python quickstart.

You will also need internet access for the model requests. Check the quotas and billing settings for the key you use.

Step 1: Create a virtual environment and install ADK

Run these commands in the directory where you keep learning projects:

COPY
mkdir adk-starter
cd adk-starter
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install google-adk

On Windows PowerShell, replace the environment creation and activation commands with:

COPY
py -m venv .venv
.\.venv\Scripts\Activate.ps1

Then run the same python -m pip commands. All subsequent commands assume the environment is activated and your working directory is adk-starter.

Confirm the installation:

COPY
python --version
python -m pip show google-adk
adk --help

The last command should display CLI usage. Record the installed dependencies so you can reproduce your own environment:

COPY
python -m pip freeze > requirements.txt

This captures the versions installed on your machine. To reinstall them later in a fresh, activated virtual environment, run:

COPY
python -m pip install -r requirements.txt

Keep the same Python version when recreating the environment. This tutorial does not pin an ADK release, so your installed version may differ from another reader's.

Step 2: Scaffold the agent with the ADK CLI

From adk-starter, use the installed CLI to generate the agent package:

COPY
adk create ops_assistant --model gemini-flash-latest

Google's Python quickstart uses adk create to initialize a project. The Python CLI's scaffolding command is adk create; adk init is not listed in the CLI reference.

If prompted for a backend, choose the Gemini Developer API / Google AI option and supply your Google AI Studio API key. Prompt wording can vary by ADK version. Step 3 shows the final environment settings to verify.

The command creates these files:

COPY
ops_assistant/
├── __init__.py
├── .env
└── agent.py

If you already created ops_assistant while following an earlier version of this tutorial, continue with the existing package and the file updates below. Run the scaffold command only when creating a new package.

Create adk-starter/.gitignore with these complete contents:

COPY
.venv/
.env
.env.*
__pycache__/
*.pyc
.adk/

Open the generated adk-starter/ops_assistant/__init__.py and confirm it contains:

COPY
from . import agent

This import exposes the agent module when ADK loads the package. Next, we will verify the generated configuration and replace the starter agent with our tutorial's implementation.

Step 3: Configure the model connection

Open the generated adk-starter/ops_assistant/.env and set its contents to the following, substituting your own key:

COPY
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=replace_with_your_google_ai_studio_key

If the CLI already saved your key, preserve that value instead of replacing it with the placeholder. This tutorial uses the Gemini Developer API. ADK loads this agent's .env file when you launch it through the CLI. Restart the ADK process after changing the key, and keep the file out of version control.

Step 4: Write the complete agent

Replace the generated adk-starter/ops_assistant/agent.py with this complete implementation:

COPY
from google.adk.agents import Agent


root_agent = Agent(
    name="ops_assistant",
    model="gemini-flash-latest",
    description="Explains service-health concepts for an operations tutorial.",
    instruction=(
        "You are an operations learning assistant. "
        "Explain service-health concepts in clear, concise language. "
        "You have no monitoring tools or live infrastructure access. "
        "If asked for the status of a specific service, explain that you "
        "cannot verify its status yet. Never invent a service-health result."
    ),
)

The root_agent variable is the entry point discovered by the CLI. description summarizes its purpose; instruction guides its responses. The agent configuration is documented in Google's LLM agent guide.

The model name follows the quickstart's gemini-flash-latest alias. An alias can change its underlying model. For repeatable evaluations, select an available explicit model version and record it alongside your dependency versions.

Your project should now look like this:

COPY
adk-starter/
├── .gitignore
├── requirements.txt
└── ops_assistant/
    ├── __init__.py
    ├── .env
    └── agent.py

Step 5: Start a terminal conversation

From adk-starter, run:

COPY
adk run ops_assistant

Enter:

COPY
What does degraded service health mean?

Expect an explanation that a service can remain available while experiencing reduced performance or partial failures. The wording will vary between runs.

Then ask:

COPY
Is payments healthy right now?

The assistant should acknowledge that it cannot verify the service's status. If it invents a status, the response has failed our check even if it sounds plausible.

Stop the CLI with Ctrl+C before continuing.

Step 6: Run the browser interface

From the same parent directory, run:

COPY
adk web --port 8000

Open http://localhost:8000, select ops_assistant, and try the same prompts. The web interface is a development and debugging tool, as described in the quickstart.

Keep this terminal running while using the browser. Stop it with Ctrl+C when finished.

Troubleshooting

You now have a runnable agent and a clear baseline for its behavior. Continue to Part 3: Add custom tools to give it data it can actually look up.