Triển khai, quản lý và quan sát Tác nhân ADK trên Cloud Run

Thông tin về lớp học lập trình này

0 phút

Lần cập nhật gần đây nhất: 19 tháng 6, 2025

Tác giả: Alvin Prayuda Juniarta Dwiyantoro

Trang này được dịch bởi Cloud Translation API.

1. Giới thiệu

Hướng dẫn này sẽ hướng dẫn bạn cách triển khai, quản lý và giám sát một tác nhân mạnh mẽ được tạo bằng Agent Development Kit (ADK) trên Google Cloud Run. ADK giúp bạn tạo các tác nhân có thể thực hiện quy trình làm việc phức tạp, nhiều tác nhân. Bằng cách tận dụng Cloud Run, một nền tảng không máy chủ được quản lý toàn diện, bạn có thể triển khai tác nhân dưới dạng một ứng dụng được đóng gói trong vùng chứa và có thể mở rộng mà không cần lo lắng về cơ sở hạ tầng cơ bản. Sự kết hợp mạnh mẽ này cho phép bạn tập trung vào logic cốt lõi của tác nhân, đồng thời hưởng lợi từ môi trường mạnh mẽ và có thể mở rộng của Google Cloud.

Trong suốt hướng dẫn này, chúng ta sẽ khám phá cách tích hợp liền mạch ADK với Cloud Run. Bạn sẽ tìm hiểu cách triển khai tác nhân, sau đó tìm hiểu các khía cạnh thực tế của việc quản lý ứng dụng trong chế độ cài đặt giống như môi trường sản xuất. Chúng tôi sẽ trình bày cách triển khai phiên bản mới của tác nhân một cách an toàn bằng cách quản lý lưu lượng truy cập, cho phép bạn thử nghiệm các tính năng mới với một nhóm nhỏ người dùng trước khi phát hành đầy đủ.

Ngoài ra, bạn sẽ có được trải nghiệm thực tế về việc theo dõi hiệu suất của nhân viên hỗ trợ. Chúng ta sẽ mô phỏng một tình huống thực tế bằng cách tiến hành kiểm thử tải để quan sát khả năng tự động mở rộng quy mô của Cloud Run. Để hiểu rõ hơn về hành vi và hiệu suất của tác nhân, chúng tôi sẽ bật tính năng theo dõi bằng Cloud Trace. Tính năng này sẽ cung cấp thông tin chi tiết, toàn diện về các yêu cầu khi chúng đi qua tác nhân của bạn, cho phép bạn xác định và giải quyết mọi nút thắt cổ chai về hiệu suất. Khi kết thúc hướng dẫn này, bạn sẽ hiểu rõ cách triển khai, quản lý và giám sát các tác nhân chạy bằng ADK trên Cloud Run một cách hiệu quả.

Trong lớp học lập trình này, bạn sẽ áp dụng phương pháp từng bước như sau:

Tạo cơ sở dữ liệu PostgreSQL trên CloudSQL để dùng cho dịch vụ phiên cơ sở dữ liệu của Trình đại diện ADK
Thiết lập một tác nhân ADK cơ bản
Thiết lập dịch vụ phiên cơ sở dữ liệu để trình chạy ADK sử dụng
Triển khai ban đầu tác nhân cho Cloud Run
Kiểm thử tải và kiểm tra tính năng tự động mở rộng của Cloud Run
Triển khai bản sửa đổi mới của tác nhân và tăng dần lưu lượng truy cập vào các bản sửa đổi mới
Thiết lập tính năng theo dõi trên đám mây và kiểm tra tính năng theo dõi quá trình chạy của tác nhân

Tổng quan về cấu trúc

Điều kiện tiên quyết

Thoải mái làm việc với Python
Hiểu biết về cấu trúc toàn stack cơ bản bằng cách sử dụng dịch vụ HTTP

Kiến thức bạn sẽ học được

