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

程式碼研究室簡介
schedule0 分鐘
subject上次更新時間:2025年6月19日
account_circle作者:Alvin Prayuda Juniarta Dwiyantoro

本教學課程將引導您在 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. 設定雲端追蹤功能,並檢查代理程式執行追蹤

架構總覽

5e38fc5607fb4543.jpeg

必要條件

  • 熟悉 Python 作業
  • 瞭解使用 HTTP 服務的基本全堆疊架構

課程內容

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

軟硬體需求

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

本程式碼研究室專為各級別 (包括初學者) 的開發人員設計,範例應用程式會使用 Python。不過,您不必具備 Python 知識,也能瞭解本文所述的概念。

2. 事前準備

在 Cloud 控制台中選取有效專案

本程式碼研究室假設您已擁有已啟用計費功能的 Google Cloud 專案。如果您還沒有這個帳戶,請按照下方說明操作。

  1. Google Cloud 控制台的專案選取器頁面中,選取或建立 Google Cloud 專案
  2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能

c714d4741fc97644.png

準備 Cloud SQL 資料庫

我們稍後會需要資料庫,供 ADK 代理程使用。我們現在來在 Cloud SQL 上建立 PostgreSQL 資料庫。首先,前往 Cloud 控制台頂端的搜尋列,然後輸入「cloud sql」。然後按一下「Cloud SQL」產品

1005cb65520eb3fc.png

接著,我們需要建立新的資料庫執行個體,按一下「Create Instance」(建立執行個體),然後選擇「PostgreSQL」

7f2ad19bc246895d.png

ead4a98e7a8d8a39.png

如果您要從新專案開始,可能也需要啟用 Compute Engine API。如果出現這則提示,請按一下「Enable API」

724cf67681535679.png

接下來,我們會選擇資料庫的規格,並選擇Enterprise 版,並預設Sandbox

24aa9defed93a3ef.png

接著,請在這裡設定 postgres 使用者的執行個體名稱和預設密碼。您可以使用任何憑證設定這項功能,但為了方便本教學課程,我們會在此處使用「adk-deployment」做為執行個體名稱和密碼

573719a4582f541c.png

我們將在本教學課程中使用 us-central1 區域,並在單一區域中進行設定。完成資料庫建立程序後,請按一下「Create Instance」按鈕,讓系統完成所有必要的設定

773e2ea11d97369d.png

在等待這項作業完成的同時,我們可以繼續進行下一個部分

在 Cloud Shell 終端機中設定 Cloud 專案

  1. 您將使用 Cloud Shell,這是在 Google Cloud 中執行的指令列環境。按一下 Google Cloud 控制台頂端的「啟用 Cloud Shell」。

1829c3759227c19b.png

  1. 連線至 Cloud Shell 後,請使用下列指令確認您已通過驗證,且專案已設為您的專案 ID:
gcloud auth list
  1. 在 Cloud Shell 中執行下列指令,確認 gcloud 指令知道您的專案。
gcloud config list project
  1. 如果未設定專案,請使用下列指令進行設定:
gcloud config set project <YOUR_PROJECT_ID>

或者,您也可以在控制台中查看 PROJECT_ID ID

4032c45803813f30.jpeg

按一下該按鈕,即可在右側看到所有專案和專案 ID

8dc17eb4271de6b5.jpeg

  1. 請透過下方指令啟用必要的 API。這可能需要幾分鐘的時間,請耐心等候。
gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

指令執行成功後,您應該會看到類似以下的訊息:

Operation "operations/..." finished successfully.

您可以透過主控台搜尋每項產品,或使用這個連結,來代替 gcloud 指令。

如果遺漏任何 API,您隨時可以在導入期間啟用。

如要瞭解 gcloud 指令和用法,請參閱說明文件

前往 Cloud Shell 編輯器並設定應用程式工作目錄

我們現在可以設定程式碼編輯器,執行一些程式設計作業。我們將使用 Cloud Shell 編輯器進行這項操作

  1. 按一下「開啟編輯器」按鈕,即可開啟 Cloud Shell 編輯器,並在其中編寫程式碼 b16d56e4979ec951.png
  2. 請確認 Cloud Code 專案已設在 Cloud Shell 編輯器的左下角 (狀態列),如下圖所示,並設為已啟用計費功能的有效 Google Cloud 專案。如果出現提示訊息,請點選「授權」。如果您已按照先前的指令操作,按鈕可能會直接指向已啟用的專案,而非登入按鈕

