在 Cloud Run 上部署、管理及觀察 ADK 代理程式

1. 簡介

重要注意事項：

本教學課程需要具備有效帳單帳戶的 Google Cloud 專案。如果沒有，請按照下列步驟取得可用於本教學課程的試用帳單帳戶：

1. 開啟無痕視窗
2. 如要參加研討會，通常會在研討會中提供兌換入口網站網址，否則您可以前往這個試用帳單帳戶兌換入口網站
3. 使用個人 Gmail 帳戶登入( Google Workspace / 其他電子郵件無法登入！)
4. 按照兌換說明逐步操作，為本教學課程建立新的 Google Cloud 專案

本教學課程將引導您在 Google Cloud Run 上，部署、管理及監控使用 Agent Development Kit (ADK) 建構的強大代理。ADK 可協助您建立代理，處理複雜的多代理工作流程。只要運用全代管的無伺服器平台 Cloud Run，就能將代理程式部署為可擴充的容器化應用程式，不必擔心基礎架構問題。這個強大的組合可讓您專注於代理程式的核心邏輯，同時享有 Google Cloud 強大且可擴充的環境。

在本教學課程中，我們將探索 ADK 與 Cloud Run 的無縫整合。您將瞭解如何部署代理程式，然後深入探討在類似於正式環境的設定中管理應用程式的實務層面。我們會說明如何管理流量，安全地推出新版代理程式，讓您在全面發布前，先對部分使用者測試新功能。

此外，您還會實際操作，監控代理程式的成效。我們會進行負載測試，模擬實際情境，觀察 Cloud Run 的自動調整資源配置功能運作情形。為深入瞭解代理程式的行為和成效，我們將透過 Cloud Trace 啟用追蹤功能。這項功能會提供要求在代理程式中傳輸的端對端詳細檢視畫面，方便您找出並解決任何效能瓶頸。完成本教學課程後，您將全面瞭解如何在 Cloud Run 上有效部署、管理及監控 ADK 輔助代理程式。

在本程式碼研究室中，您將逐步完成下列步驟：

1. 在 CloudSQL 上建立 PostgreSQL 資料庫，用於 ADK Agent 資料庫工作階段服務
2. 設定基本 ADK 代理程式
3. 設定 ADK 執行器使用的資料庫工作階段服務
4. 將代理程式初步部署至 Cloud Run
5. 進行負載測試並檢查 Cloud Run 自動調度資源
6. 部署新的代理程式修訂版本，並逐步增加新修訂版本的流量
7. 設定雲端追蹤功能，並檢查代理程式執行追蹤記錄

架構總覽

必要條件

• 熟悉 Python
• 瞭解使用 HTTP 服務的基本全端架構

課程內容

• ADK 結構和本機公用程式
• 使用資料庫工作階段服務設定 ADK 代理程式
• 在 CloudSQL 中設定 PostgreSQL，供資料庫工作階段服務使用
• 使用 Dockerfile 將應用程式部署至 Cloud Run，並設定初始環境變數
• 透過負載測試設定及測試 Cloud Run 自動調度資源功能
• 使用 Cloud Run 逐步發布的策略
• 設定 ADK 代理程式追蹤記錄，將資料傳送至 Cloud Trace

軟硬體需求

• Chrome 網路瀏覽器
• Gmail 帳戶
• 已啟用計費功能的 Cloud 專案

本程式碼研究室適用於所有程度的開發人員 (包括初學者)，並在範例應用程式中使用 Python。不過，您不需要具備 Python 知識，也能瞭解本文介紹的概念。

2. 🚀 準備工作坊開發設定

目標：確認專案和計費帳戶已準備就緒、熟悉 Cloud Shell 終端機和編輯器，並設定工作目錄和基本代理程式

步驟 1：在 Cloud 控制台中選取有效專案

在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案 (請參閱控制台左上方的部分)

點選該按鈕後，您會看到所有專案的清單，如下例所示：

紅框標示的值是專案 ID，本教學課程會使用這個值。

確認 Cloud 專案已啟用計費功能。如要確認，請按一下左上列的漢堡圖示 ☰，顯示「導覽選單」，然後找出「帳單」選單

如果「帳單 / 總覽」標題下方 ( 雲端控制台左上角部分) 顯示「Google Cloud Platform 試用帳單帳戶」，表示專案已準備就緒，可供本教學課程使用。如果沒有，請返回本教學課程的開頭，兌換試用帳單帳戶

