سخنرانی اصلی توسعه‌دهندگان بعدی در سال 2026: اشکال‌زدایی از Agentها در مقیاس بزرگ

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه عامل‌های هوش مصنوعی را که روی Google Cloud اجرا می‌شوند، اشکال‌زدایی کنید. شما یک عامل شبیه‌ساز را در Agent Runtime مستقر خواهید کرد، از Cloud Observability برای شناسایی مشکلات استفاده خواهید کرد و از Gemini Cloud Assist و Antigravity IDE برای ریشه‌یابی و رفع خطاها در زمان واقعی استفاده خواهید کرد.

فرضیه این نسخه آزمایشی این است که ما به تازگی ADK EventCompaction را به Simulator Agent اضافه کرده‌ایم. این به Simulator اجازه می‌دهد تا به صورت دوره‌ای گردش کار خود را با استفاده از Gemini خلاصه کند و کل زمینه ارسال شده به مدل را در هر نوبت کاهش دهد - در نتیجه کیفیت پاسخ را بهبود می‌بخشد و هزینه‌های کل را کاهش می‌دهد. اما، متوجه خواهیم شد که یک اشکال در EventCompactionConfig ما وجود دارد که باعث ایجاد خطا در agent می‌شود! این codelab نحوه یافتن این نوع مشکل و رفع سریع آن را شرح می‌دهد.

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

• عامل شبیه‌ساز ماراتون را در Agent Runtime مستقر کنید.
• برای تشخیص خطاهای عامل، یک هشدار نظارت بر ابر تنظیم کنید.
• با استفاده از Cloud Trace و Gemini Cloud Assist خطاها را بررسی کنید.
• با استفاده از Antigravity و MCP، عامل را ریشه‌یابی و وصله کنید.

توجه: Gemini Cloud Assist در حال حاضر در پیش‌نمایش خصوصی است. برای اجرای این آزمایشگاه کد، نیازی به فهرست مجاز Cloud Assist ندارید. تمام مراحل Cloud Assist به شماره ۸ (اختیاری) محدود شده‌اند: استفاده از تحقیقات Cloud Assist - اگر هنوز نمی‌توانید به Cloud Assist دسترسی پیدا کنید، از این صفحه صرف نظر کنید!

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

• یک مرورگر وب مانند کروم .
• یک حساب گوگل
• ضد جاذبه (پشتیبانی از مک، لینوکس و ویندوز)
• پایتون ۳.۱۳+
• uv (مدیر بسته پایتون)

مدت زمان تخمینی: ۴۵ دقیقه

هزینه تخمینی: کمتر از ۵ دلار آمریکا

۲. قبل از شروع

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

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

محیط خود را تنظیم کنید

Antigravity را باز کنید و وارد سیستم شوید. سپس، با فشردن کلیدهای cmd-shift-P (یا ctrl-shift-P ) یک ترمینال باز کنید و سپس عبارت "Create New Terminal" را تایپ کنید.

1. از طریق ترمینال، با Google Cloud احراز هویت کنید:

gcloud auth login
gcloud auth application-default login

2. شناسه پروژه خود را تنظیم کنید:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

فعال کردن APIها

برای فعال کردن API های مورد نیاز Google Cloud، دستور زیر را اجرا کنید:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

اگر در فهرست Gemini Cloud Assist (پیش‌نمایش خصوصی) قرار دارید، این APIهای اضافی را فعال کنید:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

۳. عامل شبیه‌ساز را تنظیم کنید

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

مخزن را کلون کنید

مخزن next-26-keynotes را کلون کنید و به دایرکتوری demo بروید:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

پیکربندی متغیرهای محیطی

عامل شبیه‌ساز از یک فایل .env برای پیکربندی استفاده می‌کند.

فایل sample.env را در سمت چپ پنجره Antigravity (اکسپلورر) پیدا کنید:

sample.env را باز کنید و فیلد GCP_PROJECT_ID را با شناسه واقعی پروژه گوگل کلود خود به‌روزرسانی کنید. فایل باید مشابه این باشد:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

