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 çok temsilcili 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 projeyi nasıl oluşturacağınız gösterilmektedir.

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. Faturalandırmanın bir projede 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'deki 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ı onaylamak 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.

Aşağıda örnek bir etkileşim 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üğ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. Temsilcinizi 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 öğesini 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ırmalar 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.")

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

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 hangi araç çağrılarını yaptığını görmek ve araç hatalarını yakalamak için BigQuery Düzenleyici'de aşağıdaki sorguyu çalıştırın:

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

Bunu grafik olarak görüntülemek için Görselleştirme'yi tıklayın:

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

Bunu grafik olarak görüntülemek için Görselleştirme'yi tıklayın:

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

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

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

Birkaç dakika bekleyin ve ardından kullanıcı duyarlılığını analiz etmek için BigQuery AI.SCORE işlevini çalıştırın:

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;

AI.SCORE işlevi, her kullanıcı girişi için 1 ile 5 arasında bir duygu değeri atar. Aşağıdaki gibi 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

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 çoklu aracı sistemi oluşturdunuz ve aracınızın davranışını izlemek ve denetlemek için BigQuery Agent Analytics Plugin'i başarıyla entegre ettiniz.

Referans belgeleri

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