عامل علوم داده‌ی حالت‌مند (Stateful Data Science Agent) روی زمان اجرای عامل (Agent Runtime)

۱. مرور کلی

در این آزمایشگاه کد، شما یک عامل علوم داده خواهید ساخت که داده‌های واقعی را از مجموعه داده‌های عمومی BigQuery پرس‌وجو می‌کند و تنظیمات برگزیده شما را در طول جلسات به خاطر می‌سپارد. سپس آن را در Agent Runtime، یک سرویس کاملاً مدیریت‌شده Google Cloud که زیرساخت، مقیاس‌پذیری و مدیریت جلسه را مدیریت می‌کند، مستقر خواهید کرد.

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

  • مجموعه ابزارهای BigQuery : این عامل، طرحواره‌ها را بررسی کرده و پرس‌وجوهای SQL را روی مجموعه داده‌های واقعی BigQuery اجرا می‌کند - این قابلیت هم به صورت محلی و هم در زمان استقرار، کار می‌کند.
  • بانک حافظه : هنگام استقرار، عامل تنظیمات و زمینه کاربر را در جلسات قطع شده به خاطر می‌سپارد.
  • قابلیت مشاهده : Cloud Trace مراحل استدلال عامل، فراخوانی ابزارها و تأخیرها را از طریق ابزار OpenTelemetry ثبت می‌کند.

آنچه یاد خواهید گرفت

  • نحوه ایجاد یک عامل ADK با BigQueryToolset برای دسترسی به داده‌های واقعی
  • نحوه پیکربندی بانک حافظه برای پایداری بین جلساتی
  • چگونه عامل خود را با استفاده از adk deploy در Agent Runtime مستقر کنیم؟
  • نحوه اعطای مجوزهای IAM برای حساب سرویس عامل مستقر شده
  • چگونه پایداری حافظه و مشاهده‌پذیری را آزمایش کنیم

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

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک مرورگر وب مانند کروم
  • اگر کد را به جای Cloud Shell روی دستگاه خودتان اجرا کنید: Google Cloud SDK ( gcloud CLI)، uv (مدیر بسته پایتون) و پایتون ۳.۱۲+ (در صورت نیاز به طور خودکار توسط uv نصب می‌شود)

ADK (کیت توسعه عامل) چارچوب گوگل برای ساخت عامل‌های هوش مصنوعی است. این آزمایشگاه کد از ADK برای ایجاد یک عامل و استقرار آن در Agent Runtime استفاده می‌کند.

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که با پایتون و گوگل کلود آشنایی دارند.

این آزمایشگاه کد تقریباً ۳۵ دقیقه طول می‌کشد (شامل ۵ تا ۱۰ دقیقه برای استقرار).

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۵ دلار هزینه داشته باشند.

۲. محیط خود را آماده کنید

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

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

پروژه خود را تنظیم کنید

ویرایشگر Cloud Shell را در پروژه GCP ایجاد شده خود باز کنید.

سپس یک ترمینال > ترمینال جدید ایجاد کنید و دستور زیر را برای تنظیم پروژه خود اجرا کنید. دستورات بعدی شناسه پروژه را از این تنظیمات می‌خوانند.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

فعال کردن APIها

در ترمینال، دستور زیر را اجرا کنید.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)
  • aiplatform.googleapis.com : میزبان عامل شما در Agent Runtime، شامل Gemini Enterprise Sessions و Memory Bank، است و مدل Gemini را ارائه می‌دهد.
  • رابط برنامه‌نویسی کاربردی BigQuery ( bigquery.googleapis.com ): کوئری‌های SQL در مجموعه داده‌های عمومی و خصوصی
  • API تله‌متری ( telemetry.googleapis.com ): ردیابی‌های OpenTelemetry برای مشاهده‌پذیری عامل

نصب ADK