ما در حال فعال‌سازی یکپارچه‌سازی‌های OpenTelemetry هستیم تا ردپاهای دقیقی از فراخوانی‌های ابزار و جریان استدلال عامل را ثبت کنیم.

۴. عامل شبیه‌ساز را در زمان اجرای عامل مستقر کنید

اکنون، شما با استفاده از کیت توسعه عامل (ADK) عامل را در Agent Runtime مستقر خواهید کرد.

نصب وابستگی‌ها

uv sync

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

1. دستور adk deploy را اجرا کنید. این مرحله، عامل شما را بسته‌بندی کرده و آن را در Google Cloud (Agent Runtime) مستقر می‌کند.

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

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

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

شناسه زمان اجرای عامل تولید شده را یادداشت کنید. بعداً به آن نیاز خواهید داشت!

2. از یک مرورگر وب، کنسول Agent Runtime را باز کنید. باید simulator_agent در Agent Runtime در حال اجرا ببینید، در حالی که مجموعه telemetry فعال است .

۵. یک سیاست هشدار تنظیم کنید

برای تشخیص خودکار خطاهای Agent Runtime، یک هشدار مبتنی بر گزارش در کنسول Google Cloud ایجاد خواهید کرد.

1. به کنسول Cloud Monitoring - Alerting بروید.

2. روی ویرایش کانال‌های اعلان کلیک کنید. به پایین بروید تا به نوع ایمیل برسید، سپس یک کانال اعلان ایمیلی برای ارسال به ایمیل شخصی خود ایجاد کنید. روی ذخیره کلیک کنید.

3. به داشبورد هشدار برگردید و روی ایجاد سیاست کلیک کنید.
4. در سمت راست صفحه، روی «ایجاد هشدار مبتنی بر گزارش» کلیک کنید.

5. شما به Log Explorer هدایت خواهید شد. عبارت زیر را در آن وارد کنید و به جای آن شناسه پروژه خود را قرار دهید.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

این کوئری لاگ به دنبال لاگ‌های خطا در Agent Runtime agent شما می‌گردد، که در آن ReasoningEngine نام API اصلی برای Agent Runtime است.

6. روی اجرای پرس‌وجو کلیک کنید. هنوز هیچ گزارشی نمایش داده نمی‌شود - که البته قابل انتظار است.
7. در نوار ابزار نتایج، روی «اقدامات» کلیک کنید، سپس روی «ایجاد هشدار گزارش» کلیک کنید.

8. هشدار مبتنی بر گزارش را پیکربندی کنید. به هشدار یک نام (هر نامی) بدهید، سپس سطح شدت را روی خطا (Error ) تنظیم کنید.

9. برای بخش «تنظیم تعداد دفعات اعلان» روی «بعدی» کلیک کنید (پیش‌فرض‌ها را نگه دارید).

10. برای چه کسی باید مطلع شود؟ (Who should be notice?)، هشدار را طوری تنظیم کنید که کانال اعلان ایمیلی که اخیراً راه‌اندازی کرده‌اید (مثلاً My Email ) را فعال کند.
11. روی ذخیره کلیک کنید.

۶. حادثه را آغاز کنید

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

1. در کنسول گوگل کلود، به کنسول Agent Runtime بروید.
2. روی simulator_agent کلیک کنید.
3. از نوار ابزار بالا، روی Playground کلیک کنید. این یک جلسه جدید با عامل ADK آغاز می‌کند.

4. از پنجره چت جلسه، عبارت Test Simulation را تایپ کنید و برای ارسال اعلان، کلید اینتر را فشار دهید.

این کار شبیه‌سازی ماراتن را آغاز می‌کند و هزاران دونده شبیه‌سازی شده را در مسیر برنامه‌ریزی شده ردیابی می‌کند. شما باید چندین فراخوانی ابزار برای get_runner_telemetry و analyze_medical_risk را مشاهده کنید، زیرا شبیه‌سازی چندین "منطقه" از مسابقه را ارزیابی می‌کند.

پس از چند دقیقه، باید انتظار داشته باشید که اجرای عامل متوقف شود و هیچ پاسخی برنگرداند.

