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

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

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ó khả năng thực hiện quy trình làm việc phức tạp với 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 của mình dưới dạng một ứng dụng có thể mở rộng và được chứa trong vùng chứa 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 trong khi vẫn được hưởng lợi từ môi trường mạnh mẽ và có khả năng mở rộng của Google Cloud.

Trong suốt hướng dẫn này, chúng ta sẽ khám phá quá trình 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 của mình, sau đó đi sâu vào các khía cạnh thực tế của việc quản lý ứng dụng trong một chế độ cài đặt giống như môi trường sản xuất. Chúng ta sẽ tìm hiểu cách triển khai các 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 chính thức.

Hơn nữa, bạn sẽ có được trải nghiệm thực tế về việc giám sát hiệu suất của trợ lý ảo. 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 mở rộng quy mô tự động của Cloud Run trong thực tế. Để 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. Điều 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 điểm nghẽn 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 hiệu quả các tác nhân dựa trên ADK trên Cloud Run.

Trong lớp học lập trình này, bạn sẽ sử 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 ADK Agent
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 để được trình chạy ADK sử dụng
Triển khai ban đầu tác nhân vào Cloud Run
Kiểm thử tải và kiểm tra tính năng tự động mở rộng quy mô của Cloud Run
Triển khai bản sửa đổi tác nhân mới 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 đám mây và kiểm tra tính năng theo dõi lượt 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 cơ bản của ngăn xếp đầy đủ 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 để được dùng bởi dịch vụ phiên Cơ sở dữ liệu
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ô Cloud Run bằng kiểm thử 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 ADK Agent cho Cloud Trace

Bạn cần có

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

Lớp học lập trình này được thiết kế cho 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 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 có 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 chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng 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 một dự án hay không.

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

Sau này, chúng ta sẽ cần một cơ sở dữ liệu để được tác nhân ADK 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 đá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 sẽ cần tạo một phiên bản cơ sở dữ liệu mới, nhấp vào Tạo phiên bản và chọn PostgreSQL

Bạn cũng có thể cần bật Compute Engine API nếu bắt đầu bằng 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 các thông số kỹ thuật của cơ sở dữ liệu, chọn phiên bản Enterprise với chế độ cài đặt sẵn Sandbox

Sau đó, hãy đặt tên phiên bản 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 đăng nhập tuỳ ý, tuy nhiên, trong hướng dẫn này, chúng ta sẽ sử dụng "adk-deployment" cho cả tên phiên bản và mật khẩu

Hãy sử dụng us-central1 với một vùng 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ể tiếp tục chuyển sang phần tiếp theo

Thiết lập dự án trên Cloud trong thiết bị đầu cuối Cloud Shell

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, bạn có thể kiểm tra để đảm bảo rằng 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 bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:

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 bên dưới. Quá trình này có thể mất vài phút, vì vậy, 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 lệnh thành công, 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ể thay thế lệnh gcloud bằng cách tìm kiếm từng sản phẩm trên bảng điều khiển hoặc sử dụng đường liên kết này.

Nếu bỏ lỡ 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 Cloud Shell Editor 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 chỉnh sửa mã để thực hiện một số việc liên quan đến mã hoá. Chúng ta sẽ sử dụng Trình chỉnh sửa Cloud Shell cho 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ở Cloud Shell Editor. Chúng ta có thể viết mã 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 đánh dấu trong hì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 của bạn thay vì nút đăng nhập

Tiếp theo, hãy sao chép thư mục làm việc của mẫu cho lớp học lập trình này từ GitHub bằng cách 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 Cloud Shell Editor 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) của bạn, tìm thư mục deploy_and_manage_adk (triển khai và quản lý ADK) rồi 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 được hiển thị bên dưới

