1. Einführung
Übersicht
In diesem Codelab stellen Sie einen ADK-Agent als Backend-Dienst in Cloud Run und dann ein Gradio-Frontend für den ADK-Agent als zweiten Cloud Run-Dienst bereit. In diesem Codelab wird gezeigt, wie Sie die Authentifizierung für Ihren ADK-Agent-Dienst erzwingen und authentifizierte Aufrufe vom Gradio-Frontend-Dienst aus an ihn senden.
Lerninhalte
- ADK-Agent in Cloud Run bereitstellen
- Gradio-App in Cloud Run bereitstellen
- Authentifizierte Dienst-zu-Dienst-Aufrufe in Cloud Run ausführen
2. APIs aktivieren
Legen Sie zuerst Ihr Google Cloud-Projekt fest.
gcloud config set project <YOUR_PROJECT_ID>
Sie können Ihr Google Cloud-Projekt mit dem folgenden Befehl bestätigen:
gcloud config get-value project
Für dieses Codelab müssen die folgenden APIs aktiviert werden:
gcloud services enable run.googleapis.com \
compute.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
aiplatform.googleapis.com
3. Einrichtung und Anforderungen
In diesem Abschnitt erstellen Sie einige Dienstkonten und weisen ihnen die entsprechenden IAM-Rollen zu. Jeder Cloud Run-Dienst hat ein eigenes Dienstkonto.
Legen Sie zuerst Umgebungsvariablen für dieses Codelab fest, die im gesamten Codelab verwendet werden.
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"
Erstellen Sie als Nächstes das Dienstkonto für den ADK-Agent.
gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"
Weisen Sie dem ADK-Dienstkonto die Rolle „Vertex AI-Nutzer“ zu.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
--role="roles/aiplatform.user"
Erstellen Sie nun das Dienstkonto für das Gradio-Frontend.
gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
--display-name="Service account for gradio frontend cloud run"
Weisen Sie dem Gradio-Frontend die Rolle „Cloud Run Invoker“ zu, damit es den in Cloud Run gehosteten ADK-Agent aufrufen kann.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_GRADIO" \
--role="roles/run.invoker"
4. ADK-App erstellen
Im nächsten Schritt erstellen Sie den Code für die ADK-Kurzanleitungsanwendung.
Hinweis: Am Ende des Labs sollte Ihre Dateistruktur so aussehen:
- 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
Erstellen Sie zuerst ein Verzeichnis für das gesamte Codelab.
mkdir codelab-gradio-adk
cd codelab-gradio-adk
Erstellen Sie nun ein Verzeichnis für den ADK-Agent-Dienst.
mkdir multi_tool_agent && cd multi_tool_agent
Erstellen Sie eine __init__.py-Datei mit folgendem Inhalt:
from . import agent
requirements.txt-Datei erstellen:
google-adk
Erstellen Sie eine Datei mit dem Namen 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. ADK-Agent bereitstellen
In diesem Abschnitt stellen Sie den ADK-Agent in Cloud Run bereit. Anschließend prüfen Sie mit der von ADK bereitgestellten Web-UI für Entwickler, ob die Bereitstellung funktioniert hat. Schließlich benötigen Sie authentifizierte Aufrufe für diesen Dienst.
Rufen Sie den übergeordneten Ordner auf.
HINWEIS:Der ADK-Agent-Code muss den Ordner multi_tool_agent als Stammordner enthalten.
cd ..
Erstellen Sie zuerst den Cloud Run-Dienst:
HINWEIS: --with_ui ist optional, wenn Sie die Entwickler-UI verwenden, wie in einem der nächsten Schritte gezeigt wird:
HINWEIS: Mit dem Befehl -- können Sie Befehlszeilen-Flags an den zugrunde liegenden Befehl gcloud run deploy übergeben.
HINWEIS: Mit uvx --from wird ein Befehl aus dem google-adk-Paket ausgeführt. Mit uvx wird eine temporäre virtuelle Umgebung erstellt, in der google-adk installiert wird. Anschließend wird der angegebene Befehl ausgeführt und die Umgebung wird wieder abgebaut.
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
Speichern Sie die URL als Umgebungsvariable, die Sie im zweiten Teil dieses Codelabs verwenden.
AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')
Agent jetzt ausprobieren
Öffnen Sie die Dienst-URL in Ihrem Webbrowser und fragen Sie tell me about the weather in new york. Sie sollten eine Antwort ähnlich der folgenden erhalten: „Das Wetter in New York ist sonnig mit einer Temperatur von 25 °C (77 °F).“
Agent schützen
Sichern wir jetzt den Zugriff auf den KI‑Agenten. Im nächsten Abschnitt stellen Sie einen Cloud Run-Dienst bereit, der einen authentifizierten Aufruf an diesen Backend-Dienst ausführt.
gcloud run services remove-iam-policy-binding adk-agent-cr \
--member="allUsers" \
--role="roles/run.invoker" \
--region=$REGION
6. Gradio-Frontend bereitstellen
In diesem Schritt erstellen Sie ein Gradio-Frontend für Ihren ADK-Agenten.
Hinweis: Die Gradio-App kann sich im selben Dienst wie der ADK-Agent befinden. In diesem Codelab werden zwei separate Dienste bereitgestellt, um zu zeigen, wie authentifizierte Dienst-zu-Dienst-Aufrufe in Cloud Run erfolgen.
Erstellen Sie zuerst eine App neben dem Ordner „multi_tool_agent“.
mkdir gradio-frontend && cd gradio-frontend
Erstellen Sie als Nächstes eine requirements.txt-Datei, die Folgendes enthält:
gradio
requests
google-auth
Jetzt eine app.py-Datei erstellen
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. Gradio-App bereitstellen und testen
In diesem Schritt stellen Sie die Gradio-Frontend-App in Cloud Run bereit.
Achten Sie darauf, dass Sie sich im Verzeichnis der Gradio-App befinden.
pwd
Hier sollten Sie codelab-gradio-adk/gradio-frontend sehen.
Stellen Sie jetzt Ihre Gradio-App bereit.
Hinweis: Obwohl dieser Gradio-Frontend-Dienst eine öffentlich verfügbare Website ist, erfordert der Backend-Dienst eine Authentifizierung. Um zu veranschaulichen, warum Sie das tun sollten, könnten Sie diesem Frontend-Dienst die Nutzerauthentifizierung (z.B. Firebase Auth) hinzufügen und dann nur Nutzern, die angemeldet sind, erlauben, den Backend-Dienst aufzurufen.
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
Nach der Bereitstellung sollten Sie auf die Frage what's the weather in new york? eine Antwort ähnlich der folgenden erhalten: The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).
8. Glückwunsch!
Herzlichen Glückwunsch zum Abschluss des Codelabs!
Wir empfehlen, die Dokumentation zum Hosten von KI-Apps und ‑Agents zu lesen.
Behandelte Themen
- ADK-Agent in Cloud Run bereitstellen
- Gradio-App in Cloud Run bereitstellen
- Authentifizierte Dienst-zu-Dienst-Aufrufe in Cloud Run ausführen
9. Bereinigen
Um unbeabsichtigte Gebühren zu vermeiden, z. B. wenn die Cloud Run-Dienste versehentlich öfter aufgerufen werden als Ihre monatliche Cloud Run-Aufrufkontingent im kostenlosen Kontingent, können Sie den in Schritt 6 erstellten Cloud Run-Dienst löschen.
Wenn Sie die Cloud Run-Dienste löschen möchten, rufen Sie die Cloud Run Cloud Console unter https://console.cloud.google.com/run auf und löschen Sie die Dienste my-adk-gradio-frontend und adk-agent-cr.
Wenn Sie das gesamte Projekt löschen möchten, rufen Sie Ressourcen verwalten auf, wählen Sie das Projekt aus, das Sie in Schritt 2 erstellt haben, und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie das Projekt in Ihrem Cloud SDK ändern. Sie können die Liste aller verfügbaren Projekte mit gcloud projects list aufrufen.