این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اجرای ADK Agent را با افزونه BigQuery Agent Analytics تجزیه و تحلیل کنید

۱. مقدمه

در این آزمایشگاه کد، شما یک سیستم چندعاملی را با استفاده از کیت توسعه عامل (ADK) خواهید ساخت و قابلیت مشاهده عامل را با استفاده از افزونه BigQuery Agent Analytics فعال خواهید کرد . شما یک سری سؤال از عامل خواهید پرسید ، سپس از BigQuery برای تجزیه و تحلیل رد مکالمات و استفاده از ابزار عامل استفاده خواهید کرد.

کاری که انجام خواهید داد

ساخت یک دستیار خرده فروشی چند عاملی با استفاده از ADK
افزونه BigQuery Agent Analytics را برای ثبت و ذخیره داده‌های ردیابی مربوط به اجرای این عامل‌ها در BigQuery راه‌اندازی کنید.
تجزیه و تحلیل داده‌های لاگ عامل در BigQuery

آنچه نیاز دارید

یک مرورگر وب مانند کروم
یک پروژه Google Cloud با قابلیت پرداخت، یا
یک حساب جیمیل. بخش بعدی به شما نشان می‌دهد که چگونه می‌توانید اعتبار رایگان ۵ دلاری را برای این codelab بازخرید کنید و یک پروژه جدید راه‌اندازی کنید.

این آزمایشگاه کد برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است. شما از رابط خط فرمان در Google Cloud Shell و کد پایتون برای توسعه ADK استفاده خواهید کرد. نیازی نیست که متخصص پایتون باشید، اما درک اولیه از نحوه خواندن کد به شما در درک مفاهیم کمک می‌کند.

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .

مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

روی فعال کردن 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/..." با موفقیت به پایان رسید.

۳. نصب و راه‌اندازی

به Cloud Shell برگردید و مطمئن شوید که در دایرکتوری خانگی خود هستید.

دستور زیر را در Cloud Shell اجرا کنید تا یک مجموعه داده جدید به نام adk_logs در BigQuery ایجاد شود:

bq mk --dataset --location=US adk_logs

حالا، بیایید یک محیط مجازی پایتون ایجاد کنیم و بسته‌های مورد نیاز را نصب کنیم.

یک تب ترمینال جدید در Cloud Shell باز کنید و این دستور را اجرا کنید تا پوشه‌ای به نام adk-agent-observability ایجاد و به آن بروید:

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

ایجاد یک محیط مجازی پایتون:

python -m venv .venv

فعال کردن محیط مجازی:

source .venv/bin/activate

نصب ADK:

pip install --upgrade google-adk

۴. یک برنامه ADK ایجاد کنید

حالا، بیایید دستیار خرده‌فروشی خود را ایجاد کنیم. این نماینده به گونه‌ای طراحی خواهد شد که ...

دستور adk create utility را اجرا کنید تا یک برنامه عامل جدید با پوشه‌ها و فایل‌های لازم ایجاد شود:

adk create retail_assistant_app

دستورالعمل‌ها را دنبال کنید:

برای مدل، gemini-2.5-flash را انتخاب کنید.
برای بک‌اند، Vertex AI را انتخاب کنید.
شناسه و منطقه پیش‌فرض پروژه گوگل کلود خود را تأیید کنید.

یک نمونه تعامل در زیر نشان داده شده است:

برای باز کردن ویرایشگر Cloud Shell و مشاهده پوشه‌ها و فایل‌های تازه ایجاد شده، روی دکمه Open Editor در Cloud Shell کلیک کنید :

به فایل‌های تولید شده توجه کنید:

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

init.py: پوشه را به عنوان یک ماژول پایتون علامت‌گذاری می‌کند.
agent.py: شامل تعریف اولیه عامل است.
.env: برای مشاهده این فایل، ممکن است لازم باشد روی View > Toggle Hidden Files کلیک کنید.