f5003b9c38b43262.png

  1. 接下來,我們將從 GitHub 複製本程式碼研究室的範本工作目錄,並執行下列指令。系統會在 deploy_and_manage_adk 目錄中建立工作目錄
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
  1. 接著,前往 Cloud Shell 編輯器的頂端部分,依序點選「File」>「Open Folder」,找出您的 使用者名稱資料夾,然後找出 deploy_and_manage_adk 資料夾,然後按一下「OK」按鈕。這會將所選目錄設為主要工作目錄。在本範例中,使用者名稱為 alvinprayuda,因此目錄路徑如下所示

2c53696f81d805cc.png

a51615f22ba1690f.png

您的 Cloud Shell 編輯器現在應如下所示:

228d4c1844790573.png

接下來,我們可以設定 Python 環境

環境設定

準備 Python 虛擬環境

下一個步驟是準備開發環境。目前的有效終端機工作目錄應位於 deploy_and_manage_adk 工作目錄中。我們會在本程式碼研究室中使用 Python 3.12,並使用 uv Python 專案管理工具,簡化 Python 版本和虛擬環境的建立及管理作業

  1. 如果尚未開啟終端機,請依序點選「Terminal」->「New Terminal」,或使用「Ctrl + Shift + C」鍵盤快速鍵,在瀏覽器底部開啟終端機視窗

f8457daf0bed059e.jpeg

  1. 下載 uv,然後使用下列指令安裝 Python 3.12
curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
  1. 接下來,我們將使用 uv 初始化虛擬環境,請執行下列指令
uv sync --frozen

這會建立 .venv 目錄並安裝依附元件。快速查看 pyproject.toml 可提供依附元件相關資訊,如下所示:

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]
  1. 如要測試虛擬環境,請建立新檔案 main.py,並複製下列程式碼
def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()
  1. 然後執行下列指令
uv run main.py

您會看到如下所示的輸出內容

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

這表示 Python 專案已正確設定。

設定設定檔

接下來,我們需要為這個專案設定設定檔。

.env.example 檔案重新命名為 .env,系統就會顯示下方的值。將 GOOGLE_CLOUD_PROJECT 值更新為專案 ID

# 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
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

在本程式碼研究室中,我們會使用 GOOGLE_CLOUD_LOCATIONGOOGLE_GENAI_USE_VERTEXAI. 的預先設定值。目前,我們會將 SESSION_SERVICE_URI 註解掉。

接下來,我們可以檢查並部署代理程式邏輯

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

簡介 ADK 目錄結構

首先,我們來探索 ADK 提供的功能,以及如何建構代理程式。如需 ADK 完整說明文件,請前往這個網址。ADK 在執行 CLI 指令時提供許多公用程式。其中一些是:

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

接下來,我們來檢查 weather_agent 目錄中的代理程式結構

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

如果您檢查 init.pyagent.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 google.cloud import logging as google_cloud_logging

# 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")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


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,以支援天氣服務的代理程式功能

執行網頁版 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)

e7c9f56c2463164.png

您會看到下方的網頁,可在左上方的下拉式選單中選取可用的服務項目 ( 在本例中應為 weather_agent),並與機器人互動。您會在左側視窗中看到許多代理程式執行階段的記錄詳細資料

d95b1e057315fee2.png

接著,請嘗試與其互動。在左側列中,我們可以檢查每個輸入內容的追蹤記錄,瞭解服務機器人執行每個動作所需的時間,進而形成最終答案。

39c0a06ace937683.png

這是 ADK 內建的可觀察性功能之一,目前我們會在本機檢查這項功能。稍後我們會說明如何將這項功能整合至 Cloud Tracing,以便集中追蹤所有要求

4. 後端伺服器指令碼

為了讓代理程式可做為服務存取,我們會在 FastAPI 應用程式中包裝代理程式。我們可以在此設定必要的服務來支援代理程式,例如準備用於實際工作環境的 SessionMemoryArtifact 服務。以下是將使用的 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
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


# 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}

# 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",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 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 = ""


@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_SERVICE_URI 環境變數,則工作階段服務會使用該變數,否則會使用記憶體內工作階段
  3. 我們可以新增自訂路徑來支援其他後端業務邏輯,在指令碼中,我們會新增意見回饋功能路徑範例
  4. 啟用雲端追蹤功能,將追蹤記錄傳送至 Google Cloud Trace

5. 部署至 Cloud Run

接下來,我們將這項代理程式服務部署至 Cloud Run。為了方便示範,這項服務會以可供他人存取的公開服務形式提供。不過請注意,這並非最佳做法,因為這不安全