در ترمینال، دستورات زیر را اجرا کنید تا یک پوشه برای این codelab ایجاد شود و ADK و وابستگی‌های آن نصب شود:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv یک محیط پایتون ایزوله برای این codelab ایجاد می‌کند، بنابراین نیازی به فعال کردن چیزی ندارید. دستورات پایتون را با uv run شروع کنید.

بسته google-adk شامل ابزار adk CLI است که برای آزمایش و استقرار عامل از آن استفاده خواهید کرد. adk deploy از google-cloud-aiplatform برای ایجاد عامل شما در Agent Runtime استفاده می‌کند و google-cloud-bigquery کتابخانه کلاینت پشت ابزارهای BigQuery ADK است.

۳. عامل را ایجاد کنید

در پوشه ~/adk-deploy-scale ، دایرکتوری agent را ایجاد کنید. تمام دستورات بعدی را از ~/adk-deploy-scale (والد data_science_agent/ ) اجرا کنید:

mkdir data_science_agent

سپس دستور زیر را اجرا کنید تا فایل data_science_agent/.env را با پروژه خود، منطقه‌ای که می‌خواهید عامل را در آن مستقر کنید و تنظیمات عامل مستقر شده ایجاد کنید. adk deploy این فایل را می‌خواند، بنابراین اگر یک ترمینال جدید باز کنید، این تنظیمات همچنان کار می‌کنند.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF
  • GOOGLE_CLOUD_PROJECT و GOOGLE_CLOUD_LOCATION : شناسه پروژه شما (که از gcloud پر شده است) و منطقه‌ای که عامل در آن اجرا می‌شود
  • GOOGLE_GENAI_USE_ENTERPRISE : از طریق پروژه Google Cloud شما، ADK با Gemini تماس می‌گیرد.
  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT : ورودی‌های کامل و پاسخ‌های عامل را ثبت می‌کند که برای اشکال‌زدایی مفید است.

ساختار دایرکتوری نهایی شما به این شکل خواهد بود:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

اکنون __init__.py و agent.py ایجاد خواهید کرد، سپس requirements.txt را در مرحله Deploy اضافه خواهید کرد.

data_science_agent/__init__.py را ایجاد کنید - این فایل برای اینکه ADK بتواند عامل شما را کشف و بارگذاری کند، لازم است:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

data_science_agent/agent.py را ایجاد کنید:

این عامل برای استخراج داده‌ها به BigQuery متصل می‌شود و جلسات را در Memory Bank ذخیره می‌کند.

حافظه هنگام استقرار به طور خودکار فعال می‌شود. Agent Runtime متغیر محیطی GOOGLE_CLOUD_AGENT_ENGINE_ID را تنظیم می‌کند، که هنگام اجرای محلی وجود ندارد.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by Agent Runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Runtime, where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

بیایید بررسی کنیم که این کد چه کاری انجام می‌دهد:

  1. BigQueryToolset ابزارهایی مانند execute_sql ، list_table_ids و get_table_info را در اختیار عامل قرار می‌دهد - این ابزار می‌تواند طرحواره‌ها را بررسی کرده و از هر مجموعه داده‌ای که فراخواننده به آن دسترسی دارد، پرس‌وجو کند.
  2. PreloadMemoryTool به طور خودکار قبل از هر فراخوانی LLM، با جستجوی محتوای مرتبط با پیام کاربر در Memory Bank، خاطرات مرتبط را بازیابی می‌کند. تابع فراخوانی _save_memory پس از هر بار اجرای عامل، جلسه را در Memory Bank حفظ می‌کند، بنابراین عامل می‌تواند زمینه را در جلسات آینده فراخوانی کند.
  3. App، عامل ریشه را در یک برنامه قابل استقرار که Agent Runtime می‌تواند به آن سرویس دهد، قرار می‌دهد. name باید با نام دایرکتوری ( data_science_agent ) مطابقت داشته باشد - adk web از این برای یافتن و بارگذاری عامل استفاده می‌کند.
  4. این دستورالعمل به اپراتور می‌گوید که از پروژه صورتحساب برای پرس‌وجوهای SQL استفاده کند و تنظیمات کاربر را به خاطر بسپارد.
  5. Gemini با client_kwargs={"location": "global"} فراخوانی‌های مدل را به نقطه پایانی سراسری، جایی که gemini-3.8-flash در دسترس است، ارسال می‌کند. خود عامل در us-central1 اجرا می‌شود: adk deploy GOOGLE_CLOUD_LOCATION را روی عامل مستقر شده به منطقه‌ای که شما در آن مستقر می‌شوید، تنظیم می‌کند، بنابراین مکان مدل به جای آن در کد تنظیم می‌شود.

