BigQuery Agent Analytics eklentisiyle ADK aracısının yürütülmesini analiz etme

1. Giriş

Bu codelab'de, Agent Development Kit'i (ADK) kullanarak çoklu aracı sistemi oluşturacak ve BigQuery Agent Analytics Plugin'i kullanarak Agent Observability'yi etkinleştireceksiniz.Aracıya bir dizi soru soracak, ardından konuşma izlerini ve aracı aracının kullanımını analiz etmek için BigQuery'yi kullanacaksınız.

Yapacaklarınız

• ADK'yı kullanarak birden fazla temsilcinin yer aldığı bir perakende asistanı oluşturma
• Bu aracının yürütülmesiyle ilgili izleme verilerini BigQuery'de yakalayıp depolamak için BigQuery Agent Analytics Plugin'i başlatın.
• BigQuery'deki aracı günlük verilerini analiz etme

Gerekenler

• Chrome gibi bir web tarayıcısı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi veya
• Gmail hesabı Sonraki bölümde, bu codelab için ücretsiz 5 ABD doları tutarındaki krediyi nasıl kullanacağınız ve yeni bir proje oluşturacağınız gösterilecektir.

Bu codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştiriciye yöneliktir. ADK geliştirme için Google Cloud Shell'deki komut satırı arayüzünü ve Python kodunu kullanacaksınız. Python uzmanı olmanız gerekmez ancak kodu nasıl okuyacağınızla ilgili temel bilgiler, kavramları anlamanıza yardımcı olur.

2. Başlamadan önce

Google Cloud kredileri için: Başlamanıza yardımcı olmak için bu bağlantıyı kullanarak ücretsiz Google Cloud kredilerinizi kullanın. Krediyi etkinleştirip yeni bir proje oluşturmak için buradaki talimatları uygulayabilirsiniz.

Google Cloud projesi oluşturma

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.

2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın:

2. Cloud Shell'e bağlandıktan sonra Cloud Shell'de kimlik doğrulamanızı doğrulamak için şu komutu çalıştırın:

gcloud auth list

3. Projenizin gcloud ile kullanılacak şekilde yapılandırıldığını doğrulamak için aşağıdaki komutu çalıştırın:

gcloud config get project

4. Projeniz beklendiği gibi yapılandırılmamışsa projenizi ayarlamak için aşağıdaki komutu kullanın:

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

API'leri etkinleştir

1. Gerekli tüm API'leri ve hizmetleri etkinleştirmek için bu komutu çalıştırın:

gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com

2. Komut başarıyla yürütüldüğünde aşağıda gösterilene benzer bir mesaj görürsünüz:

"operations/..." işlemi başarıyla tamamlandı.

3. Yükleme ve Kurulum

Cloud Shell'e dönün ve ana dizininizde olduğunuzdan emin olun.

BigQuery'de adk_logs adlı yeni bir veri kümesi oluşturmak için Cloud Shell'de aşağıdaki komutu çalıştırın:

bq mk --dataset --location=US adk_logs

Şimdi sanal bir Python ortamı oluşturalım ve gerekli paketleri yükleyelim.

1. Cloud Shell'de yeni bir terminal sekmesi açın ve adk-agent-observability adlı bir klasör oluşturup bu klasöre gitmek için aşağıdaki komutu çalıştırın:

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

2. Sanal Python ortamı oluşturun:

python -m venv .venv

3. Sanal ortamı etkinleştirin:

source .venv/bin/activate

4. ADK'yı yükleyin:

pip install --upgrade google-adk

4. ADK uygulaması oluşturma

Şimdi perakende asistanı temsilcimizi oluşturalım. Bu temsilci, ... için tasarlanacak.

1. Gerekli klasör ve dosyaları içeren yeni bir aracı uygulaması oluşturmak için adk create utility command komutunu çalıştırın:

adk create retail_assistant_app

İstemleri uygulayın:

1. Model olarak gemini-2.5-flash'i seçin.
2. Arka uç için Vertex AI'ı seçin.
3. Varsayılan Google Cloud proje kimliğinizi ve bölgenizi onaylayın.

Örnek bir etkileşim aşağıda gösterilmektedir:

2. Cloud Shell Düzenleyici'yi açmak ve yeni oluşturulan klasörleri ve dosyaları görüntülemek için Cloud Shell'de Open Editor (Düzenleyiciyi Aç) düğmesini tıklayın:

Oluşturulan dosyaları not edin:

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

• init.py: Klasörü bir Python modülü olarak işaretler.
• agent.py: İlk aracı tanımını içerir.
• .env: Bu dosyayı görüntülemek için Görünüm > Gizli Dosyaları Aç/Kapat'ı tıklamanız gerekebilir.

• .env dosyası, projenizin ortam değişkenlerini içerir. İsteklerde doğru şekilde ayarlanmamış değişkenleri güncelleyin:

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

5. Aracınızı tanımlayın

Şimdi hiyerarşik bir çoklu temsilci sistemi tanımlayalım.

1. Anlık Trend Ajanı: Güncel moda trendlerini bulmak için Google Arama'yı kullanır.
2. Envanter Veri Aracısı: Kullanılabilir ürünler için herkese açık thelook_ecommerce veri kümesini sorgulamak üzere BigQuery araç setini kullanır.
3. Perakende asistanı (kök) temsilcisi: Trend temsilcisinden tavsiye ve envanter temsilcisinden eşleşen ürünler isteyerek iş akışını düzenler.

