Level: Beginner ยท Env: Google Cloud Shell (browser terminal, no local install required)
A single conversational agent that answers weather and time questions using two custom tools you write yourself - then you'll deploy it to Cloud Run and call it over HTTP like a real service.
By the end you'll be able to:
Agent is (model + instruction + tools)adk CLIMake sure you completed the one-time setup before starting: APIs enabled, GOOGLE_API_KEY or Vertex vars exported, venv active, adk --version works. Do this in Cloud Shell, in the google-adk/ folder.
First, grab the workshop repo and move into the google-adk/ folder - everything else in both workshops assumes you're sitting here:
git clone https://github.com/adityajoshi12/ai-workshops/
cd ai-workshops/google-adk
gcloud config set project YOUR_PROJECT_ID
gcloud services enable \
aiplatform.googleapis.com \
generativelanguage.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk requests
adk --version
What each API is actually for:
API | Why you need it |
| Vertex AI backend for Gemini (if you go the Vertex route) |
| Gemini Developer API backend (if you go the API-key route) |
| Cloud Run - where the agent gets deployed |
|
|
| Stores the built container image |
| Service account permissions for the above |
Pick one Gemini backend:
Option A - Gemini Developer API (simplest):
export GOOGLE_API_KEY="YOUR_GEMINI_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
Option B - Vertex AI (uses your GCP project's quota/billing):
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
Not sure which to pick? Both work identically for this workshop - the agent's Python code never changes, only these environment variables do - but here's the practical difference:
Option A: API key | Option B: Vertex AI | |
Setup effort | Lowest - one key, no IAM | A bit more - needs ADC login + IAM role |
Good for | Workshops, quick demos, personal projects | Teams already using GCP quota/billing/IAM |
Auth locally |
|
|
Auth on Cloud Run | Same | The Cloud Run service's own service account (no key to leak!) |
Rate limits / billing | Tied to the free-tier key | Tied to your GCP project's Vertex AI quota |
adk create my_agent
This generates:
my_agent/
__init__.py # from . import agent
agent.py # your root_agent lives here
.env # env vars auto-loaded by ADK (API key / Vertex config)
Open it in the Cloud Shell Editor (pencil icon, top-right) - it's just VS Code in your browser.
Drop your backend choice into my_agent/.env - pick ONE:
Option A - Gemini Developer API:
Get you Gemini API Key from Google AI Studio
export GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
Option B - Vertex AI:
export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
(Requires gcloud auth application-default login to have already run.)
Nothing else in this workshop changes based on which one you pick - every tool and every line of agent.py you write from here is backend-agnostic.
Open the generated agent.py. Every ADK agent boils down to four things:
my_agent/agent.py
from google.adk.agents import Agent
root_agent = Agent(
model="gemini-3.5-flash", # which LLM powers it
name="root_agent", # unique id
description="...", # used by OTHER agents to decide to route to this one
instruction="...", # the system prompt - the agent's "job description"
tools=[], # python functions the model can call
)
The instruction is doing the heavy lifting: it tells the model what it's allowed to do, and - crucially - when to reach for a tool instead of guessing an answer.
When a user asks a question, the agent follows this loop:
flowchart TD A[User message] --> B[Model reads instruction and tool schemas] B --> C[Model chooses a tool and supplies arguments] C --> D[Python tool runs and returns a structured result] D --> E[Model turns the result into a response]
The model does not run your Python function to decide what to do. It sees the function name, type hints, and docstring as a tool schema, then requests a tool call when one matches the user's intent. The ADK runtime executes that call and sends the result back to the model.
A "tool" in ADK is just a plain Python function with a docstring. The docstring is the tool's API contract - the model reads it to decide whether and how to call it. Add this to agent.py:
import requests
def get_weather(city: str) -> dict:
"""Return the current weather for a given city.
Args:
city: Name of the city, e.g. "Bengaluru". Case-insensitive.
Returns:
On success: {"status": "ok", "city": "<City>", "weather": "<summary>"}
On failure: {"status": "error", "error_message": "<details>"}
"""
try:
response = requests.get(f"https://wttr.in/{city}?format=3", timeout=10)
response.raise_for_status()
return {"status": "ok", "city": city.title(), "weather": response.text.strip()}
except requests.RequestException as e:
return {"status": "error", "error_message": f"Failed to fetch weather: {e}"}
Two rules that matter a lot more than they look like they should:
status key - it gives the model (and the instruction) a clean way to branch on success/failure instead of guessing from free text.from datetime import datetime
from zoneinfo import ZoneInfo
_CITY_TZ = {
"bengaluru": "Asia/Kolkata",
"london": "Europe/London",
"new york": "America/New_York",
"tokyo": "Asia/Tokyo",
}
def get_current_time(city: str) -> dict:
"""Return the current local time for a given city.
Args:
city: Name of the city, e.g. "Tokyo". Case-insensitive.
Returns:
On success: {"status": "ok", "city", "current_time"}.
On failure: {"status": "error", "error_message"} if unsupported.
"""
tz_name = _CITY_TZ.get(city.strip().lower())
if tz_name is None:
return {
"status": "error",
"error_message": f"No timezone for '{city}'. Supported: {', '.join(sorted(_CITY_TZ))}.",
}
now = datetime.now(ZoneInfo(tz_name))
return {"status": "ok", "city": city.title(), "current_time": now.strftime("%Y-%m-%d %H:%M:%S %Z")}
root_agent = Agent(
model="gemini-3.5-flash",
name="root_agent",
description="A helpful assistant that answers weather and time questions.",
instruction=(
"You are a friendly assistant. "
"Use the get_weather tool for weather questions and the "
"get_current_time tool for time questions. "
"If a tool returns status 'error', apologize and pass along the "
"error_message so the user knows which cities are supported. "
"Never invent weather or time data - always call a tool."
),
tools=[get_weather, get_current_time],
)
Option A - Web UI (recommended for the trace panel):
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
Cloud Shell will offer a Web Preview on port 8000 - click it, pick my_agent from the dropdown, and chat. Open the trace/events panel and watch the model decide to call get_weather - that decision is the whole point of the demo.
Option B - Terminal chat:
adk run my_agent
Try:
error_message instead of making something up.For the Tokyo weather prompt, find these events in the trace panel:
get_weather and its city argument.status, city, and weather.The trace is useful because it separates a tool problem from an instruction problem. If no tool call appears, inspect the tool name, docstring, and agent instruction. If a tool call appears but fails, inspect the Python function and its returned error details.
Do this yourself, ~10 min. Add a third tool of your own choosing. Ideas:
convert_currency(amount, from_currency, to_currency) (hit https://api.frankfurter.dev/v2/rates?date=2026-09-18"es=INR&base=usd)get_joke() (hit https://official-joke-api.appspot.com/random_joke)roll_dice(sides) (pure Python, no API needed - good if you're offline)Requirements: type hints, a docstring, and a status key in the return dict. Add it to tools=[...] and update the instruction to mention it.
Your tool is complete when all four prompts produce intentional behavior: one successful result, one invalid-input error, one request that clearly selects a different tool, and one request that the agent can answer without a tool.
The .env file is convenient for local development, but it contains credentials. Never commit it, paste an API key into agent.py, or expose an API key in browser-side code. Cloud Run should receive configuration through environment variables or use its runtime service account with Vertex AI.
The get_weather example also passes user input into a URL. In production, validate and encode inputs, set timeouts, limit response sizes, and handle provider errors. A tool should be a small, bounded capability, not an unrestricted path from user text to a system command.
Use the command matching the backend you picked earlier.
Option A - Gemini Developer API:
adk deploy cloud_run my_agent -- \
--region=us-central1 \
--set-env-vars=GOOGLE_API_KEY=YOUR_GEMINI_API_KEY,GOOGLE_GENAI_USE_VERTEXAI=FALSE
Option B - Vertex AI:
# One-time per project: let the Cloud Run service account call Vertex AI.
PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
PROJECT_ID=$(gcloud config get-value project)
adk deploy cloud_run my_agent \
--with_ui \
--region=us-central1 \
--set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--allow-unauthenticated
Note there's no API key anywhere in Option B - the deployed service authenticates as itself. This builds a container (via Cloud Build), pushes it to Artifact Registry, and deploys it to Cloud Run. Note the printed service URL, e.g.:
https://adk-default-service-name-XXXXXXXXXX.us-central1.run.app
Create a session:
export SERVICE_URL="https://adk-default-service-name-XXXXXXXXXX.us-central1.run.app"
curl -X POST "$SERVICE_URL/apps/my_agent/users/u_123/sessions/s_1" \
-H "Content-Type: application/json" \
-d '{}'
Send a message:
curl -X POST "$SERVICE_URL/run" \
-H "Content-Type: application/json" \
-d '{
"appName": "my_agent",
"userId": "u_123",
"sessionId": "s_1",
"newMessage": {
"role": "user",
"parts": [{"text": "What is the weather in London?"}]
}
}'
You should get back the full event stream, including the tool call and its result - same thing you saw in the local trace panel, just over the wire.
If you deploy with --allow-unauthenticated, anyone who discovers the URL can send requests and consume your configured model quota. Use that flag only for a short workshop demo, then delete the service or add authentication before using the endpoint for real users.
The agent answers from memory instead of calling a tool: Make the tool docstring specific, mention the tool by name in instruction, and keep the rule "Never invent weather or time data - always call a tool." Try a direct prompt such as "What time is it in Tokyo?"
The agent cannot import
requests
or
google.adk
: Check that the virtual environment is active and rerun pip install google-adk requests. Confirm with which python and adk --version.
The tool returns an error: Run the Python function by itself with a known city, inspect the exception, and verify that the returned object is a dictionary containing status and error_message.
Cloud Run returns an error: Check the deployed service logs with gcloud run services logs read SERVICE_NAME --region=us-central1, then verify the deployed environment variables and the runtime service account permissions.
Upgrade your agent into a small travel assistant. Keep the weather and time tools, then add one tool of your own that helps someone plan a trip. For example, add a currency converter, a joke tool for a long journey, or a dice roller for choosing between activities.
Your finished agent should:
Avoids ongoing cost:
gcloud run services delete adk-default-service-name --region=us-central1
status/error_message dicts from tools so the model - and your instruction - can react cleanly to failure.adk web / adk run for local iteration, adk deploy cloud_run to ship it.Workshop 1 used one agent that can act through tools. In Workshop 2, several specialized agents collaborate: tools let an agent do something, while sub-agents let an agent delegate work.