Menganalisis eksekusi Agen ADK dengan Plugin Analisis Agen BigQuery

1. Pengantar

Dalam codelab ini, Anda akan membangun sistem multi-agen menggunakan Agent Development Kit (ADK) dan mengaktifkan Kemampuan Observasi Agen menggunakan Plugin Analisis Agen BigQuery.Anda akan mengajukan serangkaian pertanyaan kepada agen, lalu menggunakan BigQuery untuk menganalisis jejak percakapan dan penggunaan alat agen.

c8d3754ee87af43f.png

Yang akan Anda lakukan

  • Membangun asisten retail multi-agen menggunakan ADK
  • Lakukan inisialisasi Plugin Analisis BigQuery Agent untuk merekam dan menyimpan data rekaman aktivitas tentang eksekusi agen ini ke BigQuery
  • Menganalisis data log agen di BigQuery

Yang Anda butuhkan

  • Browser web seperti Chrome
  • Project Google Cloud yang mengaktifkan penagihan, atau
  • Akun Gmail. Bagian berikutnya akan menunjukkan cara menukarkan kredit gratis $5 untuk codelab ini dan menyiapkan project baru

Codelab ini ditujukan bagi developer dari semua level, termasuk para pemula. Anda akan menggunakan antarmuka command line di Google Cloud Shell dan kode Python untuk pengembangan ADK. Anda tidak perlu menjadi pakar Python, tetapi pemahaman dasar tentang cara membaca kode akan membantu Anda memahami konsepnya.

2. Sebelum memulai

Buat Project Google Cloud

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.

c745d833b0ed52b0.png

  1. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

  1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud:

404e4cce0f23e5c5.png

  1. Setelah terhubung ke Cloud Shell, jalankan perintah ini untuk memverifikasi autentikasi Anda di Cloud Shell:
gcloud auth list
  1. Jalankan perintah berikut untuk mengonfirmasi bahwa project Anda dikonfigurasi untuk digunakan dengan gcloud:
gcloud config get project
  1. Jika project Anda tidak dikonfigurasi seperti yang diharapkan, gunakan perintah berikut untuk menyetel project Anda:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Mengaktifkan API

  1. Jalankan perintah ini untuk mengaktifkan semua API dan layanan yang diperlukan:
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. Jika perintah berhasil dieksekusi, Anda akan melihat pesan yang mirip dengan yang ditampilkan di bawah:

Operation "operations/..." finished successfully.

3. Penginstalan & Penyiapan

Kembali ke Cloud Shell dan pastikan Anda berada di direktori beranda.

Jalankan perintah berikut di Cloud Shell untuk membuat set data baru bernama adk_logs di BigQuery:

bq mk --dataset --location=US adk_logs

Sekarang, mari buat lingkungan Python virtual dan instal paket yang diperlukan.

  1. Buka tab terminal baru di Cloud Shell dan jalankan perintah ini untuk membuat dan membuka folder bernama adk-agent-observability:
mkdir adk-agent-observability
cd adk-agent-observability
  1. Buat lingkungan Python virtual:
python -m venv .venv
  1. Aktifkan lingkungan virtual:
source .venv/bin/activate
  1. Instal ADK:
pip install --upgrade google-adk

4. Membuat aplikasi ADK

Sekarang, mari kita buat Agen asisten retail. Agen ini akan dirancang untuk ...

  1. Jalankan perintah utilitas pembuatan ADK untuk membuat struktur aplikasi agen baru dengan folder dan file yang diperlukan:
adk create retail_assistant_app

Ikuti petunjuknya:

  1. Pilih gemini-2.5-flash untuk model.
  2. Pilih Vertex AI untuk backend.
  3. Konfirmasi ID Project Google Cloud dan region default Anda.

Contoh interaksi ditampilkan di bawah:

acc9c6bb436f7025.png

  1. Klik tombol Open Editor di Cloud Shell untuk membuka Cloud Shell Editor dan melihat folder serta file yang baru dibuat:

a940b7eaf3c9f4b3.png

Perhatikan file yang dihasilkan:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py: Menandai folder sebagai modul Python.
  • agent.py: Berisi definisi agen awal.
  • .env: Anda mungkin perlu mengklik View > Toggle Hidden Files untuk melihat file ini

16a1a92b33f78e6b.png

  • File .env berisi variabel lingkungan untuk project Anda. Perbarui variabel yang tidak ditetapkan dengan benar dari perintah:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Tentukan agen Anda

Sekarang mari kita definisikan sistem multi-agen hierarkis.

  1. Agen Tren Real Time: Menggunakan Google Penelusuran untuk menemukan tren mode saat ini.
  2. Agen Data Inventaris: Menggunakan Toolset BigQuery untuk membuat kueri set data publik thelook_ecommerce untuk produk yang tersedia.
  3. Agen Asisten Retail (Root): Mengatur alur kerja dengan meminta saran dari Agen Tren dan produk yang cocok dari Agen Inventaris.