5e38fc5607fb4543.jpeg

在本程式碼研究室中,我們將使用 Dockerfile 將我們的代理程式部署至 Cloud Run。以下是將使用的 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"]

此時,我們已取得將應用程式部署至 Cloud Run 所需的所有檔案,現在就來部署吧!前往 Cloud Shell 終端機,確認目前的專案已設為有效專案,如果沒有,請使用 gcloud configure 指令設定專案 ID:

gcloud config set project [PROJECT_ID]

接著執行下列指令,將應用程式部署至 Cloud Run。

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

如要取得 {YOUR_DB_CONNECTION_NAME} 值,請再次前往 Cloud SQL,然後按一下您建立的執行個體。在執行個體頁面中,向下捲動至「Connect to this instance」部分,然後複製連線名稱,以取代 {YOUR_DB_CONNECTION_NAME} 值。例如下圖所示

5d7d6c6f17e559c1.png

如果系統提示您確認建立 Docker 存放區的構件登錄,請回答「Y」。請注意,由於這是示範應用程式,因此我們允許未經驗證的存取權。建議您為企業和正式版應用程式使用適當的驗證機制。

部署完成後,您應該會收到類似以下的連結:

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

您可以繼續在無痕式視窗或行動裝置上使用應用程式。應該已經上線了。

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

接下來,我們將檢查 Cloud Run 的自動調整功能。在這個情境中,我們將部署新的修訂版本,並為每個執行個體啟用並行作業數量上限。執行下列指令

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

接著,我們來檢查 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」服務

f5cc953cc422de6d.png

接著找出 weather-agent 服務並點選

ddd0df8544aa2bfb.png

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

41b1276616379ee8.png

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

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 執行個體會嘗試調整容器數量,以便自動符合此條件。

1ad41143eb9d95df.png

7. 逐步發布新修訂版本

請考慮以下情境:我們想將代理程式的提示更新為以下內容:

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    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

完成後,您會收到與先前部署程序類似的記錄,差別在於放送的流量數量。這項指標會顯示放送的流量為 0%

接下來,我們前往 Cloud Run 產品頁面,找出已部署的執行個體。在搜尋列中輸入「Cloud Run」,然後點選 Cloud Run 產品

f5cc953cc422de6d.png

接著找出 weather-agent 服務並點選

ddd0df8544aa2bfb.png

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

8519c5a59bc7efa6.png

您會看到新部署的修訂版本放送率為 0%,此時您可以按一下三角按鈕 (⋮),然後選擇「管理流量」

d4d224e20813c303.png

在新彈出式視窗中,您可以編輯流量分配至哪些修訂版本的百分比。

6df497c3d5847f14.png

等待一段時間後,系統會根據百分比設定,將流量按比例導向。這樣一來,如果新版本發生問題,我們就能輕鬆回溯至先前的版本

8. ADK 追蹤功能

使用 AGDK 建構的代理程式已支援使用內嵌的開放式遙測功能進行追蹤。我們使用 Cloud Trace 擷取這些追蹤記錄並進行視覺化呈現。讓我們檢查 server.py,瞭解如何在先前部署的服務中啟用

# server.py

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

我們會在這裡初始化追蹤器和匯出工具。您可以在 tracing.py 中檢查匯出工具的詳細資料。由於可匯出至雲端追蹤的追蹤記錄資料有限制,因此我們在此建立自訂匯出器。我們使用的是 https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html 實作追蹤功能。

請嘗試存取服務的網頁開發人員 UI,並與服務專員進行即時通訊。接著,前往 Cloud 控制台搜尋列,輸入「trace explorer」,然後選擇「Trace Explorer」產品

4353c0f8982361ab.png

在追蹤記錄探索工具頁面上,您會看到我們與客服專員的對話記錄。您可以查看「Span name」部分,並篩除特定於我們的代理程式的 span ( 名稱為 agent_run [weather_agent])

c4336d117a3d2f6a.png

篩除區間後,您也可以直接檢查每個追蹤記錄。系統會顯示服務專員採取的每項動作詳細時間長度。例如,請參考下方圖片

76a56dff77979037.png

1a3ce0a803d6061a.png

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

2c87b6d67b0164a8.png

這樣一來,我們就能針對客服專員與使用者的每一次互動,取得良好的可觀察性和資訊,以便排解問題。歡迎您嘗試各種工具或工作流程!

9. 挑戰

嘗試使用多代理或代理工作流程,瞭解這些工作流程在負載下執行的情形,以及追蹤記錄的樣貌

10. 清理

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

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