Эта страница переведена с помощью Cloud Translation API.

Развертывание, управление и наблюдение за агентом ADK в облаке Run

1. Введение

ВАЖНЫЕ ЗАМЕЧАНИЯ:

Для этого руководства требуется проект Google Cloud с активным платёжным аккаунтом . Если у вас его ещё нет, выполните следующие действия, чтобы получить пробный платёжный аккаунт , который можно использовать для этого руководства:

Открыть окно в режиме инкогнито
Если вы присоединяетесь к сеансу семинара, URL-адрес портала погашения обычно будет предоставлен в сеансе, в противном случае вы можете перейти на этот портал погашения пробного платежного аккаунта.
Войдите в систему, используя свою личную учетную запись Gmail (Google Workspace и другие адреса электронной почты не подойдут!)
Следуйте пошаговым инструкциям по активации , чтобы успешно создать новый проект Google Cloud для этого руководства.

Это руководство поможет вам развернуть, управлять и отслеживать работу мощного агента, созданного с помощью Agent Development Kit (ADK) в Google Cloud Run. ADK позволяет создавать агенты, способные выполнять сложные многоагентные рабочие процессы. Используя Cloud Run, полностью управляемую бессерверную платформу, вы можете развернуть свой агент как масштабируемое контейнерное приложение, не беспокоясь о базовой инфраструктуре. Это мощное сочетание позволяет вам сосредоточиться на базовой логике агента, используя при этом преимущества надежной и масштабируемой среды Google Cloud.

В этом руководстве мы рассмотрим бесшовную интеграцию ADK с Cloud Run. Вы научитесь разворачивать агент, а затем погрузитесь в практические аспекты управления приложением в условиях, приближенных к производственным. Мы расскажем, как безопасно развертывать новые версии агента, управляя трафиком, что позволит вам тестировать новые функции на ограниченной группе пользователей перед полным релизом.

Кроме того, вы получите практический опыт мониторинга производительности вашего агента. Мы смоделируем реальную ситуацию, проведя нагрузочный тест, чтобы оценить возможности автоматического масштабирования Cloud Run в действии. Для более глубокого понимания поведения и производительности вашего агента мы включим трассировку с помощью Cloud Trace. Это обеспечит детальное сквозное представление о запросах, проходящих через агента, что позволит вам выявить и устранить любые узкие места производительности. К концу этого руководства вы получите полное представление о том, как эффективно развертывать, управлять и контролировать ваши агенты на базе ADK в Cloud Run.

В ходе выполнения лабораторной работы вы будете применять следующий пошаговый подход:

Создайте базу данных PostgreSQL в CloudSQL, которая будет использоваться для сеанса службы базы данных агента ADK.
Настройте базовый агент ADK
Настройка службы сеанса базы данных для использования диспетчером ADK
Первоначальное развертывание агента в облаке.
Нагрузочное тестирование и проверка автоматического масштабирования в облаке
Разверните новую версию агента и постепенно увеличивайте трафик на новые версии.
Настройте облачную трассировку и проверьте трассировку запуска агента

Обзор архитектуры

Предпосылки

Удобная работа с Python
Понимание базовой архитектуры полного стека с использованием HTTP-сервиса

Чему вы научитесь

Структура АДК и местные коммуникации
Настройка агента ADK с помощью службы сеанса базы данных
Настройка PostgreSQL в CloudSQL для использования службой сеанса базы данных
Разверните приложение в Cloud Run с помощью Dockerfile и настройте начальные переменные среды.
Настройка и тестирование автоматического масштабирования Cloud Run с помощью нагрузочного тестирования
Стратегия постепенного выпуска с Cloud Run
Настройте трассировку агента ADK в Cloud Trace

Что вам понадобится

веб-браузер Chrome
Аккаунт Gmail
Облачный проект с включенным биллингом

Эта лабораторная работа, предназначенная для разработчиков любого уровня (включая новичков), использует Python в качестве примера приложения. Однако для понимания представленных концепций знание Python не требуется.

2. 🚀 Подготовка к разработке семинара

Шаг 1: Выберите активный проект в облачной консоли.

В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud (см. верхнюю левую часть консоли).

Нажмите на него, и вы увидите список всех ваших проектов, как в этом примере,

Значение, указанное в красной рамке, является ИДЕНТИФИКАТОРОМ ПРОЕКТА , и это значение будет использоваться на протяжении всего урока.

Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Для этого нажмите на значок бургера ☰ в левом верхнем углу панели, где отображается меню навигации, и найдите меню «Выставление счетов».