Giờ đây, Cloud Shell Editor 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à sử dụng trình quản lý dự án uv python để đơ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ở cửa sổ dòng lệnh, hãy mở bằng cách nhấp vào Terminal (Cửa sổ dòng lệnh) -> New Terminal (Cửa sổ dòng lệnh 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ổ dòng lệnh ở 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 động 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. Xem nhanh pyproject.toml sẽ cung cấp cho bạn thông tin về các phần phụ thuộc xuất hiện 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 rồi 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ả đầu ra như bên dưới

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ẽ cho thấy giá trị bên dưới. Cập nhật giá trị GOOGLE_CLOUD_PROJECT thành project-id 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

Đối với 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 sẵn cho GOOGLE_CLOUD_LOCATION và GOOGLE_GENAI_USE_VERTEXAI.. Hiện tại, chúng ta sẽ giữ SESSION_SERVICE_URI ở trạng thái được nhận xét.

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 Weather Agent 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 tính năng mà 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ố ví dụ :

Thiết lập cấu trúc thư mục tác nhân
Nhanh chóng thử tương tác thông qua đầu vào và đầu ra của 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 trong thư mục weather_agent

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

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 phần khởi tạo nhân viên hỗ trợ, trong đó chúng ta khởi tạo những điều sau:

Đặt mô hình sẽ được 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

Giờ đây, 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 theo cách cục bộ. ADK cho phép chúng tôi có một giao diện người dùng web để phát triển nhằm 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

Lệnh 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 Web Preview (Xem trước trên web) ở khu vực trên cùng của Cloud Shell Editor rồi chọn Preview on port 8080 (Xem trước trên cổng 8080)

Bạn sẽ thấy trang web sau đây, nơi bạn có thể chọn các tác nhân có sẵn trên nút thả xuống ở trên cùng bên trái ( trong trường hợp của chúng ta, đó phải 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 ở 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 của từng đầu vào, nhờ đó, chúng ta có thể biết được thời gian cần thiết cho từng hành động mà tác nhân thực hiện trước khi đưa 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 vào ADK. Hiện tại, chúng tôi kiểm tra tính năng này cục bộ. Sau đó, chúng ta sẽ xem cách tích hợp này vào Cloud Tracing để 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ợ

Để cung cấp tác nhân dưới dạng một dịch vụ, chúng ta sẽ bao bọc tác nhân trong một ứng dụng FastAPI. Tại đây, 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, chẳng hạn như chuẩn bị dịch vụ Session (Phiên), Memory (Bộ nhớ) hoặc Artifact (Hiện vật) cho mục đích sản xuất. Dưới đây là mã của server.py sẽ được 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 về mã máy chủ

Đâ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 một ứ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 về tuyến đường được 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 Dịch vụ tạo tác 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 đường tuỳ chỉnh để hỗ trợ logic nghiệp vụ phụ trợ khác. Trong tập lệnh, chúng ta sẽ thêm ví dụ về tuyến đường chức năng phản hồi
Bật tính năng theo dõi đá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 lên Cloud Run. Để minh hoạ, dịch vụ này sẽ được cung cấp dưới dạng một 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ẽ dùng Dockerfile để triển khai tác nhân của mình vào Cloud Run. Dưới đây là nội dung Dockerfile sẽ được 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"]

Đến đây, chúng ta đã có tất cả các tệp cần thiết để triển khai ứng dụng lê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 cho dự án đang hoạt động của bạn. Nếu không, bạn phải 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 này vào 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ể chuyển đến Cloud SQL một lần nữa rồi nhấp vào phiên bản mà bạn đã tạo. Trong trang phiên bản, hãy di chuyển xuống phần "Kết nối với phiên bản này" để sao chép Tên kết nối nhằm thay thế giá trị {YOUR_DB_CONNECTION_NAME}. Ví dụ về hình ảnh trang phục như bên dưới

Lưu ý: Khi bạn thiết lập SESSION_SERVICE_URI, tác nhân ADK của chúng tôi sẽ sử dụng URI cho dịch vụ để lưu trữ thông tin và trạng thái phiên. Trong hướng dẫn này, chúng ta sẽ sử dụng kết nối socket Unix của PostgreSQL với trình điều khiển pg8000.

Xin lưu ý rằng trong ví dụ này, chúng ta sử dụng người dùng mặc định postgres và cơ sở dữ liệu mặc định postgres. Nếu bạn sử dụng các giá trị giống như trong hướng dẫn, thì SESSION_SERVICE_URI của bạn sẽ có dạng như sau

SESSION_SERVICE_URI="postgresql+pg8000://postgres:adk-deployment@postgres/?unix_sock=/cloudsql/{YOUR_PROJECT_ID}:us-central1:adk-deployment/.s.PGSQL.5432"

Do đó, bạn chỉ cần thay thế mã dự án tại đây

Nếu bạn được nhắc xác nhận việc tạo một sổ đăng ký hiện vật cho kho lưu trữ docker, hãy trả lời Y. Xin lưu ý rằng chúng tôi đang cho phép truy cập chưa xác thực tại đây vì đây là một ứ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 công khai.

Sau khi quá trình triển khai hoàn tất, bạn sẽ nhận được một đường liên kết tương tự như đường liên kết 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. Nội dung đó đã được xuất bản.

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

Bây giờ, chúng ta sẽ kiểm tra khả năng tự động mở rộng quy mô của Cloud Run. Trong trường hợp này, hãy triển khai bản sửa đổi mới trong khi cho phép số lượng yêu cầu đồng thời tối đa trên mỗi phiên bản. 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 mà chúng ta dùng để thực hiện 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 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 sẽ cần biết URL dịch vụ đã triển khai của mình, nếu bạn bỏ lỡ. 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 để thực hiện 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 lệnh này, bạn sẽ thấy các chỉ số như thế này xuất hiện. ( 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, truy cập lại vào dịch vụ đã triển khai của bạn và xem trang tổng quan. Điều này sẽ cho thấy cách Cloud Run tự động mở rộng quy mô phiên bản để xử lý các yêu cầu đến. Vì chúng tôi đang giới hạn số lượng yêu cầu đồng thời tối đa là 10 cho mỗi phiên bản, nên phiên bản Cloud Run sẽ tự động tìm cách đ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 tôi muốn cập nhật câu lệnh của trợ lý thành câu lệ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 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. 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 là số lượng lưu lượng truy cập được phân phát. Thử nghiệm này sẽ cho thấy 0% lưu lượng truy cập được phân phát.

Tiếp theo, hãy truy cập vào trang sản phẩm Cloud Run và tìm phiên bản đã 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 rằng 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 tuỳ chọn (⋮) 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 các bản sửa đổi.

Sau một thời gian chờ, lưu lượng truy cập sẽ được chuyển hướng theo tỷ lệ dựa trên cấu hình 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 sử dụng tính năng nhúng đo từ xa mở trong đó. Chúng tôi có Cloud Trace để ghi lại và trực quan hoá những dấu vết đó. Hãy kiểm tra server.py để biết cách bật tính năng này trong dịch vụ mà chúng ta đã 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)

...

Ở đây, chúng ta khởi tạo trình theo dõi và trình xuất. Bạn có thể kiểm tra thông tin chi tiết về trình xuất trên tracing.py . Ở đâ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 dấu vết có thể xuất sang dấu vết đám mây. Chúng tôi đang sử dụng một cách triển khai từ https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html cho khả năng theo dõi này.

Hãy thử truy cập vào giao diện người dùng web dành cho nhà phát triển dịch vụ của bạn và trò chuyện với tác nhân. Sau đó, hãy chuyển đến thanh tìm kiếm của Cloud Console, nhập "trace explorer" rồi chọn sản phẩm Trace Explorer 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 tôi với dấu vết tác nhân đã được gửi. Bạn có thể thấy trong phần Span name (Tên khoảng thời gian) và lọc ra khoảng thời gian dành riêng cho tác nhân của chúng tôi (được đặt tên là agent_run [weather_agent]) tại đó

Khi các khoảng đã được lọc, bạn cũng có thể kiểm tra trực tiếp từng dấu vết. Báo cáo này sẽ cho biết 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ụ: xem hình ảnh bên dưới

Trong 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

Đến đây là hết, giờ chúng ta đã có khả năng quan sát và thông tin đầy đủ về từng lượt tương tác của trợ lý ảo với người dùng để giúp gỡ lỗi. Bạn có thể thoải mái thử nhiều công cụ hoặc quy trình làm việc!

9. Thách thức

Hãy thử quy trình làm việc có nhiều tác nhân hoặc dựa trên tác nhân để xem hiệu suất của các quy trình này khi chịu tải và hình dạng của dấu vết

10. Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được 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 rồi nhấp vào 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á.