Environment Setup: API Keys and SDK Installation

Theory is important, but true mastery comes from the keyboard. In this module, we transition from architectural concepts to hands-on development. To build with the Gemini ADK, you need a reliable bridge between your local code and Google's high-performance AI infrastructure.

In this lesson, we will walk through the three essential pillars of environment setup: Obtaining your Identity (API Keys), Installing the SDK (The Library), and Workspace Configuration. By the end of this page, you will have a working script that proves your system is ready for agentic development.

1. Step 1: Obtaining your API Key

Google provides the Gemini family of models through two primary channels: AI Studio (for developers and hobbyists) and Vertex AI (for enterprise-scale cloud integration). For this course, we will focus on Google AI Studio due to its speed, ease of use, and generous free tier.

The Path to Your Key:

Navigate to Google AI Studio.
Log in with your Google Account.
In the left-hand sidebar, click on "Get API key".
Click "Create API key in new project".
CRITICAL: Copy this key and save it in a secure location (e.g., a password manager). Never share this key or upload it to GitHub.

2. Step 2: Preparing Your Python Environment

The Gemini ADK is built on top of the google-generativeai Python library. We recommend using a Virtual Environment (venv) to ensure that your agent's dependencies don't clash with other projects on your machine.

Terminal Setup (Mac/Linux/Windows):

# 1. Create a project directory
mkdir my-gemini-agent
cd my-gemini-agent

# 2. Create a virtual environment
python3 -m venv venv

# 3. Activate the environment
# On Mac/Linux:
source venv/bin/activate
# On Windows:
.\venv\Scripts\activate

# 4. Install the SDK
pip install -U google-generativeai python-dotenv

3. Step 3: Secret Management with `.env`

To keep your API keys out of your source code, we use a .env file.

In your project folder, create a new file named .env.

Open it and add your key like this:

GEMINI_API_KEY=your_actual_key_here_no_quotes

Create a .gitignore file and add .env to it to prevent accidental commits.

4. Step 4: The Connectivity Test (The "Ping")

Before building a complex agent, we must ensure the "pipe" is open. create a file named ping.py:

import os
import google.generativeai as genai
from dotenv import load_dotenv

# 1. Load the Key
load_dotenv()
api_key = os.getenv("GEMINI_API_KEY")

if not api_key:
    print("Error: No API key found. Check your .env file.")
    exit()

# 2. Configure the SDK
genai.configure(api_key=api_key)

# 3. Simple Connectivity Check
try:
    model = genai.GenerativeModel('gemini-1.5-flash')
    response = model.generate_content("Ping!")
    print(f"Connection Successful! Model responded: {response.text}")
except Exception as e:
    print(f"Connection Failed: {e}")

graph LR
    A[Your Computer] -->|API Key + Request| B[Google Gateway]
    B -->|Route to Region| C[Gemini Inference Engine]
    C -->|JSON Response| B
    B -->|Tokens| D[Your Python SDK]
    
    style C fill:#4285F4,color:#fff

5. Troubleshooting Common Issues

A. "ModuleNotFoundError: No module named 'google'"

Cause: You installed the library but didn't activate your virtual environment, or you are using a different Python interpreter than the one in the venv.
Fix: Run source venv/bin/activate and then pip list to verify google-generativeai is present.

B. "API_KEY_INVALID" or 403 Forbidden

Cause: Your API key is copied incorrectly, or your project doesn't have the Gemini API enabled in AI Studio.
Fix: Re-generate the key and ensure there are no leading/trailing spaces in your .env file.

C. "Resource Exhausted" (429 Error)

Cause: You have hit the rate limit for the free tier.
Fix: Wait 60 seconds and try again. For production, you may need to enable billing in Google Cloud.

6. Pro Tip: Using the `genai.list_models()` tool

Sometimes you might be unsure which models you have access to. You can use the SDK to query the available model family.

for m in genai.list_models():
  if 'generateContent' in m.supported_generation_methods:
    print(f"Model ID: {m.name} | Capabilities: {m.display_name}")

7. Workspace Best Practices

As you move forward, keep your workspace organized:

/assets: Store images, PDFs, or audio files for multimodal tests.
/src/tools: Keep your custom Python functions here.
/src/prompts: Keep your YAML persona files here.
/logs: Store the output of your agent sessions for debugging.

8. Summary and Exercises

Setting up the environment is the first step in the Agent Lifecycle.

Google AI Studio is your portal to API keys.
Virtual Environments prevent dependency hell.
.env files protect your credentials.
The Ping Test verifies the high-speed link to Gemini.

Exercises

Configuration Check: Run the ping.py script. Does it work? If not, identify the specific error code (e.g., 401, 403, 404).
SDK Exploration: Use the genai.list_models() code provided above. Which is the newest model version available in your region?
Security Audit: Search your project directory for any plain-text instances of your API key. If you find one, delete it and move it to the .env file immediately.

In the next lesson, we will build our first Hello World Agent—moving from a simple "Ping" to an interactive, persona-driven conversation.