retail_assistant_app/agent.py dosyasının tüm içeriğini aşağıdaki kodla değiştirin.

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. BigQuery Agent Analytics eklentisiyle günlük oluşturma

Şimdi de yürütme verilerini yakalamak için BigQuery Agent Analytics Plugin'i yapılandıralım.

Bunun için App sınıfının bir örneğini oluşturursunuz. Bu sınıf, aracınızın çalışma zamanı kapsayıcısı olarak işlev görür. Görüşme döngüsünü yönetir, kullanıcı durumunu işler ve ekli eklentileri (ör. aracı analizleri kaydedicimiz) düzenler.

Aşağıdaki kod:

• Günlük Kaydı Eklentisini Başlatır: Gerekli bağlantı ayrıntılarını içeren BigQueryAgentAnalyticsPlugin oluşturur.
• Eklentiyi entegre eder: Başlatılan BigQuery eklentisini App oluşturucusuna ileterek aracı yürütme etkinliklerinin otomatik olarak yakalanmasını ve günlüğe kaydedilmesini sağlar.
• Çalıştırma ve Günlükler Aracı Yürütme: runner.run_async aracılığıyla sohbet akışını yürütür. Eklenti, kaynaklarını kapatmadan önce etkinliklerin tamamını aynı anda toplayıp BigQuery'ye gönderir.

Bu kodu kopyalayıp agent.py dosyasındaki aracı tanımlarının altına yapıştırın:

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

Enstrümantasyon tamamlandığına göre artık aracıyı çalışırken görme zamanı. Görüşme iş akışını tetiklemek için komut dosyasını çalıştırın.

python retail_assistant_app/agent.py

İş akışını düzenleyen perakende asistanını görürsünüz:

1. Real Time Trend Agent (real_time_agent)'tan Londra'daki hava durumunu belirlemesini ve uygun moda trendlerini aramasını ister.
2. Ardından, bu trendlere uyan belirli ürünler için thelook_ecommerce BigQuery veri kümesini sorgulamak üzere Envanter Veri Aracısı'na (inventory_data_agent) yetki verir.
3. Son olarak, Root Orchestrator sonuçları sentezleyerek nihai bir öneri oluşturur.

Bu sırada eklenti, aracının yürütme izini BigQuery'ye aktarıyor.

7. Aracı günlüklerini analiz etme

Araç Kullanımı

Artık temsilcimizin perde arkasında neler yaptığını görebiliyoruz. Veriler BigQuery'ye aktarıldı ve analiz edilmeye hazır:

1. Google Cloud Console'da BigQuery'yi arayın.
2. Gezgin bölmesinde projenizi bulun.
3. adk_logs veri kümesini genişletin.
4. retail_assitant_agent_logs tablosunu açıp Sorgu'yu tıklayın.

Temsilcinizin yaptığı araç çağrılarını görmek ve araç hatalarını yakalamak için BigQuery Düzenleyici'de aşağıdaki sorguyu çalıştırın:

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;

Sonuçları grafik olarak görüntülemek için Görselleştirme'yi tıklayın (sonuçlarınız farklı olabilir):

Jeton Kullanımı

Aracılarınızın maliyetini tahmin etmek için her bir farklı aracı tarafından kullanılan istem jetonlarını ve aday jetonlarını toplayabilirsiniz:

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;

Sonuçları grafik olarak görüntülemek için Görselleştirme'yi tıklayın (sonuçlarınız farklı olabilir):

8. [Bonus] Kullanıcı Duygularını Analiz Etme

Şimdi de kullanıcının temsilciye sağladığı girişin duygusunu analiz edelim.

1. Cloud Shell'de, BigQuery'nin Vertex AI hizmetleriyle etkileşim kurmasını sağlamak için bulut kaynağı bağlantısı oluşturun:

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

Şuna benzer bir yanıt görürsünüz:

Connection 517325854360.us.test_connection başarıyla oluşturuldu

2. Bulut kaynağı bağlantısı oluşturma:

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

3. Hizmet hesabının başarıyla oluşturulduğunu doğrulamak için bu komutu çalıştırın:

echo $SERVICE_ACCOUNT_EMAIL

Hizmet hesabınız gösterilir:

4. Kaynak bağlantısı hizmet hesabına Vertex AI ile etkileşim kurmak için gereken proje düzeyinde izinleri verin:

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'

İzinlerin uygulanması için birkaç dakika bekleyin. Ardından BigQuery'ye dönün ve kullanıcı duyarlılığını analiz etmek için AI.SCORE işlevini içeren aşağıdaki sorguyu çalıştırın:

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;

AI.SCORE işlevi, her kullanıcı girişi için 1 ile 5 arasında bir duygu değeri atar. Şuna benzer sonuçlar görmeniz gerekir:

9. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu atölye çalışması sırasında oluşturulan kaynakları silin.

Komut dosyası tarafından oluşturulan günlük kaydı veri kümesini silin:

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

Bulut kaynağı bağlantısını silin:

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

bigquery-adk-codelab dizinini ve içeriğini kaldırmak için:

cd .. 
rm -rf adk-agent-observability

10. Tebrikler

Tebrikler! Agent Development Kit (ADK) ile çok agent'lı bir sistem oluşturdunuz ve agent'ınızın davranışını izlemek ve denetlemek için BigQuery Agent Analytics Plugin'i başarıyla entegre ettiniz.

Referans belgeler

• ADK BigQuery Logging Plugin Documentation (ADK BigQuery Günlük Kaydı Eklentisi Belgeleri)
• BigQuery Logging Plugin İlgi Alanı Formu