步驟 2：準備 Cloud SQL 資料庫

稍後 ADK 代理程式會用到資料庫，我們將在 Cloud SQL 中建立 PostgreSQL 資料庫。首先，請前往 Cloud 控制台頂端區段的搜尋列，然後輸入「cloud sql」。然後按一下「Cloud SQL」產品

接著，我們需要建立新的資料庫執行個體，按一下「建立執行個體」，然後選擇「PostgreSQL」。

如果您從新專案開始，可能也需要啟用 Compute Engine API，只要在出現提示時點按「啟用 API」即可

接著選擇資料庫規格，選取「Enterprise」版本，並使用「Sandbox」版本預設設定

接著，請在此設定執行個體名稱和使用者 postgres 的預設密碼。您可以隨意設定憑證，但為了本教學課程，我們將使用「adk-deployment」做為執行個體名稱，並使用「ADK-deployment123」做為密碼。

重要事項！使用者名稱和密碼屬於機密資料，請務必對他人保密！

在本教學課程中，我們將使用 us-central1 和單一區域，然後點選「建立執行個體」按鈕，完成資料庫建立程序並讓系統完成所有必要設定。

請耐心等候，資料庫建立作業約需 5 到 10 分鐘才能完成

等待這項作業完成的期間，我們可以繼續下一個部分

步驟 3：熟悉 Cloud Shell

您將在大部分的教學課程中使用 Cloud Shell，請點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」。如果系統提示您授權，請按一下「Authorize」(授權)。

連線至 Cloud Shell 後，我們需要檢查 Shell ( 或終端機) 是否已通過帳戶驗證

gcloud auth list

如果看到如下列範例輸出內容的個人 Gmail，表示一切正常

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

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

如果沒有，請嘗試重新整理瀏覽器，並確保在系統提示時點選「授權」 ( 連線問題可能會導致授權中斷)。

接著，我們也需要檢查 Shell 是否已設定為正確的 PROJECT ID。如果終端機的 $圖示前有 ( ) 內的值 ( 在下方螢幕截圖中，該值為「adk-cloudrun-deployment-476504」)，則表示已為目前的 Shell 工作階段設定專案。

如果顯示的值正確無誤，可以略過下一個指令。但如果該值不正確或遺失，請執行下列指令

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 編輯器執行這項操作

按一下「Open Editor」(開啟編輯器) 按鈕，開啟 Cloud Shell 編輯器

完成後，前往 Cloud Shell 編輯器頂端，依序點選「File」->「Open Folder」，找到「username」目錄，然後找到「deploy_and_manage_adk」目錄，並點選「OK」按鈕。這會將所選目錄設為主要工作目錄。在本範例中，使用者名稱為 alvinprayuda，因此目錄路徑如下所示

現在，Cloud Shell 編輯器的工作目錄應如下所示 ( 位於 deploy_and_manage_adk 內)：

現在開啟編輯器的終端機。方法是在選單列中依序點選「Terminal」->「New Terminal」，或是使用 Ctrl + Shift + C 鍵盤快速鍵，瀏覽器底部就會開啟終端機視窗。

目前啟用的終端機應位於 deploy_and_manage_adk 工作目錄中。在本程式碼研究室中，我們將使用 Python 3.12，並使用 uv Python 專案管理工具，簡化建立及管理 Python 版本和虛擬環境的需求。Cloud Shell 已預先安裝 uv 套件。

注意：使用 uv 做為 Python 專案管理員時，建立及啟用虛擬環境的程序會簡化。不過，每個 python 指令碼指令都會替換為 uv run 指令。例如：uv run main.py，而不是 python main.py

執行這個指令，將必要的依附元件安裝至 .venv 目錄的虛擬環境

uv sync --frozen

注意：Python 依附元件會在 pyproject.toml 中宣告，並在 uv.lock 檔案中鎖定版本

現在，我們需要透過下列指令啟用必要的 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 值更新為您的專案 ID

注意：如果編輯器未顯示 .env 檔案，表示該檔案屬於隱藏檔案。依序點選「View」->「Toggle Hidden Files」即可顯示

# .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_PROJECT 的值更新為您的專案 ID