Cấu trúc ADK và các tiện ích cục bộ
Thiết lập tác nhân ADK bằng dịch vụ phiên Cơ sở dữ liệu
Thiết lập PostgreSQL trong CloudSQL để Dịch vụ phiên cơ sở dữ liệu sử dụng
Triển khai ứng dụng lên Cloud Run bằng Dockerfile và thiết lập các biến môi trường ban đầu
Định cấu hình và kiểm thử tính năng tự động mở rộng quy mô của Cloud Run bằng thử nghiệm tải
Chiến lược phát hành từng bước bằng Cloud Run
Thiết lập tính năng theo dõi Trình đại diện ADK đến Cloud Trace

Bạn cần có

Trình duyệt web Chrome
Tài khoản Gmail
Một dự án trên Google Cloud đã bật tính năng thanh toán

Lớp học lập trình này được thiết kế cho các nhà phát triển ở mọi cấp độ (kể cả người mới bắt đầu), sử dụng Python trong ứng dụng mẫu. Tuy nhiên, bạn không cần phải có kiến thức về Python để hiểu các khái niệm được trình bày.

2. Trước khi bắt đầu

Chọn Dự án đang hoạt động trong Cloud Console

Lớp học lập trình này giả định rằng bạn đã có một dự án trên Google Cloud đã bật tính năng thanh toán. Nếu chưa có, bạn có thể làm theo hướng dẫn bên dưới để bắt đầu.

Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên dự án hay không.

Chuẩn bị cơ sở dữ liệu Cloud SQL

Chúng ta sẽ cần một cơ sở dữ liệu để sau này, tác nhân ADK có thể sử dụng. Hãy tạo một cơ sở dữ liệu PostgreSQL trên Cloud SQL. Trước tiên, hãy chuyển đến thanh tìm kiếm ở phần trên cùng của bảng điều khiển trên đám mây rồi nhập "cloud sql". Sau đó, hãy nhấp vào sản phẩm Cloud SQL

Sau đó, chúng ta cần tạo một thực thể cơ sở dữ liệu mới, nhấp vào Create Instance (Tạo thực thể) rồi chọn PostgreSQL

Bạn cũng có thể cần bật API Compute Engine nếu bắt đầu với dự án mới. Chỉ cần nhấp vào Bật API nếu lời nhắc này xuất hiện

Tiếp theo, chúng ta sẽ chọn thông số kỹ thuật của cơ sở dữ liệu, chọn phiên bản Enterprise (Doanh nghiệp) với phiên bản Sandbox (Hộp cát) được đặt trước

Sau đó, hãy đặt tên thực thể và mật khẩu mặc định cho người dùng postgres tại đây. Bạn có thể thiết lập thông tin xác thực bất kỳ mà bạn muốn, tuy nhiên, để phù hợp với hướng dẫn này, chúng ta sẽ sử dụng "adk-deployment" cho cả tên thực thể và mật khẩu tại đây

Hãy sử dụng us-central1 với một vùng duy nhất cho hướng dẫn này, sau đó chúng ta có thể hoàn tất việc tạo cơ sở dữ liệu và để cơ sở dữ liệu hoàn tất tất cả các bước thiết lập bắt buộc bằng cách nhấp vào nút Tạo phiên bản

Trong khi chờ quá trình này hoàn tất, chúng ta có thể chuyển sang phần tiếp theo

Thiết lập dự án trên Cloud trong Cloud Shell Terminal

Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Google Cloud.

Sau khi kết nối với Cloud Shell, hãy kiểm tra để đảm bảo bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:

gcloud auth list

Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.

gcloud config list project

Nếu dự án của bạn chưa được đặt, hãy sử dụng lệnh sau để đặt dự án:

gcloud config set project <YOUR_PROJECT_ID>

Ngoài ra, bạn cũng có thể xem mã PROJECT_ID trong bảng điều khiển