۴. استقرار در زمان اجرای عامل

یک فایل requirements.txt در پوشه data_science_agent ایجاد کنید:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc
  • google-adk و google-genai : ADK و کلاینت Gemini
  • google-auth : احراز هویت در فضای ابری گوگل
  • google-cloud-bigquery : کتابخانه کلاینت BigQuery که BigQueryToolset از آن استفاده می‌کند. ADK به طور پیش‌فرض آن را نصب نمی‌کند.
  • python-dotenv : فایل .env را در هنگام راه‌اندازی بارگذاری می‌کند.
  • سه بسته opentelemetry-instrumentation-* ویژگی‌های مشاهده‌پذیری را که بعداً بررسی خواهید کرد، فعال می‌کنند. آن‌ها فراخوانی‌های مدل Gemini و ارتباطات داخلی gRPC/HTTP را ابزاربندی می‌کنند تا ردپاها در برگه ردپاهای عامل شما ظاهر شوند.

adk deploy همچنین فایل data_science_agent/.env که قبلاً ایجاد کرده‌اید را می‌خواند و تنظیمات آن را روی عامل مستقر شده اعمال می‌کند.

عامل را مستقر کنید. آخرین آرگومان data_science_agent دایرکتوری حاوی کد عامل شماست: 

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

تقریباً در شروع، خروجی دو خط زرد را نشان می‌دهد، Ignoring GOOGLE_CLOUD_PROJECT in .env ... و Ignoring GOOGLE_CLOUD_LOCATION in .env ... . انتظار می‌رود که این دو خط وجود داشته باشند: پرچم‌های --project و --region نسبت به مقادیر مشابه در .env اولویت دارند.

پرچم

هدف

--project / --region

هدف قرار دادن پروژه و منطقه گوگل کلود

--display_name

نام قابل خواندن توسط انسان در کنسول ابری نشان داده شده است

--otel_to_cloud

ردیابی‌ها و گزارش‌های OpenTelemetry را به Google Cloud صادر می‌کند و تله‌متری ( GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true ) را روی عامل مستقر شده فعال می‌کند.

هنگام استقرار در Agent Runtime، دو قابلیت به طور خودکار فعال می‌شوند:

  • Memory Bank : adk deploy عامل را به Sessions و Memory Bank در نمونه Agent Runtime خود متصل می‌کند. PreloadMemoryTool از Memory Bank می‌خواند و _save_memory به طور خودکار جلسات را حفظ می‌کند.
  • قابلیت مشاهده : Cloud Trace مراحل استدلال، فراخوانی ابزارها و تأخیرهای عامل را ثبت می‌کند.

۵. مجوزهای BigQuery را اعطا کنید

شما باید به BigQuery دسترسی به Agent Runtime service agent (عامل سرویس موتور استدلال پلتفرم هوش مصنوعی) بدهید. این عامل پس از استقرار، به عنوان این حساب سرویس تحت مدیریت گوگل (نه اعتبارنامه‌های شخصی شما) اجرا می‌شود، بنابراین برای اجرای کوئری‌های SQL به مجوزهای صریح نیاز دارد. 

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

هر دستور در صورت موفقیت‌آمیز بودن، Updated IAM policy for project [...] را چاپ می‌کند.

۶. تست عامل مستقر شده