在本程式碼研究室中，我們將使用 GOOGLE_CLOUD_LOCATION 和 GOOGLE_GENAI_USE_VERTEXAI. 的預先設定值。目前，我們會將 DB_CONNECTION_NAME 註解掉。

現在我們可以前往下一個步驟，檢查代理程式邏輯並部署

3. 🚀 使用 ADK 和 Gemini 2.5 建構天氣代理程式

ADK 目錄結構簡介

首先，我們來瞭解 ADK 的功能，以及如何建構代理程式。如要查看 ADK 完整說明文件，請前往這個網址。ADK 在執行 CLI 指令時提供許多公用程式。部分範例如下：

• 設定代理程式目錄結構
• 透過 CLI 輸入/輸出快速試用互動功能
• 快速設定本機開發 UI 網頁介面

現在，讓我們檢查 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 CLI 必須能辨識目錄結構、init.py 內的代理程式匯入項目，以及 agent.py 中的 root_agent 宣告，因此請務必採用這些結構。

ADK 程式碼解說

這個指令碼包含代理程式啟動程序，我們會初始化下列項目：

• 設定要用於 gemini-2.5-flash 的模型
• 提供工具 get_weather，支援天氣代理程式等代理程式功能

執行網頁版 UI

現在，我們可以與代理程式互動，並在本機檢查其行為。ADK 可讓我們透過開發網頁 UI 互動，並檢查互動期間發生的情況。執行下列指令，啟動本機開發 UI 伺服器

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 編輯器頂端的「Web Preview」(網頁預覽) 按鈕，然後選取「Preview on port 8080」(透過以下通訊埠預覽：8080)。

你會看到下列網頁，在左上方的下拉式按鈕中選取可用的代理程式 ( 在本例中應為 weather_agent)，然後與機器人互動。在左側視窗中，您會看到代理程式執行階段的記錄詳細資料

現在試著與其互動。在左側列中，我們可以檢查每個輸入內容的追蹤記錄，瞭解代理程式在形成最終答案前，執行每個動作所需的時間。

這是 ADK 內建的可觀測性功能之一，目前我們是在本機檢查。稍後我們將瞭解如何將這項功能整合至 Cloud Trace，集中追蹤所有要求

提醒事項！現在先終止 adk web 程序，按下 CTRL + C 即可終止程序

4. 🚀 部署至 Cloud Run

現在，請將這個代理程式服務部署至 Cloud Run。在本示範中，這項服務會公開，供他人存取。不過請注意，這並非最佳做法，因為不安全

在本程式碼研究室中，我們將使用 Dockerfile 將代理程式部署至 Cloud Run。此時，我們已備妥將應用程式部署至 Cloud Run 所需的所有檔案 ( Dockerfile 和 server.py)。我們稍後會詳細說明這點。

現在，請先部署服務，然後前往 Cloud Shell 終端機，並確認目前的專案已設為有效專案。如果不是，請使用 gcloud 設定指令設定專案 ID：

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 存放區建立 Artifact Registry，請回答 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)。在本教學課程中，我們將使用 PostgreSQL Unix 通訊端連線和 pg8000 驅動程式。

請注意，在範例中，我們使用預設使用者 postgres 和預設資料庫 postgres (密碼為 ADK-deployment123)。

重要事項！由於這是示範應用程式，因此我們允許未經驗證的存取要求 (旗標 –allow_unauthenticated)。建議您為企業和正式版應用程式使用適當的驗證方式。

部署完成後，您會取得類似下方的連結：

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

取得這個網址後，您就可以在無痕視窗或行動裝置上使用應用程式，並存取代理程式開發人員使用者介面。等待部署期間，我們將在下一節檢查剛部署的詳細服務

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"]

我們可以在這裡設定必要服務來支援代理程式，例如準備用於生產環境的 Session、Memory 或 Artifact 服務。以下是將使用的 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 指令碼中定義的項目：

1. 使用 get_fast_api_app 方法將代理程式轉換為 FastAPI 應用程式。這樣一來，我們就會沿用用於網頁開發 UI 的相同路徑定義。
2. 將關鍵字引數新增至 get_fast_api_app 方法，設定必要的 Session、Memory 或 Artifact 服務。在本教學課程中，如果我們設定 SESSION_SERVICE_URI 環境變數，工作階段服務就會使用該變數，否則會使用記憶體內工作階段
3. 我們可以新增自訂路徑，支援其他後端業務邏輯。在指令碼中，我們新增了意見回饋功能路徑範例
4. 在 get_fast_api_app arg 參數中啟用雲端追蹤，將追蹤記錄傳送至 Google Cloud Trace
5. 使用 uvicorn 執行 FastAPI 服務