Nhấp vào đó, bạn sẽ thấy tất cả dự án và mã dự án ở bên phải

Bật các API bắt buộc thông qua lệnh hiển thị bên dưới. Quá trình này có thể mất vài phút. Vui lòng kiên nhẫn chờ đợi.

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

Khi thực thi thành công lệnh này, bạn sẽ thấy một thông báo tương tự như thông báo dưới đây:

Operation "operations/..." finished successfully.

Bạn có thể sử dụng bảng điều khiển để tìm kiếm từng sản phẩm hoặc sử dụng đường liên kết này thay cho lệnh gcloud.

Nếu thiếu bất kỳ API nào, bạn luôn có thể bật API đó trong quá trình triển khai.

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.

Chuyển đến Trình chỉnh sửa Cloud Shell và Thiết lập thư mục làm việc của ứng dụng

Bây giờ, chúng ta có thể thiết lập trình soạn thảo mã để thực hiện một số thao tác lập trình. Chúng ta sẽ sử dụng Trình chỉnh sửa Cloud Shell để thực hiện việc này

Nhấp vào nút Open Editor (Mở trình chỉnh sửa), thao tác này sẽ mở một Cloud Shell Editor (Trình chỉnh sửa Cloud Shell), chúng ta có thể viết mã của mình tại đây
Đảm bảo dự án Cloud Code được đặt ở góc dưới bên trái (thanh trạng thái) của trình chỉnh sửa Cloud Shell, như được làm nổi bật trong hình ảnh bên dưới và được đặt thành dự án Google Cloud đang hoạt động mà bạn đã bật tính năng thanh toán. Uỷ quyền nếu được nhắc. Nếu bạn đã làm theo lệnh trước đó, nút này cũng có thể trỏ trực tiếp đến dự án đã kích hoạt thay vì nút đăng nhập

Tiếp theo, hãy sao chép thư mục hoạt động của mẫu cho lớp học lập trình này từ GitHub, chạy lệnh sau. Thao tác này sẽ tạo thư mục đang hoạt động trong thư mục deploy_and_manage_adk

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

Sau đó, hãy chuyển đến phần trên cùng của Trình chỉnh sửa Cloud Shell rồi nhấp vào File->Open Folder (Tệp->Mở thư mục), tìm thư mục username (tên người dùng) rồi tìm thư mục deploy_and_manage_adk, sau đó nhấp vào nút OK. Thao tác này sẽ đặt thư mục đã chọn làm thư mục làm việc chính. Trong ví dụ này, tên người dùng là alvinprayuda, do đó, đường dẫn thư mục sẽ hiển thị bên dưới

Bây giờ, Trình chỉnh sửa Cloud Shell của bạn sẽ có dạng như sau

Tiếp theo, chúng ta có thể định cấu hình chế độ thiết lập môi trường python

Thiết lập môi trường

Chuẩn bị môi trường ảo Python

Bước tiếp theo là chuẩn bị môi trường phát triển. Thư mục đang hoạt động của thiết bị đầu cuối hiện tại phải nằm trong thư mục đang hoạt động deploy_and_manage_adk. Chúng ta sẽ sử dụng Python 3.12 trong lớp học lập trình này và chúng ta sẽ sử dụng trình quản lý dự án python uv để đơn giản hoá nhu cầu tạo và quản lý phiên bản python cũng như môi trường ảo

Nếu bạn chưa mở thiết bị đầu cuối, hãy mở bằng cách nhấp vào Terminal (Thiết bị đầu cuối) -> New Terminal (Thiết bị đầu cuối mới) hoặc sử dụng tổ hợp phím Ctrl + Shift + C. Thao tác này sẽ mở một cửa sổ thiết bị đầu cuối ở phần dưới cùng của trình duyệt

Tải uv xuống và cài đặt python 3.12 bằng lệnh sau

curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

Bây giờ, hãy khởi chạy môi trường ảo bằng uv, Chạy lệnh này

