דף זה תורגם על ידי Cloud Translation API.

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

1. מבוא

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

מה תעשו

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

מה תצטרכו

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

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

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

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

ב-Google Cloud Console, בדף לבחירת הפרויקט, בוחרים פרויקט ב-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 utility כדי ליצור סביבת עבודה לאפליקציית סוכן חדשה עם התיקיות והקבצים הנדרשים:

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

עכשיו נגדיר את תוסף BigQuery Agent Analytics כדי לתעד נתוני ביצוע.

כדי לעשות את זה, יוצרים מופע של המחלקה 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.")

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

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

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

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

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

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

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

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

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

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

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

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

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

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

יוצרים חיבור למשאב בענן:

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'

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

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

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

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

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

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

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

cd .. 
rm -rf adk-agent-observability

10. מזל טוב

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