Quickstart: Build an agent with the Agent Development Kit

This quickstart guides you through setting up your Google Cloud project, installing the Agent Development Kit (ADK), setting up a basic agent, and running its developer user interface.

This quickstart assumes you are using a local IDE (VS Code, PyCharm, etc.) with Python 3.10+ and terminal access. The agent runs entirely on your machine, which is recommended for local application development.

Before you begin

Complete the following steps:

Set up a Google Cloud project

Set up your Google Cloud project and enable the Vertex AI API.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

Set up credentials

On your local terminal, set up and authenticate with the Google Cloud CLI. If you are familiar with the Gemini API in Google AI Studio, note that the Vertex AI Gemini API uses Identity and Access Management instead of API keys to manage access.

  1. Install and initialize the Google Cloud CLI.

  2. If you previously installed the gcloud CLI, ensure your gcloud components are updated by running this command.

    gcloud components update

  3. Run the following command to generate a local Application Default Credentials (ADC) file. Your agent will use these credentials to access Vertex AI during local application development.

    gcloud auth application-default login

    For more information, see Setup Application Default Credentials.

Set up a virtual environment and install ADK

  • Create and activate a virtual environment (Recommended):

    # Create
python -m venv .venv
# Activate (uncomment the line relevant to your environment)
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

  • Install ADK:

    pip install google-adk

Create an agent

Using the terminal, create the folder structure:

mkdir multi_tool_agent/
touch \
multi_tool_agent/__init__.py \
multi_tool_agent/agent.py \
multi_tool_agent/.env

Your structure:

parent_folder/
    multi_tool_agent/
        __init__.py
        agent.py
        .env

Copy and paste the following code into the following three files you created:

__init__.py

from . import agent

.env

# If using Gemini via Vertex AI on Google CLoud
GOOGLE_CLOUD_PROJECT="your-project-id"
GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1
GOOGLE_GENAI_USE_VERTEXAI="True"

agent.py

from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Returns:
        dict: A dictionary containing the weather information with a 'status' key ('success' or 'error') and a 'report' key with the weather details if successful, or an 'error_message' if an error occurred.
    """
    if city.lower() == "new york":
        return {"status": "success",
                "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit)."}
    else:
        return {"status": "error",
                "error_message": f"Weather information for '{city}' is not available."}

def get_current_time(city:str) -> dict:
    """Returns the current time in a specified city.

    Args:
        dict: A dictionary containing the current time for a specified city information with a 'status' key ('success' or 'error') and a 'report' key with the current time details in a city if successful, or an 'error_message' if an error occurred.
    """
    import datetime
    from zoneinfo import ZoneInfo

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {"status": "error",
                "error_message": f"Sorry, I don't have timezone information for {city}."}

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return {"status": "success",
            "report": f"""The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}"""}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash",
    description="Agent to answer questions about the time and weather in a city.",
    instruction="I can answer your questions about the time and weather in a city.",
    tools=[get_weather, get_current_time]
)

The agent is equipped with two function tools with mock implementations.

Run and test your agent

  1. In the terminal, navigate to the agent's parent directory (for example, using cd ..):

    parent_folder/      <-- navigate to this directory
    multi_tool_agent/
        __init__.py
        agent.py
        .env

  2. Run the following command to launch the developer Web UI.

    adk web

    Open the URL provided (usually http://localhost:8000 or http://127.0.0.1:8000) in your browser. This connection stays entirely on your local machine. Select multi_tool_agent and interact with the agent.

Example prompts to try

You can try the following prompts:

  • What is the weather in New York?
  • What is the time in New York?
  • What is the weather in Paris?
  • What is the time in Paris?

What's next