uv sync --frozen

Thao tác này sẽ tạo thư mục .venv và cài đặt các phần phụ thuộc. Hãy xem nhanh pyproject.toml để biết thông tin về các phần phụ thuộc như sau

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]

Để kiểm thử môi trường ảo, hãy tạo tệp mới main.py và sao chép mã sau

def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()

Sau đó, hãy chạy lệnh sau

uv run main.py

Bạn sẽ nhận được kết quả như sau

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

Điều này cho thấy dự án python đang được thiết lập đúng cách.

Thiết lập tệp cấu hình

Bây giờ, chúng ta cần thiết lập các tệp cấu hình cho dự án này.

Đổi tên tệp .env.example thành .env và tệp này sẽ hiển thị giá trị bên dưới. Cập nhật giá trị GOOGLE_CLOUD_PROJECT thành mã dự án của bạn

# 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

Trong lớp học lập trình này, chúng ta sẽ sử dụng các giá trị được định cấu hình trước cho GOOGLE_CLOUD_LOCATION và GOOGLE_GENAI_USE_VERTEXAI.. Hiện tại, chúng ta sẽ giữ lại phần chú thích SESSION_SERVICE_URI.

Bây giờ, chúng ta có thể chuyển sang bước tiếp theo, kiểm tra logic của tác nhân và triển khai logic đó

3. Tạo Trình đại diện thời tiết bằng ADK và Gemini 2.5

Giới thiệu về Cấu trúc thư mục ADK

Hãy bắt đầu bằng cách khám phá những gì ADK cung cấp và cách tạo tác nhân. Bạn có thể truy cập vào tài liệu đầy đủ về ADK tại URL này . ADK cung cấp cho chúng ta nhiều tiện ích trong quá trình thực thi lệnh CLI. Sau đây là một số yếu tố :

Thiết lập cấu trúc thư mục của tác nhân
Thử tương tác nhanh qua đầu ra đầu vào CLI
Thiết lập nhanh giao diện web của giao diện người dùng phát triển cục bộ

Bây giờ, hãy kiểm tra cấu trúc của tác nhân trên thư mục weather_agent

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

Và nếu kiểm tra init.py và agent.py, bạn sẽ thấy mã này

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

Giải thích mã ADK

Tập lệnh này chứa quá trình khởi tạo tác nhân, trong đó chúng ta khởi chạy những nội dung sau:

Đặt mô hình sẽ được sử dụng thành gemini-2.5-flash
Cung cấp công cụ get_weather để hỗ trợ chức năng của tác nhân dưới dạng tác nhân thời tiết

Chạy giao diện người dùng web

Bây giờ, chúng ta có thể tương tác với tác nhân và kiểm tra hành vi của tác nhân cục bộ. ADK cho phép chúng ta có giao diện người dùng web phát triển để tương tác và kiểm tra những gì đang diễn ra trong quá trình tương tác. Chạy lệnh sau để khởi động máy chủ giao diện người dùng phát triển cục bộ

uv run adk web --port 8080

Thao tác này sẽ tạo ra kết quả như ví dụ sau, tức là chúng ta đã có thể truy cập vào giao diện web

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)

Bây giờ, để kiểm tra, hãy nhấp vào nút Xem trước trên web ở khu vực trên cùng của Trình chỉnh sửa Cloud Shell rồi chọn Xem trước trên cổng 8080

Bạn sẽ thấy trang web sau đây, trong đó bạn có thể chọn các tác nhân hiện có trên nút thả xuống ở trên cùng bên trái ( trong trường hợp này là weather_agent) và tương tác với bot. Bạn sẽ thấy nhiều thông tin về chi tiết nhật ký trong thời gian chạy của tác nhân trong cửa sổ bên trái