Если вы видите «Пробный платёжный аккаунт Google Cloud Platform» в разделе «Биллинг/Обзор» ( в левом верхнем углу облачной консоли ), ваш проект готов к использованию в рамках этого руководства. Если нет, вернитесь к началу руководства и активируйте пробный платёжный аккаунт.

Шаг 2: Подготовка базы данных Cloud SQL

Нам понадобится база данных, которую позже будет использовать агент ADK. Давайте создадим базу данных PostgreSQL в Cloud SQL. Для начала перейдите в строку поиска в верхней части облачной консоли и введите «cloud sql». Затем выберите продукт Cloud SQL .

После этого нам нужно будет создать новый экземпляр базы данных, нажимаем « Создать экземпляр» и выбираем PostgreSQL.

Вам также может потребоваться включить API Compute Engine, если вы начинаете новый проект. Просто нажмите « Включить API», если появится такое сообщение.

Далее выберем характеристики базы данных, выбираем редакцию Enterprise с предустановкой Sandbox Edition.

После этого задайте имя экземпляра и пароль по умолчанию для пользователя postgres . Вы можете указать любые учётные данные, но в рамках этого руководства мы используем имя экземпляра " adk-deployment " и пароль "ADK-deployment123".

Давайте используем us-central1 с одной зоной для этого руководства, затем мы можем завершить создание нашей базы данных и позволить ей завершить всю необходимую настройку, нажав кнопку «Создать экземпляр» .

Пока мы ждем окончания этого, мы можем перейти к следующему разделу.

Шаг 3: Знакомство с Cloud Shell

В большинстве обучающих программ вы будете использовать Cloud Shell . Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud. Если появится запрос на авторизацию, нажмите «Авторизовать».

После подключения к Cloud Shell нам нужно будет проверить, аутентифицирована ли оболочка (или терминал) с помощью нашей учетной записи.

gcloud auth list

Если вы видите свой личный Gmail, как в примере ниже, все в порядке.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Если нет, попробуйте обновить браузер и обязательно нажмите кнопку «Авторизовать» при появлении соответствующего запроса (возможно, процесс был прерван из-за проблем с подключением).

Далее нам также необходимо проверить, настроена ли оболочка на правильный идентификатор ПРОЕКТА , который у вас есть. Если вы видите значение внутри ( ) перед значком $ в терминале (на снимке экрана ниже значение равно «adk-cloudrun-deployment-476504» ), это значение показывает настроенный проект для вашего активного сеанса оболочки.

Если отображаемое значение верно , вы можете пропустить следующую команду . Однако, если оно неверно или отсутствует, выполните следующую команду.

gcloud config set project <YOUR_PROJECT_ID>

Затем клонируйте рабочий каталог шаблона для этой лабораторной работы с Github, выполнив следующую команду. Она создаст рабочий каталог в каталоге deploy_and_manage_adk .

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

Шаг 4: Знакомство с редактором Cloud Shell и настройка рабочего каталога приложения

Теперь мы можем настроить наш редактор кода для написания кода. Для этого мы будем использовать Cloud Shell Editor.

Нажмите кнопку «Открыть редактор» , чтобы открыть редактор Cloud Shell.

После этого перейдите в верхнюю часть редактора Cloud Shell и выберите Файл -> Открыть папку, найдите каталог с именем пользователя , а затем каталог deploy_and_manage_adk и нажмите кнопку «ОК». Выбранный каталог станет основным рабочим каталогом. В этом примере имя пользователя — alvinprayuda , поэтому путь к каталогу показан ниже.

Теперь рабочий каталог вашего Cloud Shell Editor должен выглядеть следующим образом (внутри deploy_and_manage_adk )

Теперь откройте терминал редактора. Это можно сделать, нажав «Терминал» -> «Новый терминал» в строке меню или нажав Ctrl + Shift + C , чтобы открыть окно терминала в нижней части браузера.

Ваш текущий активный терминал должен находиться в рабочем каталоге deploy_and_manage_adk . В этой лабораторной работе мы будем использовать Python 3.12 и менеджер проектов Python UV для упрощения создания и управления версиями Python и виртуальными средами. Этот пакет UV уже предустановлен в Cloud Shell.

Выполните эту команду, чтобы установить необходимые зависимости для виртуальной среды в каталоге .venv.

uv sync --frozen

Теперь нам нужно включить необходимые API с помощью команды, показанной ниже. Это может занять некоторое время.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

