Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Phân tích quá trình thực thi ADK Agent bằng BigQuery Agent Analytics Plugin

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ xây dựng một hệ thống đa tác nhân bằng Bộ công cụ phát triển tác nhân (ADK) và bật tính năng Quan sát tác nhân bằng Trình bổ trợ phân tích tác nhân BigQuery.Bạn sẽ đặt cho tác nhân một loạt câu hỏi, sau đó sử dụng BigQuery để phân tích dấu vết cuộc trò chuyện và mức sử dụng công cụ của tác nhân.

Bạn sẽ thực hiện

Tạo một trợ lý bán lẻ đa tác nhân bằng ADK
Khởi động Trình bổ trợ Phân tích tác nhân BigQuery để thu thập và lưu trữ dữ liệu theo dõi về quá trình thực thi của tác nhân này vào BigQuery
Phân tích dữ liệu nhật ký của đặc vụ trong BigQuery

Bạn cần có

Một trình duyệt web như Chrome
Một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán, hoặc
Tài khoản Gmail. Phần tiếp theo sẽ hướng dẫn bạn cách sử dụng khoản tín dụng miễn phí trị giá 5 USD cho lớp học lập trình này và thiết lập một dự án mới

Lớp học lập trình này dành cho nhà phát triển ở mọi cấp độ, kể cả người mới bắt đầu. Bạn sẽ sử dụng giao diện dòng lệnh trong Google Cloud Shell và mã Python để phát triển ADK. Bạn không cần phải là chuyên gia về Python, nhưng kiến thức cơ bản về cách đọc mã sẽ giúp bạn hiểu các khái niệm.

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

Tạo một dự án trên Google Cloud

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

Khởi động Cloud Shell

Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết.

Nhấp vào Kích hoạt Cloud Shell ở đầu Cloud Console:

Sau khi kết nối với Cloud Shell, hãy chạy lệnh này để xác minh quá trình xác thực của bạn trong Cloud Shell:

gcloud auth list

Chạy lệnh sau để xác nhận rằng dự án của bạn đã được định cấu hình để sử dụng với gcloud:

gcloud config get project

Nếu dự án của bạn không được định cấu hình như mong đợi, hãy dùng lệnh sau để thiết lập dự án:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Bật API

Chạy lệnh này để bật tất cả các API và dịch vụ bắt buộc:

gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.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:

Thao tác "operations/..." đã hoàn tất thành công.

3. Cài đặt và thiết lập

Quay lại Cloud Shell và đảm bảo bạn đang ở trong thư mục chính.

Chạy lệnh sau trong Cloud Shell để tạo một tập dữ liệu mới có tên là adk_logs trong BigQuery:

bq mk --dataset --location=US adk_logs

Bây giờ, hãy tạo một môi trường Python ảo và cài đặt các gói cần thiết.

Mở một thẻ terminal mới trong Cloud Shell rồi chạy lệnh này để tạo và chuyển đến một thư mục có tên adk-agent-observability:

mkdir adk-agent-observability
cd adk-agent-observability

Tạo môi trường Python ảo:

python -m venv .venv

Kích hoạt môi trường ảo:

source .venv/bin/activate

Cài đặt ADK:

pip install --upgrade google-adk

4. Tạo ứng dụng ADK

Bây giờ, hãy tạo Tác nhân trợ lý bán lẻ. Trợ lý này sẽ được thiết kế để ...

Chạy lệnh tiện ích adk create để tạo khung cho một ứng dụng tác nhân mới có các thư mục và tệp cần thiết:

adk create retail_assistant_app

Làm theo lời nhắc:

Chọn gemini-2.5-flash cho mô hình.
Chọn Vertex AI cho phần phụ trợ.
Xác nhận mã dự án và khu vực mặc định của Google Cloud.

Dưới đây là một ví dụ về lượt tương tác:

Nhấp vào nút Open Editor (Mở trình chỉnh sửa) trong Cloud Shell để mở Cloud Shell Editor và xem các thư mục cũng như tệp mới tạo:

Lưu ý các tệp được tạo:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env

init.py: Đánh dấu thư mục là một mô-đun Python.
agent.py: Chứa định nghĩa ban đầu về tác nhân.
.env: Bạn có thể phải nhấp vào View > Toggle Hidden Files (Xem > Chuyển đổi tệp ẩn) để xem tệp này

Tệp .env chứa các biến môi trường cho dự án của bạn, hãy cập nhật mọi biến chưa được đặt chính xác từ các lời nhắc:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Xác định tác nhân

Bây giờ, hãy xác định một hệ thống đa tác nhân phân cấp.

Tác nhân xu hướng theo thời gian thực: Sử dụng Google Tìm kiếm để tìm các xu hướng thời trang hiện tại.
Inventory Data Agent: Sử dụng Bộ công cụ BigQuery để truy vấn tập dữ liệu công khai thelook_ecommerce về các sản phẩm hiện có.
Tác nhân trợ lý bán lẻ (Root): Điều phối quy trình công việc bằng cách hỏi ý kiến của Tác nhân xu hướng và Tác nhân kho hàng để tìm sản phẩm phù hợp.

Thay thế toàn bộ nội dung của retail_assistant_app/agent.py bằng mã sau.

import os
import uuid
import asyncio
import google.auth
import dotenv
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(
 credentials_config=credentials_config
)

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-2.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-2.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'
  
   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-2.5-flash",   
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.   
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. Tạo nhật ký bằng Trình bổ trợ Phân tích tác nhân BigQuery

Bây giờ, hãy định cấu hình Trình bổ trợ Phân tích tác nhân BigQuery để thu thập dữ liệu thực thi.

Để thực hiện việc này, bạn sẽ tạo một phiên bản của lớp App. Lớp này đóng vai trò là vùng chứa thời gian chạy cho tác nhân của bạn; lớp này quản lý vòng lặp trò chuyện, xử lý trạng thái người dùng và điều phối mọi trình bổ trợ được đính kèm (chẳng hạn như trình ghi nhật ký phân tích tác nhân của chúng tôi).

Mã bên dưới:

Khởi động Trình bổ trợ ghi nhật ký: Tạo BigQueryAgentAnalyticsPlugin bằng các thông tin kết nối bắt buộc.
Tích hợp trình bổ trợ: Truyền trình bổ trợ BigQuery đã khởi tạo vào hàm khởi tạo App, đảm bảo rằng các sự kiện thực thi tác nhân được tự động ghi lại và đăng nhập.
Chạy và ghi nhật ký quá trình thực thi của tác nhân: Thực thi quy trình trò chuyện thông qua runner.run_async, đồng thời trình bổ trợ sẽ thu thập và gửi toàn bộ chuỗi sự kiện đến BigQuery trước khi đóng các tài nguyên của trình bổ trợ.

Sao chép và dán mã này bên dưới các định nghĩa về tác nhân trong tệp agent.py:

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )
    app = App(name=APP_NAME, root_agent=root_agent, plugins=[bq_logger_plugin])
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        my_session =