Bây giờ, hãy thử tương tác với nó. Trên thanh bên trái, chúng ta có thể kiểm tra dấu vết cho mỗi dữ liệu đầu vào để biết thời gian cần thiết cho mỗi hành động mà tác nhân thực hiện trước khi tạo ra câu trả lời cuối cùng.

Đây là một trong những tính năng quan sát được tích hợp sẵn vào ADK, hiện chúng ta kiểm tra tính năng này trên máy. Sau này, chúng ta sẽ xem cách tích hợp tính năng này vào tính năng Theo dõi trên đám mây để có được dấu vết tập trung của tất cả các yêu cầu

4. Tập lệnh máy chủ phụ trợ

Để có thể truy cập vào tác nhân dưới dạng dịch vụ, chúng ta sẽ gói tác nhân bên trong ứng dụng FastAPI. Chúng ta có thể định cấu hình các dịch vụ cần thiết để hỗ trợ tác nhân tại đây, chẳng hạn như chuẩn bị dịch vụ Phiên, Bộ nhớ hoặc Cấu phần phần mềm cho mục đích sản xuất tại đây. Dưới đây là mã của server.py sẽ được sử dụng

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)

Giải thích mã máy chủ

Dưới đây là những nội dung được xác định trong tập lệnh server.py:

Chuyển đổi tác nhân của chúng ta thành ứng dụng FastAPI bằng phương thức get_fast_api_app. Bằng cách này, chúng ta sẽ kế thừa cùng một định nghĩa tuyến đường được sử dụng cho giao diện người dùng phát triển web.
Định cấu hình dịch vụ Phiên, Bộ nhớ hoặc Cấu phần phần mềm cần thiết bằng cách thêm các đối số từ khoá vào phương thức get_fast_api_app. Trong hướng dẫn này, nếu chúng ta định cấu hình biến môi trường SESSION_SERVICE_URI, thì dịch vụ phiên sẽ sử dụng biến đó, nếu không thì dịch vụ sẽ sử dụng phiên trong bộ nhớ
Chúng ta có thể thêm tuyến tuỳ chỉnh để hỗ trợ các logic nghiệp vụ phụ trợ khác, trong tập lệnh, chúng ta thêm ví dụ về tuyến chức năng phản hồi
Bật tính năng theo dõi trên đám mây để gửi dấu vết đến Google Cloud Trace

5. Triển khai lên Cloud Run

Bây giờ, hãy triển khai dịch vụ tác nhân này cho Cloud Run. Để minh hoạ, dịch vụ này sẽ được hiển thị dưới dạng dịch vụ công khai mà người khác có thể truy cập. Tuy nhiên, hãy lưu ý rằng đây không phải là phương pháp hay nhất vì không an toàn

Trong lớp học lập trình này, chúng ta sẽ sử dụng Dockerfile để triển khai tác nhân của mình lên Cloud Run. Dưới đây là nội dung Dockerfile sẽ được sử dụng

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

Tại thời điểm này, chúng ta đã có tất cả các tệp cần thiết để triển khai ứng dụng trên Cloud Run. Hãy triển khai ứng dụng. Chuyển đến Cloud Shell Terminal và đảm bảo dự án hiện tại được định cấu hình thành dự án đang hoạt động của bạn, nếu không, bạn phải sử dụng lệnh gcloud configure để đặt mã dự án:

gcloud config set project [PROJECT_ID]

Sau đó, hãy chạy lệnh sau để triển khai ứng dụng đó lên 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

Để lấy giá trị {YOUR_DB_CONNECTION_NAME}, bạn có thể quay lại Cloud SQL và nhấp vào phiên bản bạn đã tạo. Bên trong trang thực thể, hãy di chuyển xuống phần "Kết nối với thực thể này" và bạn có thể sao chép Tên kết nối để thay thế giá trị {YOUR_DB_CONNECTION_NAME}. Ví dụ: hình ảnh bên dưới

