ניתוח של ביצוע סוכן ADK באמצעות התוסף BigQuery Agent Analytics

1. מבוא

בשיעור Codelab הזה נסביר איך ליצור מערכת מרובת סוכנים באמצעות ערכה לפיתוח סוכנים (ADK), ואיך להפעיל את יכולת הניראות (observability) של הסוכן באמצעות BigQuery Agent Analytics Plugin.תשאלו את הסוכן סדרה של שאלות, ואז תשתמשו ב-BigQuery כדי לנתח את עקבות השיחות ואת השימוש בכלי הסוכן.

מה עושים

יצירת עוזר מרובה סוכנים למוצרים קמעונאיים באמצעות ADK
מפעילים את BigQuery Agent Analytics Plugin כדי לתעד ולאחסן ב-BigQuery נתוני מעקב על ההרצה של הסוכן הזה
ניתוח נתוני יומן הסוכן ב-BigQuery

מה תצטרכו

דפדפן אינטרנט כמו Chrome
פרויקט בענן של Google שהחיוב בו מופעל, או
חשבון Gmail. בקטע הבא נסביר איך לממש קרדיט חינמי בסך 5 $לשימוש ב-codelab הזה ולהגדיר פרויקט חדש.

שיעור ה-Codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים. תשתמשו בממשק שורת הפקודה ב-Google Cloud Shell ובקוד Python לפיתוח ADK. לא צריך להיות מומחה ל-Python, אבל הבנה בסיסית של קריאת קוד תעזור לכם להבין את המושגים.

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.

הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

מפעילים את Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud, וכוללת מראש את הכלים הדרושים.

לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) בחלק העליון של מסוף Google Cloud:

אחרי שמתחברים ל-Cloud Shell, מריצים את הפקודה הבאה כדי לאמת את האימות ב-Cloud Shell:

gcloud auth list

מריצים את הפקודה הבאה כדי לוודא שהפרויקט מוגדר לשימוש ב-gcloud:

gcloud config get project

אם הפרויקט לא מוגדר כמו שציפיתם, מריצים את הפקודה הבאה כדי להגדיר את הפרויקט:

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

הפעלת ממשקי ה-API

מריצים את הפקודה הזו כדי להפעיל את כל ממשקי ה-API והשירותים הנדרשים:

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

אם הפקודה תפעל בהצלחה, תוצג הודעה שדומה לזו שמופיעה בהמשך:

הפעולה 'operations/...' הסתיימה בהצלחה.

3. התקנה והגדרה

חוזרים ל-Cloud Shell ומוודאים שאתם בספריית הבית.

כדי ליצור מערך נתונים חדש בשם adk_logs ב-BigQuery, מריצים את הפקודה הבאה ב-Cloud Shell:

bq mk --dataset --location=US adk_logs

עכשיו ניצור סביבה וירטואלית של Python ונתקין את החבילות הנדרשות.

פותחים כרטיסייה חדשה בטרמינל ב-Cloud Shell ומריצים את הפקודה הבאה כדי ליצור תיקייה בשם adk-agent-observability ולעבור אליה:

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

יוצרים סביבת Python וירטואלית:

python -m venv .venv

מפעילים את הסביבה הווירטואלית:

source .venv/bin/activate

מתקינים את ADK:

pip install --upgrade google-adk

4. יצירת אפליקציית ADK

עכשיו ניצור סוכן שישמש כעוזר קמעונאי. הנציג הזה יתוכנן כדי ...

מריצים את פקודת כלי השירות adk create כדי ליצור סביבה לפיתוח אפליקציית סוכן חדשה עם התיקיות והקבצים הנדרשים:

adk create retail_assistant_app

פועלים לפי ההנחיות:

בוחרים את המודל gemini-2.5-flash.
בוחרים באפשרות Vertex AI עבור ה-Backend.
מאשרים את מזהה הפרויקט ב-Google Cloud ואת האזור שמוגדרים כברירת מחדל.

דוגמה לאינטראקציה:

לוחצים על הלחצן Open Editor (פתיחת העורך) ב-Cloud Shell כדי לפתוח את Cloud Shell Editor ולראות את התיקיות והקבצים החדשים שנוצרו:

שימו לב לקבצים שנוצרו:

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

‫init.py: סימון התיקייה כמודול Python.
‫agent.py: מכיל את ההגדרה הראשונית של הסוכן.
‫.env: יכול להיות שתצטרכו ללחוץ על 'תצוגה' > 'החלפת מצב של קבצים מוסתרים' כדי לראות את הקובץ הזה

קובץ ‎.env מכיל משתני סביבה לפרויקט. צריך לעדכן את כל המשתנים שלא הוגדרו בצורה נכונה בהנחיות:

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

5. הגדרת הנציג

עכשיו נגדיר מערכת היררכית מרובת סוכנים.

סוכן מגמות בזמן אמת: משתמש בחיפוש Google כדי למצוא מגמות אופנה עדכניות.
‫Inventory Data Agent: משתמש בערכת הכלים של BigQuery כדי להריץ שאילתות במערך הנתונים הציבורי thelook_ecommerce ולחפש מוצרים זמינים.
סוכן (בסיס) של עוזר קמעונאי: מתאם את תהליך העבודה על ידי בקשת ייעוץ מסוכן המגמות ומוצרים תואמים מסוכן המלאי.