При успешном выполнении команды вы должны увидеть сообщение, похожее на показанное ниже:

Operation "operations/..." finished successfully.

Далее нам необходимо настроить файлы конфигурации для этого проекта.

Переименуйте файл .env.example в .env.

cp .env.example .env

Откройте файл .env и обновите значение GOOGLE_CLOUD_PROJECT на идентификатор вашего проекта.

# .env

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# DB_CONNECTION_NAME=your-db-connection-name

В этой лабораторной работе мы используем предустановленные значения для GOOGLE_CLOUD_LOCATION и GOOGLE_GENAI_USE_VERTEXAI. Пока что оставим DB_CONNECTION_NAME закомментированным.

Теперь мы можем перейти к следующему шагу: проверить логику агента и развернуть ее.

3. 🚀 Создайте Weather Agent с помощью ADK и Gemini 2.5

Введение в структуру каталогов ADK

Давайте начнём с изучения возможностей ADK и способов создания агента. Полную документацию ADK можно найти по этой ссылке . ADK предлагает множество утилит для выполнения команд CLI. Вот некоторые из них:

Настройте структуру каталога агентов
Быстро попробуйте взаимодействие через ввод-вывод CLI
Быстрая настройка локального веб-интерфейса разработки

Теперь давайте проверим структуру агента в каталоге weather_agent .

weather_agent/
├── __init__.py
├── agent.py
└── tool.py

И если вы проверите init.py и agent.py, вы увидите этот код

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py