Nếu bạn được nhắc xác nhận việc tạo một kho lưu trữ cấu phần phần mềm cho kho lưu trữ docker, bạn chỉ cần trả lời Có. Xin lưu ý rằng chúng tôi đang cho phép quyền truy cập chưa xác thực tại đây vì đây là ứng dụng minh hoạ. Bạn nên sử dụng phương thức xác thực phù hợp cho các ứng dụng doanh nghiệp và ứng dụng phát hành chính thức.

Sau khi triển khai xong, bạn sẽ nhận được một đường liên kết tương tự như bên dưới:

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

Hãy tiếp tục sử dụng ứng dụng của bạn trong cửa sổ Ẩn danh hoặc trên thiết bị di động. Trang web đã được xuất bản.

6. Kiểm tra tính năng Tự động mở rộng của Cloud Run bằng thử nghiệm tải

Bây giờ, chúng ta sẽ kiểm tra các tính năng tự động mở rộng của Cloud Run. Đối với trường hợp này, hãy triển khai bản sửa đổi mới trong khi bật số lượng đồng thời tối đa trên mỗi thực thể. Chạy lệnh sau

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

Sau đó, hãy kiểm tra tệp load_test.py. Đây sẽ là tập lệnh chúng ta sử dụng để kiểm thử tải bằng khung locust. Tập lệnh này sẽ thực hiện những việc sau :

user_id và session_id được tạo ngẫu nhiên
Tạo session_id cho user_id
Truy cập vào điểm cuối "/run_sse" bằng user_id và session_id đã tạo

Chúng tôi cần biết URL dịch vụ đã triển khai của bạn (nếu bạn chưa cung cấp). Chuyển đến bảng điều khiển Cloud Run rồi nhấp vào dịch vụ weather-agent

Sau đó, hãy tìm dịch vụ weather-agent rồi nhấp vào dịch vụ đó

URL của dịch vụ sẽ xuất hiện ngay bên cạnh thông tin về Khu vực. Ví dụ:

Sau đó, hãy chạy lệnh sau để kiểm thử tải

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

Khi chạy mã này, bạn sẽ thấy các chỉ số như sau. ( Trong ví dụ này, tất cả các yêu cầu đều thành công )

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

Sau đó, hãy xem điều gì đã xảy ra trong Cloud Run, quay lại dịch vụ đã triển khai và xem trang tổng quan. Điều này sẽ cho thấy cách đám mây chạy tự động mở rộng thực thể để xử lý các yêu cầu đến. Vì chúng tôi đang giới hạn số lượng đồng thời tối đa là 10 cho mỗi thực thể, nên thực thể chạy trên đám mây sẽ cố gắng tự động điều chỉnh số lượng vùng chứa để đáp ứng điều kiện này.

7. Phát hành dần các bản sửa đổi mới

Bây giờ, hãy xem xét trường hợp sau. Chúng ta muốn cập nhật lời nhắc của trợ lý thành như sau :

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

Sau đó, bạn muốn phát hành các bản sửa đổi mới nhưng không muốn tất cả lưu lượng truy cập yêu cầu chuyển trực tiếp đến phiên bản mới. Chúng ta có thể phát hành dần dần bằng Cloud Run. Trước tiên, chúng ta cần triển khai một bản sửa đổi mới, nhưng có cờ –no-traffic (không có lưu lượng truy cập). Lưu tập lệnh tác nhân trước đó và chạy lệnh sau

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

Sau khi hoàn tất, bạn sẽ nhận được một nhật ký tương tự như quy trình triển khai trước đó, chỉ khác ở số lượng lưu lượng truy cập được phân phát. Thẻ này sẽ hiển thị lưu lượng truy cập được phân phát là 0%.

Tiếp theo, hãy chuyển đến trang sản phẩm Cloud Run và tìm thực thể đã triển khai của bạn. Nhập cloud run vào thanh tìm kiếm rồi nhấp vào sản phẩm Cloud Run

Sau đó, hãy tìm dịch vụ weather-agent rồi nhấp vào dịch vụ đó