5. ظرف یک دقیقه یا بیشتر، باید ایمیلی را در صندوق ورودی خود مشاهده کنید که شما را از یک حادثه جدید در داخل اپراتور مطلع می‌کند.

برای باز کردن کنسول Cloud Monitoring روی View Incident کلیک کنید. برای بررسی مشکل در کنسول به صفحه بعد بروید.

۷. حادثه را در کنسول بررسی کنید

1. حادثه را در کنسول Cloud Monitoring مشاهده کنید. باید گزارش‌های خطا را از Simulator Agent مشاهده کنید.

از این دیدگاه، تشخیص اینکه دقیقاً در چه نقطه‌ای عامل از کار افتاده دشوار است. برای دیدن فراخوانی‌های ابزار اساسی و جریان استدلال عامل، ردپاهای عامل را بررسی خواهیم کرد.

2. دوباره کنسول Agent Runtime را باز کنید. روی simulator_agent کلیک کنید، سپس تب Traces را باز کنید.

3. روی جدیدترین ردیابی در لیست کلیک کنید. سپس در بالا سمت راست، روی Timeline کلیک کنید. باید نمای ردیابی را با "span" های جداگانه ببینید. هر span نشان دهنده یک فراخوانی مدل یا ابزار در گردش کار عامل است.

4. روی آخرین دهانه در نمای ترسیم کلیک کنید. باید قرمز باشد.
5. روی Stacktrace کلیک کنید. باید گزارش‌های خطای مربوط به فراخوانی مدل API Gemini را ببینید. به طور خاص، خطای 400: Invalid Argument . این نشان دهنده یک مشکل در سطح درخواست با payload ارسال شده توسط Simulator Agent به Gemini API است.

۸. [اختیاری] استفاده از Cloud Assist Investigations برای اشکال‌زدایی

فقط در صورتی که در فهرست Gemini Cloud Assist (پیش‌نمایش خصوصی) قرار دارید، این مراحل را دنبال کنید. در غیر این صورت، به صفحه بعد بروید.

1. در محدوده‌ی خطای رخ داده، روی Logs and Events کلیک کنید. لاگ "Exception" را با دکمه‌ی sparkle در کنار آن پیدا کنید. سپس روی Investigate Log کلیک کنید.

2. این کار باعث می‌شود که یک بررسی ابری از نوار کناری سمت راست صفحه آغاز شود. بارگذاری این بخش حدود ۳ تا ۵ دقیقه طول می‌کشد.

3. پس از تکمیل، تحقیق را باز کنید.

4. خلاصه تحقیقات را مشاهده کنید.

5. به پایین اسکرول کنید و فرضیه‌ها را مشاهده کنید. Gemini Cloud Assist باید خط خاصی از فایل agent.py مربوط به Simulator Agent که باعث ایجاد خطای ۴۰۰ Gemini API می‌شود را شناسایی کرده باشد.

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

۹. از ضد جاذبه برای ریشه‌یابی و رفع مشکل استفاده کنید

1. آنتی گراویتی را دوباره باز کنید.
2. مدیر عامل را در بالا سمت راست صفحه باز کنید.

3. مطمئن شوید که مدل روی حالت Gemini 3 Flash and Planning تنظیم شده است.

4. عبارت زیر را وارد کنید و اینتر را بزنید.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

شما باید ببینید که Antigravity کد agent.py را بررسی می‌کند و در GitHub به دنبال مشکلات مرتبط می‌گردد:

دلیل اصلی خطای Gemini API 400 این است که ما از محدودیت توکن زمینه ورودی Gemini 3 Flash که حدود ۱ میلیون است، عبور می‌کنیم. دلیل این اتفاق این است که ما EventCompaction را به اندازه کافی فعال نمی‌کنیم تا پاسخ‌های عظیم از فراخوانی‌های ابزار Simulator Agents را به طور موثر خلاصه کنیم.

برای رفع این مشکل، Antigravity باید پیشنهاد کند که یک پارامتر token_threshold به EventsCompactionConfig اضافه شود تا به صورت دوره‌ای، پس از رسیدن به تعداد مشخصی از توکن‌ها، متن را در هر فراخوانی فشرده کند.

