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

LƯU Ý QUAN TRỌNG:

Hướng dẫn này yêu cầu bạn phải có một Dự án trên Google Cloud có tài khoản thanh toán đang hoạt động. Nếu bạn chưa có tài khoản thanh toán, vui lòng làm theo các bước bên dưới để tạo một tài khoản thanh toán dùng thử có thể dùng cho hướng dẫn này:

Mở cửa sổ ẩn danh
Nếu tham gia một buổi hội thảo, bạn thường sẽ nhận được URL của cổng đổi quà trong buổi hội thảo đó. Nếu không, bạn có thể truy cập vào cổng đổi quà của tài khoản thanh toán dùng thử này
Đăng nhập bằng tài khoản Gmail cá nhân của bạn ( Google Workspace / các email khác sẽ không hoạt động! )
Làm theo hướng dẫn từng bước về cách sử dụng để tạo thành công một dự án Google Cloud mới cho hướng dẫn này

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 đầy đủ.

Hơn nữa, bạn sẽ có được trải nghiệm thực tế về việc theo dõi 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 tự động mở rộng quy mô 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 của 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 lên 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 khi 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. 🚀 Chuẩn bị thiết lập môi trường phát triển cho hội thảo

Bước 1: Chọn Dự án đang hoạt động trong Cloud Console

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 (xem phần trên cùng bên trái của bảng điều khiển)

Nhấp vào biểu tượng đó, bạn sẽ thấy danh sách tất cả dự án của mình như ví dụ này:

Giá trị được biểu thị bằng hộp màu đỏ là MÃ DỰ ÁN và giá trị này sẽ được dùng trong suốt hướng dẫn.

Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Để kiểm tra, hãy nhấp vào biểu tượng trình đơn ☰ ở thanh trên cùng bên trái để xem Trình đơn điều hướng và tìm trình đơn Thanh toán

Nếu bạn thấy "Tài khoản thanh toán dùng thử của Google Cloud Platform" trong phần Thanh toán / Tổng quan ( phần trên cùng bên trái của bảng điều khiển đám mây), thì dự án của bạn đã sẵn sàng để sử dụng cho hướng dẫn này. Nếu không, hãy quay lại đầu hướng dẫn này và sử dụng tài khoản thanh toán dùng thử

Bước 2: 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 Doanh nghiệp 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 theo ý muốn. Tuy nhiên, trong hướng dẫn này, chúng ta sẽ sử dụng "adk-deployment" cho tên phiên bản và "ADK-deployment123" cho 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 mọi chế độ 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

Bước 3: Làm quen với Cloud Shell

Bạn sẽ sử dụng Cloud Shell cho hầu hết các phần của hướng dẫn, hãy nhấp vào Kích hoạt Cloud Shell ở đầu Google Cloud Console. Nếu hệ thống nhắc bạn uỷ quyền, hãy nhấp vào Uỷ quyền

Sau khi kết nối với Cloud Shell, chúng ta cần kiểm tra xem shell ( hoặc cửa sổ dòng lệnh) đã được xác thực bằng tài khoản của chúng ta hay chưa

gcloud auth list

Nếu bạn thấy gmail cá nhân của mình như ví dụ về đầu ra bên dưới, thì mọi thứ đều ổn

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

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

Nếu không, hãy thử làm mới trình duyệt và đảm bảo bạn nhấp vào Uỷ quyền khi được nhắc ( quá trình này có thể bị gián đoạn do sự cố kết nối)

Tiếp theo, chúng ta cũng cần kiểm tra xem shell đã được định cấu hình thành PROJECT ID chính xác mà bạn có hay chưa. Nếu thấy có giá trị bên trong ( ) trước biểu tượng $ trong thiết bị đầu cuối ( trong ảnh chụp màn hình bên dưới, giá trị là "adk-cloudrun-deployment-476504"), thì giá trị này cho biết dự án đã được định cấu hình cho phiên shell đang hoạt động của bạn.

Nếu giá trị xuất hiện đã chính xác, bạn có thể bỏ qua lệnh tiếp theo. Tuy nhiên, nếu không chính xác hoặc bị thiếu, hãy chạy lệnh sau

gcloud config set project <YOUR_PROJECT_ID>

Sau đó, 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

Bước 4: Làm quen với 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

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, thư mục làm việc của Cloud Shell Editor sẽ có dạng như sau ( trong deploy_and_manage_adk)

Bây giờ, hãy mở cửa sổ dòng lệnh cho trình chỉnh sửa. Bạn có thể thực hiện việc này bằng cách nhấp vào Terminal -> New Terminal (Cửa sổ dòng lệnh -> Cửa sổ dòng lệnh mới) trên thanh trình đơn 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

