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

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ẽ tạo một hệ thống nhiều tác nhân bằng cách sử dụng Bộ công cụ phát triển tác nhân (ADK) và bật tính năng Khả năng quan sát tác nhân bằng cách sử dụ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 của 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ợ Analytics của BigQuery Agent để 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 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 bảng điều khiển Google 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 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 một Agent trợ lý bán lẻ. Nhân viên hỗ trợ 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 nhân viên hỗ trợ

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

Real Time Trend Agent (Trợ lý 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 kho hàng): 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 thiết lập Trình bổ trợ Analytics của BigQuery Agent để 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 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 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 mình.

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 = 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.")

if __name__ == "__main__":
   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, prompt in enumerate(prompts):
       asyncio.run(main(prompt))

Sau khi thiết lập tính 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 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:

Công cụ này yêu cầu Real Time Trend Agent (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 đó, công cụ này uỷ quyền cho Tác nhân dữ liệu kho hàng (inventory_data_agent) để truy vấn tập dữ liệu thelook_ecommerce BigQuery cho những sản phẩm cụ thể phù hợp với các xu hướng đó.
Cuối cùng, Root Orchestrator tổng hợp các 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 tuyến dấu vết thực thi của tác nhân đến BigQuery.

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

Cách sử dụng công cụ

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

Trong Google Cloud Console, hãy tì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 Truy vấn.

Để xem những lệnh gọi công cụ mà tác nhân của bạn đã thực hiện và ghi lại 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 text between "Tool Name: " and the next comma (or end of line)
   REGEXP_EXTRACT(content, r'Tool Name: ([^,]+)') AS tool_name,
   -- Count every time a tool finished (successfully or with an error)
   COUNT(*) AS total_finished_runs,
   -- Count it as a failure if it's an explicit system error OR contains "error" in the text
   COUNTIF(event_type = 'TOOL_ERROR' OR REGEXP_CONTAINS(content, r'(?i)\berror\b')) 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 Hình ảnh trực quan để xem dữ liệu này dưới dạng biểu đồ:

Số token đã dùng

Để suy ra chi phí của các tác nhân, bạn có thể tổng hợp các mã thông báo của câu lệnh và mã thông báo của đề xuất mà mỗi tác nhân riêng biệt sử dụng:

SELECT
     t.agent,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'prompt:\s*(\d+)') AS INT64)) AS prompt_tokens,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'candidates:\s*(\d+)') AS INT64)) AS candidate_tokens
   FROM
     `adk_logs.retail_assistant_agent_logs` AS t
   WHERE
     t.event_type = 'LLM_RESPONSE'
     AND t.content LIKE '%Token Usage: %'
   GROUP BY 1

Nhấp vào Hình ảnh trực quan để xem dữ liệu này dưới dạng biểu đồ:

8. [Phần thưởng] Phân tích ý kiến của người dùng

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

Tạo một mối kết nối tài nguyên trên đám mây để cho phép BigQuery tương tác với các dịch vụ của 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:

Đã tạo thành công kết nối 517325854360.us.test_connection

Tạo mối kết nối tài nguyên trê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 xuất hiện:

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'

Đợi vài phút rồi chạy hàm AI.SCORE của BigQuery để phân tích cảm xúc của người dùng:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', content,
   '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ẽ chỉ định một giá trị cảm xúc từ 1 đến 5 cho mỗi dữ liệu đầu vào của người dùng. Bạn sẽ thấy kết quả như bên dưới:

9. Dọn dẹp

Để tránh các khoản phí phát sinh cho tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã 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

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

cd .. 
rm -rf adk-agent-observability

10. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo một hệ thống đa tác nhân bằng Agent Development Kit (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.