1. Pengantar
Ringkasan
Dalam codelab ini, Anda akan men-deploy agen ADK ke Cloud Run sebagai layanan backend, lalu men-deploy frontend gradio untuk agen ADK sebagai layanan Cloud Run kedua. Codelab ini menunjukkan cara mewajibkan autentikasi ke layanan agen ADK Anda dan melakukan panggilan yang diautentikasi ke layanan tersebut dari layanan frontend gradio.
Yang akan Anda pelajari
- Cara men-deploy agen ADK ke Cloud Run
- Cara men-deploy aplikasi gradio ke Cloud Run
- Cara melakukan panggilan antar layanan yang diautentikasi di Cloud Run
2. Mengaktifkan API
Pertama, tetapkan project Google Cloud Anda.
gcloud config set project <YOUR_PROJECT_ID>
Anda dapat mengonfirmasi project Google Cloud dengan menjalankan perintah berikut:
gcloud config get-value project
Codelab ini mengharuskan Anda mengaktifkan API berikut:
gcloud services enable run.googleapis.com \
compute.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
aiplatform.googleapis.com
3. Penyiapan dan Persyaratan
Di bagian ini, Anda akan membuat beberapa akun layanan dan memberikan peran IAM yang sesuai kepada akun tersebut. Setiap layanan Cloud Run akan memiliki Akun Layanan sendiri.
Pertama, tetapkan variabel lingkungan untuk codelab ini yang akan digunakan di seluruh codelab ini.
export PROJECT_ID=<YOUR_PROJECT_ID>
export REGION=<YOUR_REGION>
export SERVICE_ACCOUNT_ADK="adk-agent-cr"
export SERVICE_ACCOUNT_ADDRESS_ADK=$SERVICE_ACCOUNT_ADK@$PROJECT_ID.iam.gserviceaccount.com
export SERVICE_ACCOUNT_GRADIO="adk-agent-gradio"
export SERVICE_ACCOUNT_ADDRESS_GRADIO=$SERVICE_ACCOUNT_GRADIO@$PROJECT_ID.iam.gserviceaccount.com
export AGENT_APP_NAME="multi_tool_agent"
Selanjutnya, buat akun layanan untuk agen ADK.
gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"
Lalu, berikan peran "Vertex AI User" ke akun layanan ADK
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
--role="roles/aiplatform.user"
Sekarang, buat akun layanan untuk frontend Gradio
gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
--display-name="Service account for gradio frontend cloud run"
Kemudian, berikan peran pemanggil Cloud Run ke frontend Gradio, yang akan memungkinkannya memanggil agen ADK yang dihosting di Cloud Run.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_GRADIO" \
--role="roles/run.invoker"
4. Membuat aplikasi ADK
Pada langkah berikutnya, Anda akan membuat kode untuk aplikasi mulai cepat ADK.
Catatan: di akhir lab, struktur file Anda akan terlihat seperti berikut:
- codelab-gradio-adk <-- you'll deploy the ADK agent from here
- gradio-frontend
- app.py
- requirements.txt
- multi_tool_agent <-- you'll deploy the gradio app from here
- __init__.py
- agent.py
- requirements.txt
Pertama, buat direktori untuk codelab secara keseluruhan
mkdir codelab-gradio-adk
cd codelab-gradio-adk
Sekarang, buat direktori untuk layanan agen ADK.
mkdir multi_tool_agent && cd multi_tool_agent
Buat file __init__.py dengan konten berikut:
from . import agent
Buat file requirements.txt:
google-adk
Buat file bernama agent.py
import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent
def get_weather(city: str) -> dict:
"""Retrieves the current weather report for a specified city.
Args:
city (str): The name of the city for which to retrieve the weather report.
Returns:
dict: status and result or error msg.
"""
if city.lower() == "new york":
return {
"status": "success",
"report": (
"The weather in New York is sunny with a temperature of 25 degrees"
" Celsius (77 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:
city (str): The name of the city for which to retrieve the current time.
Returns:
dict: status and result or error msg.
"""
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)
report = (
f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
)
return {"status": "success", "report": report}
root_agent = Agent(
name="weather_time_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about the time and weather in a city."
),
instruction=(
"You are a helpful agent who can answer user questions about the time and weather in a city."
),
tools=[get_weather, get_current_time],
)
5. Men-deploy agen ADK
Di bagian ini, Anda akan men-deploy agen ADK ke Cloud Run. Kemudian, Anda akan memverifikasi bahwa deployment berfungsi menggunakan UI web dev yang disediakan oleh ADK. Terakhir, Anda akan memerlukan panggilan terautentikasi ke layanan ini.
Buka folder induk.
CATATAN: Kode agen ADK harus menyertakan folder multi_tool_agent sebagai folder root-nya.
cd ..
Pertama, buat layanan Cloud Run:
CATATAN: --with_ui bersifat opsional untuk pengujian dengan UI Dev, seperti yang ditunjukkan pada langkah berikutnya:
CATATAN: perintah -- memungkinkan Anda meneruskan flag command line ke perintah gcloud run deploy yang mendasarinya.
CATATAN: uvx --from menjalankan perintah dari paket google-adk. uvx akan membuat lingkungan virtual sementara, menginstal google-adk ke dalamnya, menjalankan perintah yang ditentukan, lalu menghapus lingkungan.
uvx --from google-adk \
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=$REGION \
--service_name=adk-agent-cr \
--with_ui \
./multi_tool_agent \
-- \
--service-account=$SERVICE_ACCOUNT_ADDRESS_ADK \
--allow-unauthenticated
Selanjutnya, simpan URL sebagai variabel lingkungan yang akan Anda gunakan di bagian kedua codelab ini
AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')
Sekarang, coba agennya
Buka URL layanan di browser web Anda dan tanyakan, tell me about the weather in new york. Anda akan melihat respons yang mirip dengan "Cuaca di New York cerah dengan suhu 25 derajat Celsius (77 derajat Fahrenheit)."
Terakhir, Amankan agen
Sekarang, mari amankan akses ke agen. Di bagian berikutnya, Anda akan men-deploy layanan Cloud Run yang melakukan panggilan yang diautentikasi ke layanan backend ini.
gcloud run services remove-iam-policy-binding adk-agent-cr \
--member="allUsers" \
--role="roles/run.invoker" \
--region=$REGION
6. Men-deploy frontend gradio
Pada langkah ini, Anda akan membuat frontend gradio untuk agen ADK
Catatan: Anda dapat memiliki aplikasi gradio di layanan yang sama dengan agen ADK. Codelab ini menyediakan 2 layanan terpisah untuk menunjukkan cara melakukan panggilan antar layanan yang diautentikasi di Cloud Run.
Pertama, buat aplikasi di samping folder multi_tool_agent
mkdir gradio-frontend && cd gradio-frontend
Selanjutnya, buat file requirements.txt yang berisi
gradio
requests
google-auth
Sekarang, buat file app.py
import gradio as gr
import requests
import json
import uuid
import os
import google.auth.transport.requests
import google.oauth2.id_token
# https://weather-time-service2-392295011265.us-west4.run.app
BASE_URL = os.environ.get("AGENT_SERVICE_URL")
# multi_tool_agent
APP_NAME = os.environ.get("AGENT_APP_NAME")
# Generate a unique user ID for each session of the Gradio app
USER_ID = f"gradio-user-{uuid.uuid4()}"
# API Endpoints
CREATE_SESSION_URL = f"{BASE_URL}/apps/{APP_NAME}/users/{USER_ID}/sessions"
RUN_SSE_URL = f"{BASE_URL}/run_sse"
def get_id_token():
"""Get an ID token to authenticate with the other Cloud Run service."""
audience = BASE_URL
request = google.auth.transport.requests.Request()
id_token = google.oauth2.id_token.fetch_id_token(request, audience)
return id_token
def create_session() -> str | None:
"""Creates a new session and returns the session ID."""
try:
id_token = get_id_token()
headers = {"Authorization": f"Bearer {id_token}"}
response = requests.post(CREATE_SESSION_URL, headers=headers)
response.raise_for_status()
return response.json().get("id")
except Exception as e:
print(f"Error creating session: {e}")
return None
def query_agent(prompt: str):
"""Sends a prompt to the agent and returns the streamed response."""
session_id = create_session()
if not session_id:
return "Error: Could not create a session."
id_token = get_id_token()
headers = {
"Content-Type": "application/json",
"Accept": "text/event-stream",
"Authorization": f"Bearer {id_token}",
}
payload = {
"app_name": APP_NAME,
"user_id": USER_ID,
"session_id": session_id,
"new_message": {"role": "user", "parts": [{"text": prompt}]},
"streaming": True
}
full_response = ""
try:
with requests.post(RUN_SSE_URL, headers=headers, json=payload, stream=True) as response:
response.raise_for_status()
for chunk in response.iter_lines():
if chunk and chunk.decode('utf-8').startswith('data:'):
json_data = chunk.decode('utf-8')[len('data:'):].strip()
try:
data = json.loads(json_data)
text = data.get("content", {}).get("parts", [{}])[0].get("text", "")
if text:
full_response = text
except json.JSONDecodeError:
pass # Ignore chunks that are not valid JSON
return full_response
except requests.exceptions.RequestException as e:
return f"An error occurred: {e}"
iface = gr.Interface(
fn=query_agent,
inputs=gr.Textbox(lines=2, placeholder="e.g., What's the weather in new york?"),
outputs="text",
title="Weather and Time Agent",
description="Ask a question about the weather or time in a specific location.",
)
if __name__ == "__main__":
iface.launch()
7. Men-deploy dan menguji aplikasi gradio
Pada langkah ini, Anda akan men-deploy aplikasi gradio front-end ke Cloud Run.
Pastikan Anda berada di direktori aplikasi gradio.
pwd
Anda akan melihat codelab-gradio-adk/gradio-frontend
Sekarang deploy aplikasi gradio Anda.
Catatan: meskipun layanan frontend gradio ini adalah situs yang tersedia secara publik, layanan backend memerlukan autentikasi. Untuk mengilustrasikan alasan Anda mungkin ingin melakukan hal ini, Anda dapat menambahkan autentikasi pengguna (misalnya, Firebase Auth) ke layanan frontend ini, lalu hanya mengizinkan pengguna yang login untuk melakukan panggilan ke layanan backend.
gcloud run deploy my-adk-gradio-frontend \
--source . \
--region $REGION \
--allow-unauthenticated \
--set-env-vars AGENT_SERVICE_URL=$AGENT_SERVICE_URL,AGENT_APP_NAME=$AGENT_APP_NAME \
--service-account=$SERVICE_ACCOUNT_ADDRESS_GRADIO
Setelah di-deploy, tanyakan what's the weather in new york? dan Anda akan mendapatkan respons yang mirip dengan The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).
8. Selamat!
Selamat, Anda telah menyelesaikan codelab.
Sebaiknya tinjau dokumentasi tentang menghosting aplikasi dan agen AI.
Yang telah kita bahas
- Cara men-deploy agen ADK ke Cloud Run
- Cara men-deploy aplikasi gradio ke Cloud Run
- Cara melakukan panggilan antar layanan yang diautentikasi di Cloud Run
9. Pembersihan
Untuk menghindari tagihan yang tidak disengaja, misalnya, jika layanan Cloud Run dipanggil secara tidak sengaja lebih banyak daripada alokasi pemanggilan Cloud Run bulanan Anda di tingkat gratis, Anda dapat menghapus layanan Cloud Run yang Anda buat di Langkah 6.
Untuk menghapus layanan Cloud Run, buka Konsol Cloud Run di https://console.cloud.google.com/run, lalu hapus layanan my-adk-gradio-frontend dan adk-agent-cr.
Untuk menghapus seluruh project, buka Manage Resources, pilih project yang Anda buat di Langkah 2, lalu pilih Hapus. Jika menghapus project, Anda harus mengubah project di Cloud SDK. Anda dapat melihat daftar semua project yang tersedia dengan menjalankan gcloud projects list.