如果部署作業已完成，請存取 Cloud Run 網址，嘗試透過網頁開發人員介面與服務專員互動

6. 🚀 使用負載測試檢查 Cloud Run 自動調度資源功能

現在，我們要檢查 Cloud Run 的自動調度資源功能。在這個情境中，我們將部署新修訂版本，同時為每個執行個體啟用並行數上限。在前一節中，我們將並行數上限設為 10 ( --concurrency 10 旗標)。因此，當我們進行負載測試時，如果超過這個數字，Cloud Run 就會嘗試擴充執行個體。

請檢查 load_test.py 檔案。我們將使用這個指令碼，透過 locust 架構執行負載測試。這個指令碼會執行下列動作：

1. 隨機產生的 user_id 和 session_id
2. 為 user_id 建立 session_id
3. 使用建立的 user_id 和 session_id 存取「/run_sse」端點

如果您錯過部署的服務網址，我們需要知道該網址。前往 Cloud Run 控制台，然後點選「weather-agent」服務。

然後找出 weather-agent 服務並點選

服務網址會顯示在「區域」資訊旁邊。例如：

然後執行下列指令來進行負載測試

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

重要注意事項：請在此更新 YOUR_SERVICE_URL 的值。

注意：這會在 120 秒期間內，模擬 0 到 60 個並行使用者要求，並以每秒 5 位使用者的速率增加

執行這項操作後，您會看到類似下方的指標。( In this example all reqs success )

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 執行個體會嘗試自動調整容器數量，以滿足這項條件。

注意：您不僅可以控制並行數上限，也可以控制容器執行個體的最小值和最大值。詳情請參閱這份 SDK 說明文件

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],
)

接著，您想發布新修訂版本，但不希望所有要求流量都直接導向新版本。我們可以透過 Cloud Run 逐步發布。首先，我們需要部署新修訂版本，但要使用 –no-traffic 標記。儲存先前的代理程式指令碼，然後執行下列指令

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

重要附註：請在此更新 YOUR_PROJECT_ID 的值

完成後，您會收到與先前部署程序類似的記錄，但服務的流量數不同。系統會顯示 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 產品

然後找出 weather-agent 服務並點選

前往「修訂版本」分頁，即可查看已部署的修訂版本清單

您會看到新部署的修訂版本提供 0% 的服務，您可以點選 Kebab 按鈕 (⋮)，然後選擇「管理流量」

在彈出的新視窗中，您可以編輯要將多少流量導向哪個修訂版本。

等待一段時間後，系統會根據百分比設定，按比例分配流量。這樣一來，如果新版本發生問題，我們就能輕鬆還原至先前的修訂版本

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 追蹤功能

嘗試存取服務網頁開發人員 UI，並與服務專員對話。接著前往 Cloud 控制台搜尋列，輸入「trace explorer」，然後選擇「Trace Explorer」產品

在追蹤記錄探索器頁面中，您會看到與代理程式的對話記錄已提交。您可以從「範圍名稱」部分查看，並篩除與代理程式相關的範圍 ( 名稱為 agent_run [weather_agent] )

如果已篩選跨度，您也可以直接檢查每項追蹤記錄。系統會顯示代理人執行各項動作的詳細時間長度。舉例來說，請參考下圖

在每個部分中，您都可以檢查屬性中的詳細資料，如下所示

這樣一來，我們就能清楚掌握代理程式與使用者每次互動的資訊，有助於排解問題。歡迎嘗試各種工具或工作流程！

9. 🎯 挑戰

嘗試多代理或代理工作流程，瞭解這些工作流程在負載下的效能，以及追蹤記錄的樣貌

10. 🧹 清除

如要避免系統向您的 Google Cloud 帳戶收取本程式碼研究室所用資源的費用，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「管理資源」頁面。
2. 在專案清單中選取要刪除的專案，然後點按「刪除」。
3. 在對話方塊中輸入專案 ID，然後按一下「Shut down」(關閉) 即可刪除專案。
4. 或者，您也可以前往控制台的「Cloud Run」，選取剛部署的服務並刪除。