1. Introduzione
Panoramica
In questo codelab, eseguirai il deployment di un agente ADK in Cloud Run come servizio di backend, quindi eseguirai il deployment di un frontend gradio per l'agente ADK come secondo servizio Cloud Run. Questo codelab mostra come richiedere l'autenticazione al servizio agente ADK ed effettuare chiamate autenticate dal servizio frontend gradio.
Obiettivi didattici
- Come eseguire il deployment di un agente ADK in Cloud Run
- Come eseguire il deployment di un'app Gradio in Cloud Run
- Come effettuare chiamate autenticate da servizio a servizio in Cloud Run
2. Abilita API
Innanzitutto, imposta il progetto Google Cloud.
gcloud config set project <YOUR_PROJECT_ID>
Puoi confermare il tuo progetto Google Cloud eseguendo questo comando:
gcloud config get-value project
Questo codelab richiede l'abilitazione delle seguenti API:
gcloud services enable run.googleapis.com \
compute.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
aiplatform.googleapis.com
3. Configurazione e requisiti
In questa sezione, creerai un paio di service account e assegnerai loro i ruoli IAM appropriati. Ogni servizio Cloud Run avrà il proprio account di servizio.
Innanzitutto, imposta le variabili di ambiente per questo codelab, che verranno utilizzate durante tutto il codelab.
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"
Successivamente, crea il service account per l'agente ADK.
gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"
e concedi al service account ADK il ruolo "Utente Vertex AI".
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
--role="roles/aiplatform.user"
Ora crea il service account per il frontend Gradio
gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
--display-name="Service account for gradio frontend cloud run"
Concedi al frontend Gradio il ruolo Invoker di Cloud Run, che gli consentirà di chiamare l'agente ADK ospitato su Cloud Run.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_GRADIO" \
--role="roles/run.invoker"
4. Crea un'app ADK
Nel passaggio successivo, creerai il codice per l'applicazione di avvio rapido dell'ADK.
Nota: al termine del lab, la struttura dei file dovrebbe essere simile alla seguente:
- 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
Per prima cosa, crea una directory per il codelab complessivo
mkdir codelab-gradio-adk
cd codelab-gradio-adk
Ora crea una directory per il servizio agente ADK.
mkdir multi_tool_agent && cd multi_tool_agent
Crea un file __init__.py con i seguenti contenuti:
from . import agent
Crea un file requirements.txt:
google-adk
Crea un file denominato 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. Esegui il deployment dell'agente ADK
In questa sezione, eseguirai il deployment dell'agente ADK in Cloud Run. Poi verificherai che il deployment funzioni utilizzando la UI web di sviluppo fornita da ADK. Infine, dovrai richiedere chiamate autenticate a questo servizio.
Vai alla cartella principale.
NOTA:il codice dell'agente ADK deve includere la cartella multi_tool_agent come cartella principale.
cd ..
Innanzitutto, crea il servizio Cloud Run:
NOTA: --with_ui è facoltativo per il test con la UI di sviluppo, come mostrato in un passaggio successivo:
NOTA: il comando -- consente di passare i flag della riga di comando al comando gcloud run deploy sottostante.
NOTA: uvx --from esegue un comando dal pacchetto google-adk. uvx creerà un ambiente virtuale temporaneo, installerà google-adk, eseguirà il comando specificato e poi distruggerà l'ambiente.
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
A questo punto, salva l'URL come variabile di ambiente che utilizzerai nella seconda parte di questo codelab.
AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')
Ora prova l'agente
Apri l'URL del servizio nel browser web e chiedi tell me about the weather in new york. Dovresti visualizzare una risposta simile a "A New York il tempo è soleggiato con una temperatura di 25 gradi Celsius (77 gradi Fahrenheit)".
Infine, proteggi l'agente
Ora proteggiamo l'accesso all'agente. Nella sezione successiva, eseguirai il deployment di un servizio Cloud Run che effettua una chiamata autenticata a questo servizio di backend.
gcloud run services remove-iam-policy-binding adk-agent-cr \
--member="allUsers" \
--role="roles/run.invoker" \
--region=$REGION
6. Esegui il deployment di un front-end Gradio
In questo passaggio creerai un frontend Gradio per l'agente ADK
Nota: puoi avere l'app gradio nello stesso servizio dell'agente ADK. Questo codelab fornisce due servizi separati per mostrare come effettuare chiamate autenticate da servizio a servizio in Cloud Run.
Innanzitutto, crea un'app insieme alla cartella multi_tool_agent
mkdir gradio-frontend && cd gradio-frontend
Successivamente, crea un file requirements.txt che contenga quanto segue:
gradio
requests
google-auth
Ora crea un 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. Esegui il deployment e testa l'app Gradio
In questo passaggio, eseguirai il deployment dell'app Gradio di frontend su Cloud Run.
Assicurati di trovarti nella directory dell'app gradio.
pwd
Dovresti vedere codelab-gradio-adk/gradio-frontend
Ora esegui il deployment dell'app Gradio.
Nota: anche se questo servizio frontend di Gradio è un sito web disponibile pubblicamente, il servizio di backend richiede l'autenticazione. Per illustrare il motivo per cui potresti volerlo fare, potresti aggiungere l'autenticazione utente (ad es. Firebase Auth) a questo servizio di frontend e poi consentire solo agli utenti che hanno eseguito l'accesso di effettuare chiamate al servizio di 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
Una volta eseguito il deployment, chiedi what's the weather in new york? e dovresti ricevere una risposta simile a The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).
8. Complimenti!
Congratulazioni per aver completato il codelab.
Ti consigliamo di consultare la documentazione sull'hosting di app e agenti di AI.
Argomenti trattati
- Come eseguire il deployment di un agente ADK in Cloud Run
- Come eseguire il deployment di un'app Gradio in Cloud Run
- Come effettuare chiamate autenticate da servizio a servizio in Cloud Run
9. Esegui la pulizia
Per evitare addebiti involontari, ad esempio se i servizi Cloud Run vengono richiamati inavvertitamente più volte rispetto all'allocazione mensile di chiamate di Cloud Run nel livello senza costi, puoi eliminare il servizio Cloud Run creato nel passaggio 6.
Per eliminare i servizi Cloud Run, vai alla console Cloud Run all'indirizzo https://console.cloud.google.com/run ed elimina i servizi my-adk-gradio-frontend e adk-agent-cr.
Per eliminare l'intero progetto, vai a Gestisci risorse, seleziona il progetto che hai creato nel passaggio 2 e scegli Elimina. Se elimini il progetto, dovrai cambiarlo in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.