این با راه حل پیشنهادی در این مشکل گیت‌هاب همسو است.

اصلاحیه را روی agent.py.

تأیید کنید که چیزی شبیه به این را می‌بینید:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

نکته مهم این است که token_threshold و event_retention_size باید تنظیم شوند!

۱۰. استقرار مجدد و اعتبارسنجی اصلاحیه

اکنون که اصلاحیه token_threshold را روی EventCompactionConfig مربوط به عامل ADK اعمال کرده‌ایم، می‌توانیم Simulator Agent را دوباره به Agent Runtime منتقل کنیم.

1. Antigravity را باز کنید –> ترمینال جدید .
2. متغیرهای محیطی را تنظیم کنید. AGENT_RUNTIME_ID باید نام کامل منبع simulator_agent شما باشد. این را می‌توانید در کنسول Agent Runtime - لیست عامل‌ها پیدا کنید.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. عامل را مجدداً مستقر کنید:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

اجرای این دستور چند دقیقه طول می‌کشد. پس از موفقیت، باید تصویر زیر را ببینید:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. کنسول Agent Runtime را باز کنید. simulator_agent را دوباره باز کنید. روی Playground کلیک کنید.
5. همان عبارت را وارد کنید: Test Simulation - سپس، Enter را فشار دهید.
6. اجرای شبیه‌سازی کامل Marathon در بک‌اند باید چند دقیقه طول بکشد. باید چندین فراخوانی ابزار را مشاهده کنید. در نهایت، باید پاسخی مانند این را ببینید:

این نشان می‌دهد که شبیه‌ساز با موفقیت اجرا شده است! ✅

7. نمای Trace را برای آن جلسه ADK باز کنید.
8. شما باید تمام span های "آبی" را بدون خطای قرمز ببینید. توجه کنید که چگونه تعداد کل توکن‌های session از محدودیت 1 میلیون توکن context در Gemini API فراتر رفته است. این اشکالی ندارد، زیرا اکنون EventCompaction به اندازه کافی در هر فراخوانی اجرا می‌شود تا از اجرای بیش از حد محدودیت context برای فراخوانی‌های مدل منفرد جلوگیری شود.

🎊 هورا! ما خطا را در عامل شبیه‌ساز برطرف کردیم!

۱۱. تمیز کردن

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

برنامه زمان اجرای Agent را حذف کنید

می‌توانید نمونه Reasoning Engine را از طریق کنسول یا با استفاده از دستور gcloud (در صورت داشتن نام منبع) حذف کنید. برای سادگی، از کنسول استفاده کنید:

1. به صفحه زمان اجرای عامل بروید.
2. simulator_agent را انتخاب کنید -> روی دکمه سه نقطه در سمت راست کلیک کنید.
3. روی حذف کلیک کنید.

خط‌مشی نظارت بر ابر را حذف کنید

1. به کنسول Cloud Monitoring -> Alerting بروید.
2. به پایین اسکرول کنید تا به Policies برسید، سپس روی دکمه سه نقطه کلیک کنید تا Policy را حذف کنید .

۱۲. 🎊 تبریک می‌گویم!

تبریک! شما با موفقیت یک عامل هوش مصنوعی را در Google Cloud اشکال‌زدایی کردید.

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

• نحوه‌ی استقرار عامل‌ها در Agent Runtime
• نحوه تشخیص خطاها با استفاده از هشدارهای مانیتورینگ ابری .
• نحوه بررسی حوادث فعال با استفاده از Cloud Logging و نمای ردیابی Agent Runtime .
• نحوه بررسی خرابی‌ها با استفاده از Gemini Cloud Assist
• نحوه استفاده از Antigravity برای ریشه‌یابی و رفع اشکالات عامل.
• چگونه فشرده‌سازی رویداد ADK را برای مدیریت چرخش‌های عامل طولانی‌مدت و پرابزار تنظیم کنیم؟

مراحل بعدی

• درباره Agent Runtime بیشتر بدانید.
• درباره کیت توسعه عامل بیشتر بدانید.
• درباره هشدار در نظارت ابری بیشتر بدانید.
• درباره Gemini Cloud Assist بیشتر بدانید.