מחליפים את כל התוכן של retail_assistant_app/agent.py בקוד הבא.

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 Plugin

עכשיו נגדיר את BigQuery Agent Analytics Plugin כדי לתעד נתוני הרצה.

כדי לעשות את זה, יוצרים מופע של המחלקה App. המחלקות האלה משמשות כמאגר זמן הריצה של הסוכן. הן מנהלות את לולאת השיחה, מטפלות במצב המשתמש ומתאמות בין כל התוספים המצורפים (כמו כלי הרישום של ניתוח הנתונים של הסוכן).

הקוד הבא:

מפעיל את תוסף הרישום ביומן: יוצר את BigQueryAgentAnalyticsPlugin עם פרטי החיבור הנדרשים.
משלב את הפלאגין: מעביר את פלאגין BigQuery שאותחל אל ה-constructor‏ App, כדי להבטיח שאירועי ההרצה של הסוכן יתועדו באופן אוטומטי.
הרצה ורישום של ביצוע הסוכן: התוסף מריץ את זרימת השיחה באמצעות runner.run_async, ובמקביל אוסף ושולח את כל רצף האירועים ל-BigQuery לפני שהוא סוגר את המשאבים שלו.

מעתיקים את הקוד הבא ומדביקים אותו מתחת להגדרות של הסוכן בקובץ 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())

אחרי שמגדירים את האינסטרומנטציה, אפשר לראות את הסוכן בפעולה. מריצים את הסקריפט כדי להפעיל את תהליך העבודה של השיחה.

python retail_assistant_app/agent.py

אמור להופיע עוזר קמעונאי שמנהל את תהליך העבודה:

היא מבקשת מהסוכן לזיהוי מגמות בזמן אמת (real_time_agent) לזהות את מזג האוויר בלונדון ולחפש מגמות אופנה מתאימות.
הוא מעביר את השאילתה אל הסוכן לנתוני מלאי (inventory_data_agent) כדי ליצור שאילתה במערך הנתונים thelook_ecommerce ב-BigQuery לגבי מוצרים ספציפיים שתואמים למגמות האלה.
לבסוף, המתזמן הראשי מסנתז את התוצאות להמלצה סופית.

במהלך התהליך, התוסף מעביר בסטרימינג את נתוני המעקב של הרצת הסוכן אל BigQuery.

7. ניתוח יומני הסוכן

שימוש בכלי

עכשיו אפשר לראות מה הסוכן עשה מאחורי הקלעים. הנתונים הועברו בסטרימינג ל-BigQuery ומוכנים לניתוח:

במסוף Google Cloud, מחפשים את BigQuery.
בחלונית Explorer, מאתרים את הפרויקט.
מרחיבים את מערך הנתונים adk_logs.
פותחים את הטבלה retail_assitant_agent_logs ולוחצים על שאילתה.

כדי לראות אילו קריאות לכלים הסוכן ביצע ולתעד שגיאות שקשורות לכלים, מריצים את השאילתה הבאה בעורך של 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;

לוחצים על 'תצוגה חזותית' כדי לראות את התוצאות בתרשים (התוצאות שלכם עשויות להיות שונות):

השימוש בטוקנים

כדי להסיק את העלות של הסוכנים, אפשר לצבור את טוקני ההנחיות ואת הטוקנים של המועמדים שנצרכו על ידי כל סוכן נפרד:

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;

לוחצים על 'תצוגה חזותית' כדי לראות את התוצאות בתרשים (התוצאות שלכם עשויות להיות שונות):

8. [בונוס] ניתוח סנטימנטים של משתמשים

עכשיו ננתח את הסנטימנט של הקלט שהמשתמש סיפק לסוכן.

ב-Cloud Shell, יוצרים קישור למשאבים ב-Cloud כדי לאפשר ל-BigQuery אינטראקציה עם שירותי Vertex AI:

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

אמורה להופיע תגובה כזו:

החיבור 517325854360.us.test_connection נוצר בהצלחה

יצירת קישור למשאבים ב-Cloud:

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

מריצים את הפקודה הבאה כדי לוודא שחשבון השירות נוצר בהצלחה:

echo $SERVICE_ACCOUNT_EMAIL

חשבון השירות אמור להופיע:

נותנים לחשבון השירות של חיבור המשאבים את ההרשאות ברמת הפרויקט שנדרשות לאינטראקציה עם 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'

מחכים כמה דקות עד שההרשאות יופצו. לאחר מכן חוזרים ל-BigQuery ומריצים את השאילתה הבאה שמכילה את הפונקציה AI.SCORE כדי לנתח את סנטימנט המשתמשים:

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 תקצה ערך סנטימנט בין 1 ל-5 לכל קלט של משתמשים. אמורות להתקבל תוצאות דומות לאלה:

9. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, מוחקים את המשאבים שנוצרו במהלך הסדנה הזו.

מוחקים את מערך הנתונים של הרישום ביומן שנוצר על ידי הסקריפט:

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

מחיקת הקישור למשאבים ב-Cloud:

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

כדי להסיר את הספרייה bigquery-adk-codelab ואת התוכן שלה:

cd .. 
rm -rf adk-agent-observability

10. מזל טוב

מעולה! יצרתם מערכת מרובת סוכנים באמצעות Agent Development Kit (ADK) ושילבתם בהצלחה את BigQuery Agent Analytics Plugin כדי לעקוב אחרי התנהגות הסוכן ולבדוק אותה.