1. Wprowadzenie
Przegląd
W tym laboratorium dowiesz się, jak wdrożyć agenta ADK w Cloud Run jako usługę backendu, a następnie wdrożyć frontend gradio dla agenta ADK jako drugą usługę Cloud Run. W tym laboratorium pokazujemy, jak wymagać uwierzytelniania w usłudze agenta ADK i wykonywać w niej uwierzytelnione wywołania z usługi frontendowej gradio.
Czego się nauczysz
- Jak wdrożyć agenta ADK w Cloud Run
- Jak wdrożyć aplikację Gradio w Cloud Run
- Jak wykonywać uwierzytelnione wywołania między usługami w Cloud Run
2. Włącz interfejsy API
Najpierw ustaw projekt Google Cloud.
gcloud config set project <YOUR_PROJECT_ID>
Aby sprawdzić projekt Google Cloud, uruchom to polecenie:
gcloud config get-value project
To ćwiczenie z programowania wymaga włączenia tych interfejsów API:
gcloud services enable run.googleapis.com \
compute.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
aiplatform.googleapis.com
3. Konfiguracja i wymagania
W tej sekcji utworzysz kilka kont usługi i przypiszesz im odpowiednie role uprawnień. Każda usługa Cloud Run będzie mieć własne konto usługi.
Najpierw ustaw zmienne środowiskowe, które będą używane w tym module.
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"
Następnie utwórz konto usługi dla agenta ADK.
gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"
i przypisz do konta usługi ADK rolę „Użytkownik Vertex AI”.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
--role="roles/aiplatform.user"
Teraz utwórz konto usługi dla interfejsu Gradio.
gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
--display-name="Service account for gradio frontend cloud run"
Następnie przyznaj frontendowi Gradio rolę wywołującego w Cloud Run, która umożliwi mu wywoływanie agenta ADK hostowanego w Cloud Run.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_GRADIO" \
--role="roles/run.invoker"
4. Tworzenie aplikacji ADK
W następnym kroku utworzysz kod aplikacji z krótkiego wprowadzenia do ADK.
Uwaga: po zakończeniu modułu struktura plików powinna wyglądać tak:
- 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
Najpierw utwórz katalog dla całego laboratorium
mkdir codelab-gradio-adk
cd codelab-gradio-adk
Teraz utwórz katalog dla usługi agenta ADK.
mkdir multi_tool_agent && cd multi_tool_agent
Utwórz plik __init__.py o tej zawartości:
from . import agent
Utwórz plik requirements.txt:
google-adk
Utwórz plik o nazwie 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. Wdrażanie agenta ADK
W tej sekcji wdrożysz agenta pakietu ADK w Cloud Run. Następnie sprawdzisz, czy wdrożenie się powiodło, korzystając z interfejsu internetowego dla programistów udostępnianego przez ADK. Na koniec musisz mieć uwierzytelnione wywołania tej usługi.
Otwórz folder nadrzędny.
UWAGA: kod agenta ADK musi zawierać folder multi_tool_agent jako folder główny.
cd ..
Najpierw utwórz usługę Cloud Run:
UWAGA: --with_ui jest opcjonalne w przypadku testowania w interfejsie programisty, jak pokazano w kolejnym kroku:
UWAGA: polecenie -- umożliwia przekazywanie flag wiersza poleceń do polecenia gcloud run deploy.
UWAGA: polecenie uvx --from wykonuje polecenie z pakietu google-adk. Narzędzie uvx utworzy tymczasowe środowisko wirtualne, zainstaluje w nim pakiet google-adk, uruchomi określone polecenie, a następnie usunie środowisko.
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
Następnie zapisz adres URL jako zmienną środowiskową, której użyjesz w drugiej części tego samouczka.
AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')
Teraz wypróbuj agenta
Otwórz adres URL usługi w przeglądarce i zadaj pytanie tell me about the weather in new york. Powinna pojawić się odpowiedź podobna do tej: „W Nowym Jorku jest słonecznie, a temperatura wynosi 25 stopni Celsjusza (77 stopni Fahrenheita)”.
Na koniec zabezpiecz agenta.
Teraz zabezpieczmy dostęp do agenta. W następnej sekcji wdrożysz usługę Cloud Run, która wykonuje uwierzytelnione wywołanie tej usługi backendu.
gcloud run services remove-iam-policy-binding adk-agent-cr \
--member="allUsers" \
--role="roles/run.invoker" \
--region=$REGION
6. Wdrażanie interfejsu Gradio
W tym kroku utworzysz frontend gradio dla agenta pakietu ADK.
Uwaga: aplikacja Gradio może znajdować się w tej samej usłudze co agent ADK. W tym laboratorium znajdziesz 2 osobne usługi, które pokazują, jak wykonywać uwierzytelnione wywołania między usługami w Cloud Run.
Najpierw utwórz aplikację obok folderu multi_tool_agent.
mkdir gradio-frontend && cd gradio-frontend
Następnie utwórz plik requirements.txt zawierający następujące informacje:
gradio
requests
google-auth
Teraz utwórz plik 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. Wdrażanie i testowanie aplikacji Gradio
W tym kroku wdrożysz aplikację Gradio na frontendzie w Cloud Run.
Sprawdź, czy znajdujesz się w katalogu aplikacji gradio.
pwd
Powinien pojawić się komunikat codelab-gradio-adk/gradio-frontend
Teraz wdróż aplikację Gradio.
Uwaga: chociaż ta usługa interfejsu Gradio jest publicznie dostępną witryną, usługa backendu wymaga uwierzytelnienia. Aby zilustrować, dlaczego warto to zrobić, możesz dodać do tej usługi frontendu uwierzytelnianie użytkowników (np. Firebase Auth), a następnie zezwolić na wywoływanie usługi backendu tylko zalogowanym użytkownikom.
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
Po wdrożeniu zadaj pytanie what's the weather in new york?, a powinna pojawić się odpowiedź podobna do The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)..
8. Gratulacje!
Gratulujemy ukończenia ćwiczenia!
Zalecamy zapoznanie się z dokumentacją dotyczącą hostowania aplikacji i agentów AI.
Omówione zagadnienia
- Jak wdrożyć agenta ADK w Cloud Run
- Jak wdrożyć aplikację Gradio w Cloud Run
- Jak wykonywać uwierzytelnione wywołania między usługami w Cloud Run
9. Czyszczenie danych
Aby uniknąć przypadkowych opłat, np. jeśli usługi Cloud Run zostaną przypadkowo wywołane więcej razy niż miesięczny limit wywołań Cloud Run w bezpłatnej wersji, możesz usunąć usługę Cloud Run utworzoną w kroku 6.
Aby usunąć usługi Cloud Run, otwórz konsolę Cloud Run w Cloud Console pod adresem https://console.cloud.google.com/run i usuń usługi my-adk-gradio-frontend i adk-agent-cr.
Aby usunąć cały projekt, otwórz stronę Zarządzaj zasobami, wybierz projekt utworzony w kroku 2 i kliknij Usuń. Jeśli usuniesz projekt, musisz zmienić projekty w Cloud SDK. Listę wszystkich dostępnych projektów możesz wyświetlić, uruchamiając polecenie gcloud projects list.