Skip to main content

Section 2: Build Your First ADK Agent

It's time to get hands-on. In this section, we set up your development environment across macOS, Windows, and Ubuntu, and run your first "Hello World" agent using Google's Agent Development Kit (ADK). We will build a Website Builder Agent capable of generating full-fledged, responsive HTML landing pages from a single natural language prompt.

Companion Guide

This documentation serves as the comprehensive written companion to the Master Google ADK video course. While these guides provide the technical reference and code snippets, the video course provides the deep-dive reasoning and live debugging sessions.

Bestseller
Master Google ADK - Agent Development Kit

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+
View on Udemy

The Project: Website Builder Agent​

Before we dive into the installation, let's understand what we are building. The Website Builder Agent demonstrates the core power of LLM Orchestration.

With a single prompt—"Build a landing page for a Website that teaches about AI..."—the agent autonomously:

  1. Reasons: Analyzes the request to determine the necessary HTML structure, CSS styling, and content.
  2. Generates: Produces high-quality, responsive code.
  3. Executes: Uses a local File Writer Tool to save the code to your disk with a timestamped filename.

The result is a self-contained HTML file with modern styling (gradients, hover effects) that you can open immediately in your browser.

Architecture Breakdown​

To achieve this, we use the following ADK components:

  • LlmAgent: The brain of the operation, powered by Gemini 2.0 Flash for high speed and low latency.
  • System Instructions: A text file (instructions.txt) that defines the agent's persona ("You are an expert AI web developer").
  • Tooling: A Python function write_to_file registered as a tool. The ADK converts this Python function into a schema the LLM can understand, enabling Function Calling.

Environment Setup​

We will use Python 3.11+ and UV, a modern, lightning-fast package manager that replaces standard pip for robust dependency resolution.

Select your operating system below for specific installation steps.

1. Install Python Check your current version:

python3 --version

If you do not have Python 3.11 or newer, download the installer from python.org.

2. Install UV (Package Manager) We use uv for managing virtual environments. It is significantly faster than pip and handles dependency locking automatically.

pip3 install uv
# Verify installation
uv --version
Troubleshooting

If uv is not found after installation, restart your terminal to refresh your system PATH.

3. Install VS Code & Extensions

  1. Download Visual Studio Code from code.visualstudio.com.
  2. Install the official Python extension by Microsoft.
  3. Pro Tip: Install the HTML Preview extension (by George Oliveira) to view your agent's generated pages directly inside VS Code.

4. Install Git

git --version

If Git is missing, macOS will prompt you to install the Command Line Developer Tools. Click "Install".

Project Directory Structure​

We will organize our work to match the course repository structure. Open your terminal/PowerShell and run:

mkdir -p ~/development/adk
cd ~/development/adk

Clone the course repository or unzip the provided source code here. Your structure should look like this:

development/
└── adk/
    └── adk_samples/
        └── version_1_website_builder_simple/
            ├── agents/
            ├── tools/
            ├── utils/
            ├── .env
            └── pyproject.toml

Building and Running the Agent​

1. Initialize Virtual Environment​

Navigate to the project folder and use uv to create a fast, isolated environment.

cd ~/development/adk/adk_samples/version_1_website_builder_simple
uv venv

2. Activate Environment​

source .venv/bin/activate

You should see (version_1_website_builder_simple) in your terminal prompt.

3. Install Dependencies​

This project uses pyproject.toml to define dependencies (specifically google-adk). Using uv sync ensures you get the exact versions required.

uv sync --all-groups

4. Configure API Keys​

The ADK needs access to Google's generative models.

  1. Go to Google AI Studio and click Get API key.

  2. Create a key in a Google Cloud project (e.g., "Gemini API").

  3. In VS Code, create a file named .env in the version_1_website_builder_simple directory.

  4. Add the following configuration:

    GOOGLE_API_KEY=your_api_key_starts_with_AIza...
    GOOGLE_GENAI_USE_VERTEXAI=FALSE
Security Best Practice

The .env file contains sensitive keys. Ensure your .gitignore file includes .env to prevent accidental commits to public repositories.

5. Run the Agent​

Use the ADK CLI to launch the development server. We point it to the agents directory where our python agent code resides.

adk web ./agents

You should see output indicating the server has started. Open your browser to: http://localhost:8000

In the ADK Playground, select website_builder_simple from the left sidebar and type a prompt:

"Build me a resume website for a software engineer. Make it professional."

Code Walkthrough​

Let's understand the magic behind the scenes.

1. The Configuration (pyproject.toml)​

Instead of a requirements.txt, we use pyproject.toml. This modern standard defines metadata and dependencies (google-adk) allowing uv to manage the environment deterministically.

2. The Tool (tools/file_writer_tool.py)​

This file defines the capability we give to the agent.

def write_to_file(content: str) -> dict:
    """Writes the given HTML content to a timestamped HTML file."""
    # Logic to generate filename using datetime...
    # Logic to write content with utf-8 encoding...
    return {"status": "success", "filename": filename}

Why this matters: The ADK inspects the type hint content: str and the docstring to automatically generate a JSON schema for the LLM. The model knows how to use this tool without us writing any parsing logic.

3. The Agent (agents/website_builder_simple/agent.py)​

This is the "Brain".

from google.adk.agents import LlmAgent
from tools.file_writer_tool import write_to_file
from utils.file_loader import load_instructions_file

root_agent = LlmAgent(
    name="website_builder_simple",
    model="gemini-2.0-flash-001",  # Fast, low-latency model
    instruction=load_instructions_file("agents/.../instructions.txt"),
    tools=[write_to_file]
)
  • Model Selection: We use gemini-2.0-flash-001 because it is cost-effective and fast for interactive tasks.
  • Instruction Loading: We load instructions from a text file (instructions.txt). This separates our "Prompt Engineering" from our "Python Engineering," keeping the codebase clean.
  • Tool Registration: Passing [write_to_file] allows the agent to decide when to save the file based on the conversation flow.

What's Next?​

You have successfully set up a professional AI engineering environment and deployed your first tool-using agent.

In Section 3, we will move from single agents to Sequential Workflows. You will learn how to chain multiple agents together—one for research, one for coding, and one for review—to solve complex tasks.

Bestseller
Master Google ADK - Agent Development Kit

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+
View on Udemy

Go to Section 3: Sequential Agent Workflows →