صفحه Deployments را در کنسول Google Cloud باز کنید. روی عامل مستقر شده خود کلیک کنید، سپس روی برگه Playground کلیک کنید.

قابلیت‌های BigQuery را آزمایش کنید:

  1. "جدول‌های موجود در bigquery-public-data.hacker_news را فهرست کنید"
    • مورد انتظار : عامل list_table_ids را فراخوانی می‌کند و نام جدول‌ها از جمله full را برمی‌گرداند.
  2. "تعداد پست‌های سالانه را در bigquery-public-data.hacker_news.full پیدا کن"
    • مورد انتظار : عامل execute_sql با یک کوئری SQL فراخوانی می‌کند و جدولی از سال‌ها و تعداد پست‌ها را برمی‌گرداند.
  3. «درصد تغییر پست‌ها نسبت به سال گذشته چقدر بوده است؟»
    • مورد انتظار : عامل execute_sql را با یک پرس‌وجوی SQL فراخوانی می‌کند که درصد تغییر را محاسبه کرده و نتایج را برمی‌گرداند.

۷. تست پایداری حافظه

هنوز در زمین بازی هستید، به نماینده یک اولویت را آموزش دهید:

  1. «به یاد داشته باشید که مجموعه داده مورد علاقه من bigquery-public-data.hacker_news است.»
  2. «چه میزهایی دارد؟»

چند ثانیه صبر کنید تا حافظه باقی بماند (فراخوان _save_memory پس از پاسخ عامل اجرا می‌شود).

حالا با کلیک روی «جلسه جدید» در Playground، یک جلسه جدید شروع کنید ، سپس بپرسید:

  1. «مجموعه داده مورد علاقه من چیست؟»

حتی اگر این یک جلسه کاملاً جدید و بدون سابقه مکالمه باشد، عامل باید bigquery-public-data.hacker_news را فراخوانی کند. این روش به دلایل زیر کار می‌کند:

  • تابع _save_memory هر جلسه را از طریق callback_context.add_session_to_memory() در Memory Bank ذخیره می‌کند.
  • PreloadMemoryTool قبل از هر فراخوانی LLM، خاطرات مربوطه را بازیابی می‌کند.
  • بانک حافظه، محتوا را از نظر معنایی تطبیق می‌دهد، نه فقط با کلمه کلیدی

۸. مشاهده‌پذیری را بررسی کنید

در کنسول ابری، به عامل مستقر شده خود بروید و روی برگه ردیابی‌ها (Traces) کلیک کنید.

تب ردیابی‌ها جدول جلسه را نشان می‌دهد

شما باید یک جدول Session را ببینید که Sessionهای حاصل از کوئری‌های آزمایشی که در مراحل قبلی اجرا کرده‌اید را فهرست می‌کند. این جدول خلاصه‌ای از معیارهای هر Session را نشان می‌دهد - میانگین مدت زمان، فراخوانی‌های مدل، فراخوانی‌های ابزار، استفاده از توکن و هرگونه خطا.

برای بررسی جزئیات ردیابی یک جلسه ، از جمله موارد زیر، روی آن کلیک کنید:

  • یک گراف جهت‌دار غیرمدور (DAG) از محدوده‌های آن - که تجزیه گام به گام استدلال عامل، فراخوانی‌های ابزار (پرس‌وجوهای BigQuery) و تأخیرها را نشان می‌دهد.
  • ورودی‌ها و خروجی‌ها برای هر محدوده (فعال شده از طریق متغیر OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env در فایل .env )
  • ویژگی‌های فراداده‌ای مانند شناسه‌های دهانه، شناسه‌های ردیابی و زمان‌بندی

همچنین می‌توانید به نمای Span (در بالا تغییر وضعیت دهید) بروید تا spanهای جداگانه را در تمام جلسات مشاهده کنید.

نحوه‌ی کار ردیابی