Thiết bị đầu cuối đang hoạt động hiện tại của bạn phải nằm trong thư mục làm việc 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. Gói uv này đã được cài đặt sẵn trên Cloud Shell.

Chạy lệnh này để cài đặt các phần phụ thuộc cần thiết cho môi trường ảo trong thư mục .venv

uv sync --frozen

Bây giờ, chúng ta sẽ cần 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 một chút thời gian.

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.

Tiếp theo, chúng ta sẽ 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

cp .env.example .env

Mở tệp .env rồi cập nhật giá trị GOOGLE_CLOUD_PROJECT thành project-id

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

Đố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ữ DB_CONNECTION_NAME ở 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. 🚀 Xây dựng 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
└── tool.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 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],
)

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 trên thiết 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. 🚀 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. Tại thời điểm này, chúng ta đã có tất cả các tệp cần thiết ( Dockerfile và server.py) để triển khai các ứng dụng của mình lên Cloud Run. Chúng ta sẽ thảo luận chi tiết về vấn đề này ở phần sau.

Bây giờ, hãy triển khai dịch vụ trước. 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]

Bây giờ, chúng ta cần truy cập lại vào tệp .env, mở tệp này và bạn sẽ thấy rằng chúng ta cần bỏ chú thích biến DB_CONNECTION_NAME rồi điền giá trị chính xác vào biế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
DB_CONNECTION_NAME=your-db-connection-name

Để lấy giá trị 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. 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 đó, bạn sẽ thấy phiên bản đã tạo trước đó, hãy nhấp vào phiên bản đó

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ị DB_CONNECTION_NAME.

Sau đó, hãy mở tệp .env rồi sửa đổi biến DB_CONNECTION_NAME. Tệp env của bạn sẽ có dạng như ví dụ bên dưới

# 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

Sau đó, hãy chạy tập lệnh triển khai

bash deploy_to_cloudrun.sh

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.

Trong khi chờ quá trình triển khai, hãy xem 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

Tập lệnh này sẽ tải biến .env của bạn, sau đó chạy lệnh triển khai.

Nếu xem xét kỹ hơn, bạn sẽ thấy chúng ta chỉ cần một lệnh gcloud run deploy để thực hiện tất cả những việc cần thiết nếu muốn triển khai một dịch vụ: tạo hình ảnh, đẩy vào sổ đăng ký, triển khai dịch vụ, đặt chính sách IAM, tạo bản sửa đổi và thậm chí cả định tuyến lưu lượng truy cập. Trong ví dụ này, chúng ta đã cung cấp Dockerfile, do đó, lệnh này sẽ sử dụng Dockerfile để tạo ứng dụng

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

Sau khi nhận được URL này, bạn có thể sử dụng ứng dụng của mình trong cửa sổ ẩn danh hoặc thiết bị di động và truy cập vào giao diện người dùng dành cho nhà phát triển của tác nhân. Trong khi chờ triển khai, hãy kiểm tra dịch vụ chi tiết mà chúng ta vừa triển khai trong phần tiếp theo

5. 💡 Dockerfile và 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 sẽ chạy trên lệnh Dockerfile. Dưới đây là nội dung của 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"]

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ụ Session, Memory hoặc Artifact cho mục đích sản xuất tại đây. 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


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

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 trong các tham số get_fast_api_app arg để gửi dấu vết đến Google Cloud Trace
Chạy dịch vụ FastAPI bằng uvicorn

Giờ đây, nếu quá trình triển khai của bạn đã hoàn tất, vui lòng thử tương tác với tác nhân từ giao diện người dùng dành cho nhà phát triển trên web bằng cách truy cập vào URL Cloud Run

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. Trong phần trước, chúng ta đã đặt mức độ đồng thời tối đa là 10 ( cờ --concurrency 10). Do đó, chúng ta có thể dự kiến Cloud Run sẽ cố gắng mở rộng quy mô phiên bản khi chúng ta thực hiện kiểm thử tải vượt quá con số này.

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 từng bước 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ý. Mở weather_agent/agent.py rồi ghi đè bằng đoạn mã sau:

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

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.

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

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

...

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

...

app: FastAPI = get_fast_api_app(**app_args)

...

Ở đây, chúng ta truyền đối số trace_to_cloud thành True. Nếu đang triển khai bằng các lựa chọn khác, bạn có thể xem tài liệu này để biết thêm thông tin về cách bật tính năng theo dõi cho Cloud Trace từ nhiều lựa chọn triển khai

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

Vậy là xong. Giờ đây, 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á.