فایل .env شامل متغیرهای محیطی برای پروژه شما است، هر متغیری را که به درستی از طریق اعلان‌ها تنظیم نشده است، به‌روزرسانی کنید:

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

۵. نماینده خود را تعریف کنید

حال بیایید یک سیستم چندعاملی سلسله مراتبی را تعریف کنیم.

نماینده مد در لحظه: از جستجوی گوگل برای یافتن مدهای روز استفاده می‌کند.
عامل داده‌های موجودی: از مجموعه ابزارهای 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]
)

۶. ایجاد لاگ با افزونه BigQuery Agent Analytics

حالا، بیایید افزونه BigQuery Agent Analytics را برای ثبت داده‌های اجرا پیکربندی کنیم.

برای انجام این کار، شما یک نمونه از کلاس App ایجاد خواهید کرد. این کلاس به عنوان کانتینر زمان اجرا برای عامل شما عمل می‌کند؛ حلقه مکالمه را مدیریت می‌کند، وضعیت کاربر را مدیریت می‌کند و هر افزونه پیوست شده (مانند ثبت‌کننده تحلیل عامل ما) را هماهنگ می‌کند.

کد زیر:

افزونه ثبت وقایع را مقداردهی اولیه می‌کند: افزونه BigQueryAgentAnalyticsPlugin را با جزئیات اتصال مورد نیاز ایجاد می‌کند.
افزونه را ادغام می‌کند: افزونه‌ی اولیه‌ی BigQuery را به سازنده‌ی 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 است.

۷. گزارش‌های عامل را تجزیه و تحلیل کنید

استفاده از ابزار

اکنون می‌توانیم ببینیم که عامل ما در پشت صحنه چه می‌کرده است! داده‌ها به BigQuery منتقل شده و آماده تجزیه و تحلیل هستند:

در کنسول ابری گوگل، BigQuery را جستجو کنید.
در پنل اکسپلورر ، پروژه خود را پیدا کنید.
مجموعه داده adk_logs را گسترش دهید.
جدول retail_assitant_agent_logs را باز کنید و روی Query کلیک کنید.

برای مشاهده‌ی فراخوانی‌های ابزاری که عامل شما انجام داده است و ثبت هرگونه خطای ابزار، کوئری زیر را در ویرایشگر 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

برای مشاهده این به صورت نمودار، روی Visualization کلیک کنید:

استفاده از توکن

برای تخمین هزینه عامل‌های خود، می‌توانید توکن‌های اعلان و توکن‌های کاندید مصرف شده توسط هر عامل مجزا را جمع کنید:

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

برای مشاهده این به صورت نمودار، روی Visualization کلیک کنید:

۱۳۴dc090ba55372d.png

۸. [امتیاز ویژه] تحلیل احساسات کاربر

حالا بیایید احساسات ورودی کاربر که به عامل ارائه شده است را تجزیه و تحلیل کنیم.

یک اتصال منبع ابری ایجاد کنید تا BigQuery بتواند با سرویس‌های هوش مصنوعی Vertex تعامل داشته باشد.:

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'

چند دقیقه صبر کنید و سپس تابع BigQuery AI.SCORE را برای تحلیل احساسات کاربر اجرا کنید:

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 برای هر ورودی کاربر، یک مقدار احساسی بین ۱ تا ۵ تعیین می‌کند. شما باید نتایجی مانند زیر را مشاهده کنید:

۹. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این کارگاه را حذف کنید.

مجموعه داده‌های ثبت وقایع ایجاد شده توسط اسکریپت را حذف کنید:

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

برای حذف دایرکتوری bigquery-adk-codelab و محتویات آن:

cd .. 
rm -rf adk-agent-observability

۱۰. تبریک

تبریک! شما یک سیستم چندعاملی با کیت توسعه عامل (ADK) ساختید و با موفقیت افزونه BigQuery Agent Analytics را برای ردیابی و حسابرسی رفتار عامل خود ادغام کردید.