وقتی با --otel_to_cloud مستقر می‌شوید، adk deploy یک کانتینر می‌سازد که سرور ADK API را با OpenTelemetry روشن اجرا می‌کند. در Agent Runtime، سرور یک خط لوله OpenTelemetry را راه‌اندازی می‌کند که:

  1. یک TracerProvider با یک صادرکننده OTLP ایجاد می‌کند که spanها را به telemetry.googleapis.com ارسال می‌کند.
  2. محدوده‌های ADK را برای اجراهای عامل، فراخوانی‌های مدل و فراخوانی‌های ابزار ثبت می‌کند و از سه بسته ابزار دقیق از requirements.txt شما برای اضافه کردن محدوده‌ها از کتابخانه‌های کلیدی (Gemini، httpx، gRPC) استفاده می‌کند.
  3. دسته‌ها و خروجی‌ها به API تله‌متری (Telemetry API) متصل می‌شوند، جایی که تب Traces آنها را می‌خواند.

کانتینر مستقر شده شامل ADK و OpenTelemetry SDK و exporter است، اما شامل بسته‌های ابزار دقیق نمی‌شود . به همین دلیل است که requirements.txt شما هر سه را فهرست می‌کند. بدون آنها، سرور ADK API یک هشدار ثبت می‌کند و از آن spanها صرف نظر می‌کند.

عیب‌یابی

اگر بعد از چند دقیقه هیچ اثری ظاهر نشد:

  1. بررسی کنید که API تله‌متری فعال باشد : شما آن را در مرحله راه‌اندازی فعال کرده‌اید. با این دستور تأیید کنید: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
  2. هشدارهای Cloud Logging را بررسی کنید : به Logging > Logs Explorer بروید و عبارت "proceeding without" یا "GoogleGenAiSdkInstrumentor" را جستجو کنید. هشداری که نام یک ابزار دقیق (GenAI، HTTPX یا gRPC) را نشان می‌دهد، به این معنی است که بسته opentelemetry-instrumentation-* مطابق با آن، در requirements.txt شما وجود ندارد.
  3. google-cloud-aiplatform به requirements.txt خود اضافه نکنید . adk deploy آن را به صورت خودکار اضافه می‌کند؛ اعلام شخصی آن می‌تواند باعث تداخل بسته OpenTelemetry شود و بی‌سروصدا ابزار دقیق را از کار بیندازد.

۹. تمیز کردن

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

عامل مستقر شده را از صفحه استقرارها در کنسول ابری حذف کنید. عامل خود را انتخاب کرده و روی حذف کلیک کنید.

اگر پروژه‌ای را به‌طور خاص برای این آزمایشگاه کد ایجاد کرده‌اید، می‌توانید کل پروژه را حذف کنید: 

gcloud projects delete <YOUR_PROJECT_ID>

در صورت تمایل، محیط محلی خود را پاکسازی کنید: 

cd ~
rm -rf ~/adk-deploy-scale

۱۰. تبریک

شما یک عامل علم داده با وضعیت (stateful data science agent) ساخته و آن را در Agent Runtime مستقر کرده‌اید!

آنچه آموخته‌اید

  • نحوه ایجاد یک عامل ADK با BigQueryToolset برای دسترسی به داده‌های واقعی
  • نحوه فعال کردن حافظه پایدار با Memory Bank با استفاده از PreloadMemoryTool و after_agent_callback
  • نحوه اعطای مجوزهای IAM برای حساب سرویس عامل مستقر شده
  • نحوه استقرار در Agent Runtime و فعال کردن قابلیت مشاهده با Cloud Trace

مراحل بعدی

  • با اعطای دسترسی به Agent Service Runtime به داده‌هایتان، مجموعه داده‌های خصوصی BigQuery خود را جستجو کنید.
  • اضافه کردن اجرای کد برای اجرای تحلیل پایتون در یک محیط امن (sandbox)
  • داشبوردهای رصدپذیری Cloud Trace را برای نظارت بر عامل خود در محیط عملیاتی تنظیم کنید
  • انتشار نتایج در Google Workspace با استفاده از ابزارهای MCP

اسناد مرجع