import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
""",
    tools=[get_weather],
)

Пояснение кода ADK

Этот сценарий содержит инициализацию нашего агента, где мы инициализируем следующие вещи:

Установите используемую модель на gemini-2.5-flash
Предоставить инструмент get_weather для поддержки функциональности агента в качестве погодного агента.

Запустить веб-интерфейс

Теперь мы можем взаимодействовать с агентом и отслеживать его поведение локально. ADK позволяет нам использовать веб-интерфейс разработки для взаимодействия и отслеживания происходящего во время взаимодействия. Выполните следующую команду, чтобы запустить локальный сервер интерфейса разработки.

uv run adk web --port 8080

Это приведет к выводу, подобному следующему примеру, что означает, что мы уже можем получить доступ к веб-интерфейсу.

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Теперь, чтобы проверить это, нажмите кнопку «Предварительный просмотр в Интернете» в верхней части редактора Cloud Shell и выберите «Предварительный просмотр на порту 8080».

Вы увидите следующую веб-страницу, где можно выбрать доступных агентов в раскрывающемся списке слева вверху (в нашем случае это должен быть weather_agent ) и взаимодействовать с ботом. В левом окне вы увидите множество информации о журнале работы агента.

Теперь попробуйте взаимодействовать с ним. На левой панели мы можем просмотреть трассировку для каждого входного сигнала, чтобы понять, сколько времени занимает каждое действие, выполняемое агентом, прежде чем сформировать окончательный ответ.

Это одна из функций наблюдения, встроенных в ADK. Сейчас мы проверяем её локально. Позже мы рассмотрим, как она интегрируется в Cloud Tracing, чтобы обеспечить централизованное отслеживание всех запросов.

4. 🚀 Развертывание в Cloud Run

Теперь развернём этот агентский сервис в Cloud Run. В целях демонстрации этот сервис будет представлен как публичный, к которому смогут получить доступ другие пользователи. Однако имейте в виду, что это не лучший вариант, поскольку он небезопасен.

В этой лабораторной работе мы будем использовать Dockerfile для развертывания нашего агента в Cloud Run. На данный момент у нас уже есть все необходимые файлы ( Dockerfile и server.py ) для развертывания наших приложений в Cloud Run. Мы подробно обсудим это позже.

Теперь давайте сначала развернем службу, перейдите в Cloud Shell Terminal и убедитесь, что текущий проект настроен на ваш активный проект. Если нет, используйте команду gcloud configure, чтобы задать идентификатор проекта:

gcloud config set project [PROJECT_ID]

Теперь нам нужно снова обратиться к файлу .env , открыть его, и вы увидите, что нам нужно раскомментировать переменную DB_CONNECTION_NAME и заполнить ее правильным значением.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name

Чтобы получить значение DB_CONNECTION_NAME , снова перейдите в Cloud SQL и выберите созданный вами экземпляр. Перейдите в строку поиска в верхней части консоли Cloud и введите «cloud sql». Затем выберите продукт Cloud SQL .

После этого вы увидите ранее созданный экземпляр, нажмите на него.

На странице экземпляра прокрутите вниз до раздела « Подключиться к этому экземпляру » и скопируйте имя подключения , чтобы заменить значение DB_CONNECTION_NAME .

После этого откройте файл .env и измените переменную DB_CONNECTION_NAME . Ваш файл env должен выглядеть, как показано ниже.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

После этого запустите скрипт развертывания.

bash deploy_to_cloudrun.sh

Если вам будет предложено подтвердить создание реестра артефактов для репозитория Docker, просто ответьте Y.

Пока мы ждем процесса развертывания, давайте взглянем на deploy_to_cloudrun.sh

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

Этот скрипт загрузит вашу переменную .env , а затем выполнит команду развертывания.

Если присмотреться, нам понадобится всего одна команда gcloud run deploy, чтобы выполнить все необходимые действия для развёртывания сервиса: сборку образа, отправку в реестр, развёртывание сервиса, настройку политики IAM, создание ревизий и даже маршрутизацию трафика. В этом примере мы уже предоставляем Dockerfile, поэтому эта команда будет использовать его для сборки приложения.

Примечание: В скрипте развёртывания мы задаём переменные окружения SESSION_SERVICE_URI . Если эта переменная настроена, наш агент ADK будет использовать URI сервиса для хранения информации о сеансе и состоянии (определённых в файле server.py ). В этом руководстве мы используем соединение через Unix-сокет PostgreSQL с драйвером pg8000 .

Обратите внимание, что в примере мы используем пользователя по умолчанию postgres и базу данных по умолчанию postgres (с паролем ADK-deployment123 ) .

После завершения развертывания вы должны получить ссылку, похожую на приведенную ниже:

https://weather-agent-*******.us-central1.run.app

Получив этот URL, вы сможете запустить приложение в режиме инкогнито или на мобильном устройстве и получить доступ к интерфейсу разработчика. Пока вы ожидаете развёртывания, давайте подробно рассмотрим сервис, который мы только что развёртываем в следующем разделе.

5. 💡 Dockerfile и скрипт внутреннего сервера

Чтобы сделать агент доступным как сервис, мы поместим его в приложение FastAPI, которое будет запускаться командой Dockerfile. Ниже представлено содержимое Dockerfile.

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

Здесь мы можем настроить необходимые службы для поддержки агента, например, подготовить службы сеанса , памяти или артефакта для использования в производственных целях. Вот код server.py , который будет использоваться.

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


# Example if you want to add your custom endpoint
@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

Пояснение кода сервера

Вот что определено в скрипте server.py :

Конвертируем наш агент в приложение FastAPI с помощью метода get_fast_api_app . Таким образом, мы унаследуем то же определение маршрута, которое используется для пользовательского интерфейса веб-разработки.
Настройте необходимые службы сеанса, памяти или артефакта, добавив ключевые аргументы в метод get_fast_api_app . В этом руководстве, если мы настроим переменную окружения SESSION_SERVICE_URI , служба сеанса будет использовать её, в противном случае она будет использовать сеанс в памяти.
Мы можем добавить пользовательский маршрут для поддержки другой бэкэнд-бизнес-логики, в скрипте мы добавляем пример маршрута функциональности обратной связи.
Включите трассировку облака в параметрах аргумента get_fast_api_app , чтобы отправить трассировку в Google Cloud Trace.
Запустите службу FastAPI с помощью uvicorn

Теперь, если развертывание уже завершено, попробуйте взаимодействовать с агентом через веб-интерфейс разработчика, перейдя по URL-адресу Cloud Run.

6. 🚀 Проверка автоматического масштабирования Cloud Run с помощью нагрузочного тестирования

Теперь мы рассмотрим возможности автоматического масштабирования Cloud Run. В этом сценарии развернём новую версию, включив максимальное количество параллельных вычислений на экземпляр. В предыдущем разделе мы установили максимальное количество параллельных вычислений равным 10 (флаг --concurrency 10 ). Следовательно, можно ожидать, что Cloud Run попытается масштабировать свой экземпляр при выполнении нагрузочного теста, превышающего это число.

Давайте проверим файл load_test.py . Это скрипт, который мы будем использовать для нагрузочного тестирования с использованием фреймворка Locust . Он выполняет следующие действия:

Рандомизированные user_id и session_id
Создайте session_id для user_id
Перейдите в конечную точку "/run_sse" с созданными user_id и session_id.

Нам понадобится URL-адрес нашего развернутого сервиса, если вы его пропустили. Перейдите в консоль Cloud Run и выберите ваш сервис Weather Agent.

Затем найдите службу прогноза погоды и нажмите на нее.

URL-адрес сервиса будет отображаться рядом с информацией о регионе. Например:

Затем выполните следующую команду для выполнения нагрузочного теста.

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

Запустив это, вы увидите такие метрики. (В этом примере все требования выполнены успешно)

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

Затем давайте посмотрим, что произошло в Cloud Run, снова перейдите к развёрнутому сервису и посмотрите на панель управления. Здесь вы увидите, как Cloud Run автоматически масштабирует экземпляр для обработки входящих запросов. Поскольку мы ограничиваем максимальное количество одновременных запросов 10 на экземпляр, Cloud Run попытается автоматически скорректировать количество контейнеров для удовлетворения этого условия.

7. 🚀 Постепенный выпуск новых версий

Теперь рассмотрим следующий сценарий. Мы хотим обновить подсказку агента. Откройте файл weather_agent/agent.py и перезапишите его следующим кодом:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

Затем вы хотите выпустить новые версии, но не хотите, чтобы весь трафик запросов напрямую направлялся в новую версию. Мы можем выполнить постепенный выпуск с помощью облачного запуска. Сначала нам нужно развернуть новую версию, но с флагом --no-traffic . Сохраните предыдущий скрипт агента и выполните следующую команду.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

После завершения вы получите аналогичный журнал, как и в предыдущем процессе развёртывания, но с разницей в количестве обслуженного трафика. Он покажет 0 процентов обслуженного трафика.

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

Далее перейдем на страницу продукта Cloud Run и найдем ваш развернутый экземпляр. Введите «cloud run» в строке поиска и выберите продукт Cloud Run.

Затем найдите службу прогноза погоды и нажмите на нее.

Перейдите на вкладку «Ревизии» , и вы увидите список развернутых ревизий.

Вы увидите, что новые развернутые версии обслуживают 0%, отсюда вы можете нажать кнопку с кебабом (⋮) и выбрать «Управление трафиком».

В открывшемся окне вы можете редактировать процент трафика, который будет направляться на те или иные ревизии.

Через некоторое время трафик будет распределен пропорционально в соответствии с процентными настройками. Таким образом, мы сможем легко вернуться к предыдущим версиям, если что-то случится с новым релизом.

8. 🚀 Отслеживание ADK

Агенты, созданные с помощью ADK, уже поддерживают трассировку, используя встроенную открытую телеметрию. Для сбора и визуализации этих данных используется Cloud Trace. Давайте рассмотрим файл server.py и рассмотрим, как мы включаем эту функцию в нашем ранее развёрнутом сервисе.

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

Здесь мы передаем аргументу trace_to_cloud значение True . Если вы используете другие параметры развёртывания, обратитесь к этой документации , чтобы узнать больше о том, как включить трассировку в Cloud Trace для различных параметров развёртывания.

Попробуйте открыть веб-интерфейс разработчика вашего сервиса и пообщаться с агентом. После этого перейдите в строку поиска Cloud Console, введите «trace explorer» и выберите продукт Trace Explorer .

На странице проводника трассировки вы увидите, что наша беседа с агентом отправлена. Вы можете посмотреть её в разделе «Имя диапазона» и отфильтровать диапазон, специфичный для нашего агента (он называется agent_run [weather_agent] ).

Когда интервалы уже отфильтрованы, вы также можете напрямую просматривать каждую трассировку. Она будет отображать подробную длительность каждого действия, выполненного агентом. Например, см. изображения ниже.

В каждом разделе вы можете просмотреть подробную информацию об атрибутах, как показано ниже.

Итак, теперь у нас есть хорошая наблюдаемость и информация о каждом взаимодействии нашего агента с пользователем, что позволяет отлаживать проблемы. Смело пробуйте различные инструменты и рабочие процессы!

9. 🎯 Вызов

Попробуйте многоагентные или агентные рабочие процессы, чтобы увидеть, как они работают под нагрузкой и как выглядит трассировка.

10. 🧹 Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этой лабораторной работе, выполните следующие действия:

В консоли Google Cloud перейдите на страницу Управление ресурсами .
В списке проектов выберите проект, который вы хотите удалить, а затем нажмите Удалить .
В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить», чтобы удалить проект.
Либо вы можете перейти в Cloud Run на консоли, выбрать службу, которую вы только что развернули, и удалить ее.