Ganti seluruh konten retail_assistant_app/agent.py dengan kode berikut.

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. Membuat log dengan Plugin Analisis Agen BigQuery

Sekarang, mari kita konfigurasi BigQuery Agent Analytics Plugin untuk merekam data eksekusi.

Untuk melakukannya, Anda akan membuat instance class App. Class ini berfungsi sebagai penampung runtime untuk agen Anda; class ini mengelola loop percakapan, menangani status pengguna, dan mengatur plugin terlampir (seperti logger analisis agen kami).

Kode di bawah:

  • Menginisialisasi Plugin Logging: Membuat BigQueryAgentAnalyticsPlugin dengan detail koneksi yang diperlukan.
  • Mengintegrasikan Plugin: Meneruskan plugin BigQuery yang diinisialisasi ke konstruktor App, sehingga memastikan bahwa peristiwa eksekusi agen otomatis diambil dan dicatat.
  • Menjalankan dan Mencatat Eksekusi Agen: Menjalankan alur percakapan melalui runner.run_async, dengan plugin secara bersamaan mengumpulkan dan mengirimkan seluruh urutan peristiwa ke BigQuery sebelum menutup sumber dayanya.

Salin dan tempel kode ini di bawah definisi agen dalam file 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))

Setelah instrumentasi diterapkan, saatnya melihat cara kerja agen. Jalankan skrip untuk memicu alur kerja percakapan.

python retail_assistant_app/agent.py

Anda akan melihat asisten retail mengatur alur kerja:

  1. Tindakan ini meminta Agen Tren Real Time (real_time_agent) untuk mengidentifikasi cuaca di London dan menelusuri tren mode yang sesuai.
  2. Kemudian, API ini akan mendelegasikan ke Inventory Data Agent (inventory_data_agent) untuk membuat kueri set data BigQuery thelook_ecommerce untuk produk tertentu yang cocok dengan tren tersebut.
  3. Terakhir, Root Orchestrator menyintesis hasil menjadi rekomendasi akhir.

Selama itu, plugin melakukan streaming rekaman aktivitas eksekusi agen ke BigQuery.

7. Menganalisis Log Agen

Penggunaan Alat

Sekarang kita dapat melihat apa yang dilakukan agen kita di balik layar. Data telah di-streaming ke BigQuery dan siap dianalisis:

  1. Di Konsol Google Cloud, telusuri BigQuery.
  2. Di panel Explorer, cari project Anda.
  3. Luaskan set data adk_logs.
  4. Buka tabel retail_assitant_agent_logs, lalu klik Query.

a2de3b52da21855f.png

Untuk melihat panggilan alat yang dilakukan agen Anda, dan mencatat error alat apa pun, jalankan kueri berikut di Editor 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

Klik Visualisasi untuk melihatnya sebagai diagram:

2e8d009e3e0459ed.png

Penggunaan Token

Untuk menyimpulkan biaya agen, Anda dapat menggabungkan token perintah dan token kandidat yang digunakan oleh setiap agen yang berbeda:

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

Klik Visualisasi untuk melihatnya sebagai diagram:

134dc090ba55372d.png

8. [Bonus] Menganalisis Sentimen Pengguna

Sekarang, mari kita analisis sentimen input pengguna yang diberikan kepada agen.

  1. Buat koneksi resource cloud agar BigQuery dapat berinteraksi dengan layanan Vertex AI:
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Anda akan melihat respons seperti:

Connection 517325854360.us.test_connection berhasil dibuat

  1. Membuat koneksi resource cloud:
export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)
  1. Jalankan perintah ini untuk memvalidasi bahwa akun layanan berhasil dibuat:
echo $SERVICE_ACCOUNT_EMAIL

Anda akan melihat akun layanan Anda ditampilkan:

c4a155d9d005e3d8.jpeg

  1. Beri akun layanan koneksi resource izin tingkat project yang diperlukan untuk berinteraksi dengan 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'

Tunggu beberapa menit, lalu jalankan fungsi AI.SCORE BigQuery untuk menganalisis sentimen pengguna:

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;

Fungsi AI.SCORE akan menetapkan nilai sentimen antara 1 dan 5 untuk setiap input pengguna. Anda akan melihat hasil seperti di bawah ini: 4e345b703b86cde8.jpeg

9. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama workshop ini.

Hapus set data logging yang dibuat oleh skrip:

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

Untuk menghapus direktori bigquery-adk-codelab dan isinya:

cd .. 
rm -rf adk-agent-observability

10. Selamat

Selamat! Anda telah membangun sistem multi-agen dengan Agent Development Kit (ADK) dan berhasil mengintegrasikan Plugin Analisis Agen BigQuery untuk melacak dan mengaudit perilaku agen Anda.

Dokumen referensi