Chuyển đến thẻ Bản sửa đổi, bạn sẽ thấy danh sách các bản sửa đổi đã triển khai tại đó

Bạn sẽ thấy các bản sửa đổi mới được triển khai đang phân phát 0%. Từ đây, bạn có thể nhấp vào nút trình đơn thả xuống (⋮) rồi chọn Quản lý lưu lượng truy cập

Trong cửa sổ mới bật lên, bạn có thể chỉnh sửa tỷ lệ phần trăm lưu lượng truy cập chuyển đến bản sửa đổi nào.

Sau khi chờ một lúc, lưu lượng truy cập sẽ được phân bổ theo tỷ lệ dựa trên cấu hình theo tỷ lệ phần trăm. Bằng cách này, chúng ta có thể dễ dàng quay lại các bản sửa đổi trước đó nếu có vấn đề xảy ra với bản phát hành mới

8. Theo dõi ADK

Các tác nhân được tạo bằng ADK đã hỗ trợ tính năng theo dõi bằng cách nhúng tính năng đo từ xa mở trong đó. Chúng ta có Cloud Trace để ghi lại và trực quan hoá những dấu vết đó. Hãy kiểm tra server.py về cách chúng ta bật trong dịch vụ đã triển khai trước đó

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

...

Tại đây, chúng ta khởi chạy trình theo dõi và trình xuất. Bạn có thể kiểm tra thông tin chi tiết của trình xuất trên tracing.py . Tại đây, chúng ta tạo một trình xuất tuỳ chỉnh vì có giới hạn về dữ liệu theo dõi có thể xuất sang dấu vết trên đám mây. Chúng tôi đang sử dụng cách triển khai từ https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html cho tính năng theo dõi này.

Hãy thử truy cập vào giao diện người dùng dành cho nhà phát triển web của dịch vụ và trò chuyện với chuyên viên hỗ trợ. Sau đó, hãy chuyển đến thanh tìm kiếm của Cloud Console, nhập "trace explorer" (trình khám phá dấu vết) rồi chọn sản phẩm Trace Explorer (Trình khám phá dấu vết) tại đó

Trên trang trình khám phá dấu vết, bạn sẽ thấy cuộc trò chuyện của chúng ta với dấu vết của nhân viên hỗ trợ đã được gửi. Bạn có thể xem trong phần Tên span và lọc ra span dành riêng cho tác nhân của chúng tôi ( có tên là agent_run [weather_agent]) tại đó

Khi các span đã được lọc, bạn cũng có thể trực tiếp kiểm tra từng dấu vết. Trang này sẽ cho thấy thời lượng chi tiết của từng hành động mà nhân viên hỗ trợ thực hiện. Ví dụ: hãy xem hình ảnh bên dưới

Trên mỗi phần, bạn có thể kiểm tra thông tin chi tiết trong các thuộc tính như minh hoạ bên dưới

Vậy là xong, giờ đây chúng ta có thể quan sát và nắm được thông tin về từng lượt tương tác của tác nhân với người dùng để giúp gỡ lỗi. Hãy thoải mái thử nhiều công cụ hoặc quy trình làm việc!

9. Thách thức

Thử quy trình làm việc nhiều tác nhân hoặc tác nhân để xem chúng hoạt động như thế nào khi tải và dấu vết trông như thế nào

10. Dọn dẹp

Để tránh bị tính phí cho tài khoản Google Cloud của bạn đối với các tài nguyên dùng trong lớp học lập trình này, hãy làm theo các bước sau:

Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên.
Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá, rồi nhấp vào Xoá.
Trong hộp thoại, hãy nhập mã dự án, sau đó nhấp vào Shut down (Tắt) để xoá dự án.
Ngoài ra, bạn có thể chuyển đến Cloud Run trên bảng điều khiển, chọn dịch vụ bạn vừa triển khai rồi xoá.