1. Введение
Обзор
В этой лабораторной работе вы развернёте агент ADK в Cloud Run в качестве бэкенд-сервиса, а затем развернёте фронтенд Gradio для агента ADK в качестве второго сервиса Cloud Run. В этой лабораторной работе показано, как требовать аутентификацию для сервиса агента ADK и выполнять аутентифицированные вызовы из фронтенд-сервиса Gradio.
Чему вы научитесь
- Как развернуть агент ADK в Cloud Run
- Как развернуть приложение Gradio в Cloud Run
- Как совершать аутентифицированные вызовы между службами в Cloud Run
2. Включите API
Сначала настройте свой проект Google Cloud.
gcloud config set project <YOUR_PROJECT_ID>
Вы можете подтвердить свой проект Google Cloud, выполнив следующую команду:
gcloud config get-value project
Для этой лабораторной работы требуется включение следующих API:
gcloud services enable run.googleapis.com \
compute.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
aiplatform.googleapis.com
3. Настройка и требования
В этом разделе вы создадите несколько учётных записей служб и назначите им соответствующие роли IAM. Каждая облачная служба будет иметь собственную учётную запись службы.
Сначала задайте переменные среды для этой лабораторной работы, которые будут использоваться в ней.
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"
Затем создайте учетную запись службы для агента ADK.
gcloud iam service-accounts create $SERVICE_ACCOUNT_ADK \
--display-name="Service account for adk agent on cloud run"
И предоставьте учетной записи службы ADK роль «Пользователь Vertex AI».
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_ADK" \
--role="roles/aiplatform.user"
Теперь создайте учетную запись службы для интерфейса Gradio.
gcloud iam service-accounts create $SERVICE_ACCOUNT_GRADIO \
--display-name="Service account for gradio frontend cloud run"
И предоставьте интерфейсу Gradio роль вызывающего объекта Cloud Run, что позволит ему вызывать агента ADK, размещенного в Cloud Run.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_ADDRESS_GRADIO" \
--role="roles/run.invoker"
4. Создайте приложение ADK
На следующем этапе вы создадите код для приложения быстрого старта ADK.
Примечание: по окончании лабораторной работы структура вашего файла должна выглядеть следующим образом:
- codelab-gradio-adk <-- you'll deploy the ADK agent from here
- gradio-frontend <-- you'll deploy the gradio app from here
- app.py
- requirements.txt
- multi_tool_agent
- __init__.py
- agent.py
- requirements.txt
Сначала создайте каталог для всей кодовой лаборатории.
mkdir codelab-gradio-adk
cd codelab-gradio-adk
Теперь создайте каталог для службы агента ADK.
mkdir multi_tool_agent && cd multi_tool_agent
Создайте файл __init__.py со следующим содержимым:
from . import agent
Создайте файл requirements.txt :
google-adk
Создайте файл с именем 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
В этом разделе вы развернёте агент ADK в Cloud Run. Затем вы проверите работоспособность развёртывания с помощью веб-интерфейса разработчика, предоставляемого ADK. Кроме того, вам потребуются аутентифицированные вызовы к этой службе.
Перейдите в родительскую папку.
ПРИМЕЧАНИЕ. Код агента ADK должен включать папку multi_tool_agent в качестве корневой папки.
cd ..
Сначала создайте службу Cloud Run:
ПРИМЕЧАНИЕ: --with_ui не является обязательным для тестирования с помощью Dev UI, как показано в следующем шаге:
ПРИМЕЧАНИЕ: команда -- позволяет передавать флаги командной строки в базовую команду gcloud run deploy .
ПРИМЕЧАНИЕ: uvx --from выполняет команду из пакета google-adk. uvx создаст временную виртуальную среду, установит в нее google-adk, выполнит указанную команду, а затем удалит среду.
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
Затем сохраните URL-адрес как переменную окружения, которую вы будете использовать во второй части этой лабораторной работы.
AGENT_SERVICE_URL=$(gcloud run services describe adk-agent-cr --region $REGION --format 'value(status.url)')
Теперь попробуйте агента
Откройте URL-адрес сервиса в браузере и спросите: « tell me about the weather in new york . Вы должны увидеть ответ, похожий на «Погода в Нью-Йорке солнечная, температура 25 градусов по Цельсию (77 градусов по Фаренгейту)».
Наконец, закрепите агента
Теперь давайте обеспечим безопасный доступ к агенту. В следующем разделе мы развернем службу Cloud Run, которая будет выполнять аутентифицированный вызов к этой серверной службе.
gcloud run services remove-iam-policy-binding adk-agent-cr \
--member="allUsers" \
--role="roles/run.invoker" \
--region=$REGION
6. Разверните интерфейс Gradio
На этом этапе вы создадите интерфейс Gradio для вашего агента ADK.
Примечание: приложение Gradio можно разместить в той же службе, что и агент ADK. Эта лабораторная работа представляет собой два отдельных сервиса, демонстрирующих, как выполнять аутентифицированные вызовы между сервисами в Cloud Run.
Сначала создайте приложение рядом с папкой multi_tool_agent.
mkdir gradio-frontend && cd gradio-frontend
Затем создайте файл requirements.txt , содержащий следующее:
gradio
requests
google-auth
Теперь создайте файл 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. Разверните и протестируйте свое приложение Gradio.
На этом этапе вы развернете интерфейсное приложение Gradio в Cloud Run.
Убедитесь, что вы находитесь в каталоге приложения Gradio.
pwd
Вы должны увидеть codelab-gradio-adk/gradio-frontend
Теперь разверните свое приложение Gradio.
Примечание: хотя этот фронтенд-сервис Gradio представляет собой общедоступный веб-сайт, бэкенд-сервис требует аутентификации. Чтобы проиллюстрировать, зачем это нужно, можно добавить аутентификацию пользователей (например, Firebase Auth) к этому фронтенд-сервису и разрешить совершать вызовы к бэкенд-сервису только вошедшим в систему пользователям.
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
После развертывания спросите what's the weather in new york? , и вы должны получить ответ, похожий на The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).
8. Поздравляем!
Поздравляем с завершением лабораторной работы!
Мы рекомендуем ознакомиться с документацией по хостингу приложений ИИ и документацией агентов .
Что мы рассмотрели
- Как развернуть агент ADK в Cloud Run
- Как развернуть приложение Gradio в Cloud Run
- Как совершать аутентифицированные вызовы между службами в Cloud Run
9. Уборка
Чтобы избежать непреднамеренных списаний, например, если службы Cloud Run будут непреднамеренно вызваны большее количество раз, чем ваш ежемесячный лимит вызовов Cloud Run на бесплатном уровне , вы можете удалить службу Cloud Run, созданную на шаге 6.
Чтобы удалить службы Cloud Run, перейдите в облачную консоль Cloud Run по адресу https://console.cloud.google.com/run и удалите службы my-adk-gradio-frontend и adk-agent-cr .
Чтобы удалить весь проект, перейдите в раздел «Управление ресурсами» , выберите проект, созданный на шаге 2, и нажмите «Удалить». После удаления проекта вам потребуется изменить проекты в Cloud SDK. Список всех доступных проектов можно просмотреть, выполнив gcloud projects list .