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 nhiều 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 Khả năng ghi nhận tác nhân bằng Trình bổ trợ phân tích tác nhân BigQuery.Bạn sẽ hỏi 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

Xây dựng một trợ lý bán lẻ đa tác nhân bằng ADK
Khởi chạy Trình bổ trợ phân tích tác nhân BigQuery để thu thập và lưu trữ dữ liệu dấu vết 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 tác nhân 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
Một tài khoản Gmail. Phần tiếp theo sẽ hướng dẫn bạn cách đổi 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 các 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 việc hiểu biết cơ bản về cách đọc mã sẽ giúp bạn nắm bắt 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 bộ 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 bật cho một dự án hay chưa.

Bắt đầu 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 bảng điều khiển Cloud:

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 sử dụng lệnh sau để đặt 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:

Operation "operations/..." finished successfully.

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 bắt buộc.

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

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

Tạo một 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ẻ. Tác nhân này sẽ được thiết kế để ...

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

adk create retail_assistant_app

Làm theo yêu cầu đó:

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.

Sau đây là ví dụ minh hoạ về một lượt tương tác:

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

Lưu ý các tệp đã 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 tác nhân ban đầu.
.env: Bạn có thể cần 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 không đượ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 nhiều tác nhân theo thứ bậc.

Real Time Trend Agent (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 (Tác nhân dữ liệu hàng tồn kho): 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 có sẵn.
Retail assistant (Root) Agent (Tác nhân trợ lý bán lẻ (Gốc)): Điều phối quy trình làm việc bằng cách yêu cầu Trend Agent (Tác nhân xu hướng) tư vấn và Inventory Agent (Tác nhân hàng tồn kho) tìm các 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 thực thể 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 cuộc 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 (như trình ghi nhật ký phân tích tác nhân của chúng tôi).

Mã dưới đây:

Khởi chạy Trình bổ trợ ghi nhật ký: Tạo BigQueryAgentAnalyticsPlugin với 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 chạy 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 thu thập và ghi nhật ký.
Chạy và ghi nhật ký quá trình thực thi tác nhân: Thực thi quy trình đàm thoại thông qua runner.run_async, đồng thời trình bổ trợ thu thập và gửi toàn bộ chuỗi sự kiện đến BigQuery trước khi đóng 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 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 = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

async def run_all_prompts():
    """Runs all prompts in a single event loop."""
    prompts = [
        "what outfits do you have available that are suitable for the weather in london this week?",
        "You are such a cool agent! I need a gift idea for my friend who likes yoga.",
        "I'd like to complain - the products sold here are not very good quality!"
    ]
    for prompt in prompts:
        await main(prompt)

if __name__ == "__main__":
    asyncio.run(run_all_prompts())

Sau khi thiết lập khả năng đo lường, đã đến lúc xem tác nhân hoạt động. Chạy tập lệnh để kích hoạt quy trình làm việc của cuộc trò chuyện.

python retail_assistant_app/agent.py

Bạn sẽ thấy trợ lý bán lẻ điều phối quy trình làm việc:

Trợ lý này yêu cầu Real Time Trend Agent (Tác nhân xu hướng theo thời gian thực) (real_time_agent) xác định thời tiết ở London và tìm kiếm các xu hướng thời trang phù hợp.
Sau đó, trợ lý này uỷ quyền cho Inventory Data Agent (Tác nhân dữ liệu hàng tồn kho) (inventory_data_agent) truy vấn tập dữ liệu thelook_ecommerce BigQuery để tìm một số sản phẩm phù hợp với những xu hướng đó.
Cuối cùng, Root Orchestrator (Trình điều phối gốc) tổng hợp kết quả thành một đề xuất cuối cùng.

Trong suốt quá trình này, trình bổ trợ sẽ truyền trực tiếp dấu vết thực thi của tác nhân đến BigQuery.

7. Phân tích nhật ký tác nhân

Mức sử dụng công cụ

Giờ đây, chúng ta có thể thấy tác nhân của mình đang làm gì ở hậu trường! Dữ liệu đã được truyền trực tiếp đến BigQuery và sẵn sàng để phân tích:

Trong Google Cloud Console, hãy tìm kiếm BigQuery.
Trong ngăn Explorer (Trình khám phá), hãy tìm dự án của bạn.
Mở rộng tập dữ liệu adk_logs.
Mở bảng retail_assitant_agent_logs rồi nhấp vào Query (Truy vấn).

Để xem các lệnh gọi công cụ mà tác nhân của bạn đã thực hiện và thu thập mọi lỗi công cụ, hãy chạy truy vấn sau trong Trình chỉnh sửa BigQuery:

SELECT
  -- Extract the tool name directly from the JSON key "tool"
  JSON_VALUE(content, '$.tool') AS tool_name,
  -- Count every time a tool finished (successfully or with an error)
  COUNT(*) AS total_finished_runs,
  -- Count as a failure if  event_type is ERROR, result object contains a status of 'ERROR', or error_details exist
  COUNTIF(
    event_type = 'TOOL_ERROR' OR
    JSON_VALUE(content, '$.result.status') = 'ERROR' OR
    JSON_VALUE(content, '$.result.error_details') IS NOT NULL
  ) AS failure_count
FROM
  `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
  1;

Nhấp vào Visualization (Hình ảnh trực quan) để xem kết quả này dưới dạng biểu đồ (kết quả của bạn có thể khác):

Số token đã dùng

Để suy ra chi phí của tác nhân, bạn có thể tổng hợp các token lời nhắc và token ứng viên do từng tác nhân riêng biệt sử dụng:

SELECT
 t.agent,
 SUM(LAX_INT64(t.content.usage.prompt)) AS prompt_tokens,
 SUM(LAX_INT64(t.content.usage.completion)) AS completion_tokens
FROM
 `adk_logs.retail_assistant_agent_logs` AS t
WHERE
 t.event_type = 'LLM_RESPONSE'
 -- Filter for records that actually contain usage metadata
 AND t.content.usage IS NOT NULL
GROUP BY 1;

Nhấp vào Visualization (Hình ảnh trực quan) để xem kết quả này dưới dạng biểu đồ (kết quả của bạn có thể khác):

8. [Thưởng] Phân tích cảm tính của người dùng

Bây giờ, hãy phân tích cảm tính của dữ liệu đầu vào do người dùng cung cấp cho tác nhân.

Trong Cloud Shell, hãy tạo một kết nối tài nguyên đám mây để cho phép BigQuery tương tác với các dịch vụ Vertex AI:

bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Bạn sẽ thấy một phản hồi như sau:

Connection 517325854360.us.test_connection successfully created

Tạo kết nối tài nguyên đám mây:

export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)

Chạy lệnh này để xác thực rằng tài khoản dịch vụ đã được tạo thành công:

echo $SERVICE_ACCOUNT_EMAIL

Bạn sẽ thấy tài khoản dịch vụ của mình:

Cấp cho tài khoản dịch vụ kết nối tài nguyên các quyền ở cấp dự án cần thiết để tương tác với Vertex AI:

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' && \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

Chờ vài phút để các quyền được áp dụng. Sau đó, quay lại BigQuery và chạy truy vấn sau có chứa hàm AI.SCORE để phân tích cảm tính của người dùng:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', JSON_VALUE(content.text_summary),
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

Hàm AI.SCORE sẽ gán một giá trị cảm tính từ 1 đến 5 cho mỗi hoạt động đầu vào của người dùng. Bạn sẽ thấy kết quả tương tự như sau:

9. Dọn dẹp

Để tránh bị tính phí liên tục vào tài khoản Google Cloud, hãy xoá các tài nguyên được tạo trong hội thảo này.

Xoá tập dữ liệu ghi nhật ký do tập lệnh tạo:

bq rm -r -f -d $PROJECT_ID:adk_logs

Xoá kết nối tài nguyên đám mây:

bq rm --connection --project_id=$PROJECT_ID --location=us test_connection

Cách xoá thư mục bigquery-adk-codelab và nội dung của thư mục đó:

cd .. 
rm -rf adk-agent-observability

10. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng một hệ thống nhiều tác nhân bằng Bộ công cụ phát triển tác nhân (ADK) và tích hợp thành công Trình bổ trợ phân tích tác nhân BigQuery để theo dõi và kiểm tra hành vi của tác nhân.