گردش‌های کاری Agent First - از اعلان تا تولید

۱. مرور کلی

به «روز دوم» خوش آمدید. در حالی که ساخت یک برنامه و زدن دکمه «انتشار» جادویی است، ترافیک دنیای واقعی، شکست‌های دنیای واقعی را به همراه دارد. به جای اینکه روزهای خود را صرف کلنجار رفتن با YAML یا جستجوی لاگ‌ها کنید، می‌توانید گروهی از عوامل متخصص را برای مدیریت عملیات خود ایجاد کنید. این آزمایشگاه کد به شما نشان می‌دهد که چگونه پشته یکپارچه Google Cloud (Eventarc، Cloud Run، Firestore، Cloud Build، BigQuery) دریافت ایمن اسرار، جریان لاگ‌ها و رفع مشکلات را برای عوامل آسان می‌کند.

نمای کلی

در این آزمایشگاه کد، شما DinoQuest - یک بازی ماجراجویی دایناسوری مبتنی بر Gemini - را از پایه خواهید ساخت و آن را به یک خط لوله CI/CD کاملاً عامل‌گرا متصل خواهید کرد. در پایان موارد زیر را خواهید داشت:

  • یک برنامه وب DinoQuest که روی Cloud Run اجرا می‌شود (نام سرویس: dinoquest )
  • یک خط لوله تجزیه و تحلیل لاگ که لاگ‌های Cloud Run را به BigQuery منتقل می‌کند و یک داشبورد تعاملی از بینش‌های بازی ایجاد می‌کند.
  • عامل اصلاح ( remediation-agent ) — یک عامل اصلاح ADK که خطاهای Cloud Run را رصد می‌کند و آنها را به طور خودکار برطرف می‌کند، و به عنوان سرویس Cloud Run خود که توسط Eventarc راه‌اندازی شده است، مستقر می‌شود.
  • یک عامل CI ( ci-agent ) که تفاوت PR شما را می‌خواند، تست‌ها را هوشمندانه بررسی می‌کند، از طریق Cloud Build یک تصویر Docker می‌سازد و وضعیت commit را به GitHub ارسال می‌کند.
  • یک CD Agent که ریسک استقرار را ارزیابی می‌کند، ترافیک را تقسیم می‌کند، معیارها را رصد می‌کند و به طور خودکار ارتقا یا بازگشت می‌دهد.

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

  • نحوه استقرار یک برنامه فول‌استک Vite + FastAPI در Cloud Run به عنوان یک کانتینر واحد
  • نحوه پیکربندی Firebase Auth و Firestore برای یک برنامه React
  • نحوه ساخت و استقرار یک عامل ADK که به رویدادهای Pub/Sub از طریق Eventarc واکنش نشان می‌دهد
  • چگونه لاگ‌های Cloud Run را به BigQuery ارسال کنیم و از تجزیه و تحلیل بازی پرس‌وجو کنیم؟
  • نحوه نوشتن مهارت‌های عامل‌گرا برای CI و استقرار قناری

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

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک پروژه Firebase (می‌تواند همان پروژه GCP باشد)
  • یک حساب کاربری گیت‌هاب و یک انشعاب از مخزن DinoQuest
  • دسترسی به ضد جاذبه با جمینی (کارگزار گوگل)
  • رابط خط فرمان gcloud نصب و احراز هویت شد - دستورالعمل‌های نصب را در زیر ببینید
  • node ≥ ۱۸ و npm
  • python3 ≥ ۳.۱۱
  • git و gh (خط فرمان گیت‌هاب)

نصب رابط خط فرمان gcloud

مک‌او‌اس

brew install --cask google-cloud-sdk

یا فایل نصب را از cloud.google.com/sdk/docs/install دانلود کنید.

ویندوز

winget install Google.CloudSDK

یا فایل نصب ویندوز (.exe) را از cloud.google.com/sdk/docs/install دانلود کرده و اجرا کنید.

پس از نصب، راه‌اندازی اولیه و احراز هویت:

gcloud init
gcloud auth login
gcloud auth application-default login

۲. فایربیس را راه‌اندازی کنید

هر عامل برای استدلال به داده‌ها نیاز دارد. DinoQuest از Firestore و Firebase Auth برای ارائه یک لایه داده آماده برای تولید استفاده می‌کند که عامل‌های ما بعداً با استفاده از زبان طبیعی آن را کشف، بررسی و به‌روزرسانی می‌کنند.

از آنجایی که این برنامه از طریق AI Studio تولید شده است، به شدت با Firebase یکپارچه شده است. استفاده از Firebase مزایای متعددی را ارائه می‌دهد که مهمترین آنها معماری از پیش ایمن و دسترسی مدیریت‌شده به داده‌ها به صورت آماده است که تضمین می‌کند وضعیت بازی شما از روز اول محافظت می‌شود.

الف. ایجاد یک پروژه Firebase

  1. به console.firebase.google.com بروید
  2. روی افزودن پروژه کلیک کنید (این گزینه در گزینه ایجاد یک پروژه جدید پنهان است) → پروژه GCP موجود خود را انتخاب کنید (یا یک پروژه جدید ایجاد کنید)
  3. در صورت درخواست، گوگل آنالیتیکس را غیرفعال کنید → ایجاد پروژه (یا می‌توانید از تنظیمات پیش‌فرض استفاده کنید)

ب. فعال کردن احراز هویت گوگل

  1. در کنسول فایربیس، به مسیر Security → Authentication (Get started) → Sign-in method بروید.
  2. روی گوگل کلیک کنید → گزینه فعال کردن را فعال کنید → ایمیل پشتیبانی خود را ذخیره کنید → ذخیره

ج. اضافه کردن localhost به عنوان یک دامنه مجاز

  1. هنوز در مرحله‌ی احراز هویت هستید ، روی تب تنظیمات کلیک کنید
  2. در قسمت Authorized domains ، تأیید کنید که localhost فهرست شده باشد (باید به‌طور پیش‌فرض باشد)

د. ایجاد یک پایگاه داده Firestore

  1. به پایگاه داده و ذخیره‌سازی → پایگاه داده Firestore → ایجاد پایگاه داده بروید
  2. نسخه استاندارد را انتخاب کنید → بعدی
  3. منطقه us-central1 را انتخاب کنید (یا با منطقه Cloud Run خود مطابقت دهید)
  4. شروع در حالت تولید → ایجاد را انتخاب کنید

پس از ایجاد، شناسه پایگاه داده خود را یادداشت کنید - مگر اینکه آن را نامگذاری کنید، شبیه (default) خواهد بود.

ه. تنظیم قوانین امنیتی فایربیس

در مسیر Firestore Database → Rules ، قوانین پیش‌فرض را با موارد زیر جایگزین کنید:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // ===============================================================
    // Helper Functions
    // ===============================================================
    function isAuthenticated() {
      return request.auth != null;
    }
    
    function isOwner(userId) {
      return isAuthenticated() && request.auth.uid == userId;
    }

    function isValidUser(data) {
      return data.keys().hasAll(['uid', 'email']) &&
             data.uid is string && data.uid.size() > 0 &&
             (data.email == null || (data.email is string && data.email.matches("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")));
    }

    function isValidDinosaur(data) {
      return data.keys().hasAll(['userId', 'name', 'type']) &&
             data.userId == request.auth.uid &&
             data.name is string && data.name.size() > 0 && data.name.size() < 50 &&
             data.type in ['Speedy', 'Tank', 'Balanced', 'Agile'];
    }

    function isValidGame(data) {
      return data.keys().hasAll(['userId', 'score']) &&
             data.userId == request.auth.uid &&
             data.score is number && data.score >= 0;
    }


    match /users/{userId} {
      allow read: if isOwner(userId);
      allow create: if isOwner(userId) && isValidUser(request.resource.data);
      allow update: if isOwner(userId) && isValidUser(request.resource.data);

      match /dinosaurs/{dinoId} {
        allow read: if isOwner(userId);
        allow create: if isOwner(userId) && isValidDinosaur(request.resource.data);
        allow update: if isOwner(userId) && isValidDinosaur(request.resource.data);
      }

      match /games/{gameId} {
        allow read: if isOwner(userId);
        allow create: if isOwner(userId) && isValidGame(request.resource.data);
      }

      match /seenAnnouncements/{announcementId} {
        allow read, create: if isOwner(userId);
      }
    }

    match /announcements/{announcementId} {
      allow read: if isAuthenticated();
    }

    // Default deny
    match /{document=**} {
      allow read, write: if false;
    }

    match /scores/{scoreId} {
      allow read: if true;
      allow create: if isAuthenticated();
      allow update: if false;
    }
  }
}

روی انتشار کلیک کنید.

و. یک برنامه وب اضافه کنید و پیکربندی را دریافت کنید

  1. به تنظیمات پروژه (آیکون چرخ‌دنده) → برگه عمومی بروید
  2. به برنامه‌های خود بروید → روی افزودن برنامه کلیک کنید → نماد وب را انتخاب کنید ( )
  3. اسمشو بذار dinoquest → ثبت نام برنامه
  4. شیء firebaseConfig نشان داده شده را کپی کنید - در یک لحظه به آن نیاز خواهید داشت

۳. اجرای بازی

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

نمای کلی

یکی از دو گزینه زیر را انتخاب کنید. هر دو گزینه یک GEMINI_API_KEY تولید می‌کنند که در هر مرحله بعدی به طور یکسان از آن استفاده می‌کنید - هیچ تغییر دیگری لازم نیست.

الف. تنظیم کلید API جمینی

Vertex AI به شما امکان می‌دهد یک کلید API Gemini ایجاد کنید که مستقیماً به پروژه GCP شما متصل شده و با استفاده از حساب سرویس پیش‌فرض پروژه، برای آن صورتحساب صادر می‌شود - نیازی به حساب جداگانه AI Studio نیست.

  1. شناسه پروژه GCP خود را صادر کنید: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
  2. APIهای مورد نیاز را فعال کنید و مجوزهای لازم را به حساب سرویس پیش‌فرض Compute Engine اعطا کنید: 
    gcloud auth application-default set-quota-project $PROJECT_ID
gcloud config set project $PROJECT_ID

# Enable Vertex AI, Compute Engine, and Generative Language APIs
gcloud services enable aiplatform.googleapis.com \
                       compute.googleapis.com \
                       generativelanguage.googleapis.com

# Grant Vertex AI User role to the default compute service account
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user" \
  --condition=None
  3. صفحه کلیدهای API مربوط به Vertex AI را در کنسول ابری باز کنید.
  4. روی ایجاد اعتبارنامه‌ها کلیک کنید → کلید API را انتخاب کنید
  5. در کادر محاوره‌ای ایجاد:
    • نام کلید را Dino_Key قرار دهید.
    • کادر «تأیید اعتبار فراخوانی‌های API از طریق حساب کاربری سرویس» را علامت بزنید.
    • در قسمت حساب سرویس، حساب سرویس محاسباتی پیش‌فرض ( PROJECT_NUMBER-compute@developer.gserviceaccount.com ) را انتخاب کنید.
    • به محدودیت‌های Select API برگردید، GEMINI API را بررسی کنید
    • روی ایجاد کلیک کنید
  6. کلید تولید شده را کپی کنید.

گزینه ب - استودیوی هوش مصنوعی (سریعترین برای توسعه محلی)

  1. aistudio.google.com را باز کنید
  2. روی دریافت کلید API در نوار کناری سمت چپ کلیک کنید
  3. روی ایجاد کلید API کلیک کنید → پروژه GCP خود را انتخاب کنید → کلید را کپی کنید

هر یک از کلیدها در مراحل بعدی به عنوان GEMINI_API_KEY تنظیم می‌شوند - بک‌اند با آنها به طور یکسان رفتار می‌کند.

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

مخزن دوره در آدرس https://github.com/gca-americas/dinoquest قرار دارد. لطفاً ابتدا آن را به حساب گیت‌هاب خود منتقل کنید . در عوض، از نماینده می‌خواهیم که روی مخزن شما کار کند.

پس از انشعاب، شاخه main مخزن انشعاب یافته DinoQuest خود را کلون کنید و وارد دایرکتوری پروژه شوید:

git clone https://github.com/YOUR_GITHUB_USERNAME/dinoquest.git
cd dinoquest

ب. تنظیم متغیرهای محیطی

در هر ترمینال bash جدیدی که در طول این آزمایش کد باز می‌کنید، مطمئن شوید که این متغیرهای محیطی ضروری را تنظیم کرده‌اید. مقادیر جایگزین را با جزئیات واقعی پروژه خود جایگزین کنید:

ابتدا، آدرس مخزن گیت‌هاب خود را صادر کنید:

export GITHUB_REPO_URL=https://github.com/YOUR_GITHUB_USERNAME/dinoquest

سپس متغیرهای محیطی باقی مانده را export کنید:

export PROJECT_ID=your-project-id
export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
export CLOUD_RUN_REGION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
export HARNESS_EVENTS_TOPIC=projects/$PROJECT_ID/topics/harness-events
export CLOUD_BUILD_REPO=<YOUR_GITHUB_USERNAME>-dinoquest

تأیید کنید که ساختار درست به نظر می‌رسد: 

dinoquest/
├── backend/          # FastAPI backend (serves frontend + Gemini API calls)
├── frontend/         # React/Vite frontend
├── skills/           # Agentic CI/CD skill files
├── Dockerfile        # Multi-stage build (React → Python)
├── start.sh          # Local dev launcher
└── README.md

ب. ایجاد فایل محیط backend

ابتدا، کلید API Gemini خود را صادر کنید: 

export GEMINI_API_KEY=YOUR_GEMINI_API_KEY_FROM_STEP_2

سپس فایل .env را ایجاد کنید: 

cat > backend/.env <<EOF
GEMINI_API_KEY=$GEMINI_API_KEY
GOOGLE_GENAI_USE_VERTEXAI=False
GOOGLE_CLOUD_PROJECT=$PROJECT_ID
EOF

ج. فعال کردن بررسی برنامه فایربیس / حساب سرویس (برای اجرای ابری)

هنگام اجرا روی Cloud Run، backend از Application Default Credentials برای ارتباط با Firebase استفاده می‌کند - هیچ فایل کلید حساب سرویسی مورد نیاز نیست. فراخوانی firebase_admin.initialize_app() در backend/main.py این را به طور خودکار دریافت می‌کند.

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

gcloud auth application-default login

د. فایل پیکربندی برنامه Firebase را ایجاد کنید

در پوشه frontend/ ، firebase-applet-config.json را با پیکربندی مرحله قبل ایجاد کنید: 

{
  "apiKey": "YOUR_API_KEY",
  "authDomain": "YOUR_PROJECT_ID.firebaseapp.com",
  "projectId": "YOUR_PROJECT_ID",
  "storageBucket": "YOUR_PROJECT_ID.appspot.com",
  "messagingSenderId": "YOUR_SENDER_ID",
  "appId": "YOUR_APP_ID",
  "firestoreDatabaseId": "(default)"
}

نکته: firestoreDatabaseId باید با شناسه پایگاه داده‌ای که در مرحله قبل ایجاد کردید، مطابقت داشته باشد. اگر از مقدار پیش‌فرض استفاده کرده‌اید، آن را روی "(default)" بگذارید.

تغییرات را دوباره به مخزن خود اعمال کنید: 

git add frontend/firebase-applet-config.json
git commit -m "chore: add firebase config"
git push origin main

ج. اجرای DinoQuest به صورت محلی

۱. فعال کردن API های مورد نیاز 

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  secretmanager.googleapis.com \
  firestore.googleapis.com \
  logging.googleapis.com \
  pubsub.googleapis.com \
  eventarc.googleapis.com \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  aiplatform.googleapis.com

۲. داینو کوئست را شروع کنید

اسکریپت start.sh رابط کاربری React را می‌سازد و ترمینال را به رابط کاربری FastAPI می‌دهد که فایل‌های استاتیک کامپایل شده را ارائه می‌دهد: 

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -q

cd ..
# Force-remove the Vertex AI flag from the current terminal session to avoid conflicts
unset GOOGLE_GENAI_USE_VERTEXAI
./start.sh

آدرس http://localhost:8000 را در مرورگر خود باز کنید. باید صفحه عنوان DinoQuest را ببینید. با گوگل وارد شوید، اولین دایناسور خود را ایجاد کنید و ذخیره آن در Firestore را تأیید کنید.

عیب‌یابی: اگر صفحه خالی یا خطاهای احراز هویت Firebase را مشاهده کردید، دوباره بررسی کنید که frontend/firebase-applet-config.json مقادیر صحیحی داشته باشد و localhost در لیست دامنه‌های مجاز باشد.

ه. DinoQuest را روی Cloud Run مستقر کنید

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

export PROJECT_ID=$(gcloud config get-value project)

۳. یک مخزن رجیستری مصنوعات ایجاد کنید 

gcloud artifacts repositories create dinoquest \
  --repository-format=docker \
  --location=$CLOUD_RUN_REGION \
  --description="DinoQuest container images"

۴. کلید API جمینی را در Secret Manager ذخیره کنید 

echo -n $GEMINI_API_KEY | \
  gcloud secrets create gemini-api-key --data-file=-

# Grant the default compute service account access to the secret
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud secrets add-iam-policy-binding gemini-api-key \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

۵. ساخت ایمیج کانتینر با Cloud Build 

gcloud builds submit \
  --tag $CLOUD_RUN_REGION-docker.pkg.dev/$PROJECT_ID/dinoquest/app:latest .

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

۶. استقرار در Cloud Run

ابتدا، ایمیل ادمین خود را صادر کنید: 

export ADMIN_EMAIL=<YOUR_TEST_ACCOUNT_EMAIL>

سپس سرویس را مستقر کنید: 

gcloud run deploy dinoquest \
  --image=$CLOUD_RUN_REGION-docker.pkg.dev/$PROJECT_ID/dinoquest/app:latest \
  --region=$CLOUD_RUN_REGION \
  --platform=managed \
  --allow-unauthenticated \
  --memory=128Mi \
  --set-secrets="GEMINI_API_KEY=gemini-api-key:latest" \
  --set-env-vars="ADMIN_EMAILS=$ADMIN_EMAIL" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=False" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID"

وقتی دستور کامل شد، Cloud Run یک URL سرویس چاپ می‌کند. این URL را کپی کنید - برای تأیید دامنه در Firebase به آن نیاز خواهید داشت.

۷. دامنه Cloud Run را در Firebase مجاز کنید

برای اینکه کاربران بتوانند از برنامه‌ی مستقر شده‌ی شما وارد سیستم شوند، باید آدرس اینترنتی Cloud Run را به دامنه‌های مجاز Firebase اضافه کنید:

  1. به کنسول فایربیس → احراز هویت → تنظیمات → دامنه‌های مجاز برگردید
  2. روی افزودن دامنه کلیک کنید
  3. آدرس اینترنتی سرویس Cloud Run خود را وارد کنید (مثلاً dinoquest-xxxxx.us-central1.run.app ) - پیشوند https:// را حذف کنید.
  4. روی ذخیره کلیک کنید

۸. داده‌های جدول امتیازات را وارد کنید

برای اینکه به بازی خود کمی «جان» اولیه بدهید و مطمئن شوید که ماموران شما اطلاعات دارند، می‌توانید در جدول امتیازات اولیه، امتیازات اولیه را قرار دهید.

  1. مطمئن شوید که در دایرکتوری ریشه dinoquest هستید: 
    cd ~/dinoquest
  2. ایجاد و فعال‌سازی یک محیط مجازی: 
    python3 -m venv venv
source venv/bin/activate
  3. وابستگی مورد نیاز Firestore را نصب کنید: 
    pip install google-cloud-firestore
  4. اسکریپت seeding را اجرا کنید: 
    python3 prep/seed_scores.py
  5. غیرفعال کردن محیط مجازی: 
    deactivate

حالا می‌توانید آدرس اینترنتی سرویس را در مرورگر خود باز کنید - DinoQuest کاملاً فعال است!

۴. راه‌اندازی تئاتر دایناسور

نقش عامل: تجسم‌گر . چگونه یک تیم عامل خودمختار را رصد می‌کنید؟ Dino Theater دریچه‌ای بلادرنگ به ذهن گروه عامل‌های شما ارائه می‌دهد. به جای خیره شدن به لاگ‌های ترمینال، می‌توانید در یک داشبورد بصری و زنده، شاهد استدلال، تماس با یکدیگر و اجرای وظایف از طریق ابر توسط عامل‌های خود باشید.

نمای کلی

الف. استقرار Dino Theater در Cloud Run

ابتدا به دایرکتوری خانگی خود برگردید و کد Dino Theater را کپی کنید: 

cd ~
git clone https://github.com/gca-americas/dinoquest-theater.git
cd dinoquest-theater
  1. کانتینر را بسازید و فشار دهید: 
    gcloud builds submit --tag $CLOUD_RUN_REGION-docker.pkg.dev/$PROJECT_ID/dinoquest/dino-theater:latest .
  2. تنظیم حساب کاربری سرویس و دسترسی‌ها: 
    # Create the service account
gcloud iam service-accounts create dino-theater

# Create the Pub/Sub topic (if you haven't yet)
gcloud pubsub topics create harness-events

# Create the subscription
gcloud pubsub subscriptions create harness-events-theater \
  --topic=harness-events

# Grant subscriber role
gcloud pubsub subscriptions add-iam-policy-binding harness-events-theater \
  --member="serviceAccount:dino-theater@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/pubsub.subscriber"
  3. استقرار برنامه:
    gcloud run deploy dino-theater \
  --image $CLOUD_RUN_REGION-docker.pkg.dev/$PROJECT_ID/dinoquest/dino-theater:latest \
  --region=$CLOUD_RUN_REGION \
  --service-account=dino-theater@${PROJECT_ID}.iam.gserviceaccount.com \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID" \
  --allow-unauthenticated \
  --min-instances=1
    نکته: برای حفظ اتصال SSE بین رویدادها، استفاده --min-instances=1 توصیه می‌شود.
  4. تأیید کنید که کار می‌کند: URL سرویس مستقر شده را در مرورگر خود باز کنید (مثلاً https://dino-theater-xxx-uc.a.run.app/demo ).

۵. دواپس‌های عامل‌گرا در IDE

نقش عامل: آنتی‌گراویتی بومی . برای پر کردن شکاف بین IDE و فضای ابری شما، ما آنتی‌گراویتی را به سرورهای مدیریت‌شده‌ی MCP گوگل کلود متصل می‌کنیم. این به عامل بومی شما «چشم» به پروژه‌تان می‌دهد و به آن اجازه می‌دهد تا گزارش‌ها را تجزیه و تحلیل کند، معیارها را بررسی کند و در مورد زیرساخت استدلال کند، بدون اینکه شما مجبور باشید کلیدهای API را دستکاری کنید یا به کنسول بروید.

قبل از اجرای هرگونه مهارت، باید دسترسی Antigravity به Google Cloud را پیکربندی کنید و کتاب‌های راهنمای مهارت DinoQuest را بارگیری کنید.

الف. سرویس مدیریت‌شده‌ی MCP گوگل را نصب کنید

سرویس مدیریت‌شده‌ی MCP گوگل، دسترسی به تمام APIهای گوگل کلود را از طریق یک نقطه‌ی پایانی میزبانی‌شده‌ی واحد فراهم می‌کند.

احراز هویت با استفاده از اعتبارنامه‌های پیش‌فرض برنامه: 

gcloud auth application-default login

ب. پیکربندی mcp_config.json

mcp_config.json در دایرکتوری پیکربندی Antigravity خود (معمولاً ~/.gemini/antigravity/mcp_config.json ) یا از طریق کنسول ایجاد یا به‌روزرسانی کنید. این کار به Antigravity امکان دسترسی به ابزارهای Google Cloud و GitHub مورد نیاز برای مهارت‌های زیر را می‌دهد: 

{
  "mcpServers": {
    "google-developer-knowledge": {
      "serverUrl": "https://developerknowledge.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-bigquery": {
      "serverUrl": "https://bigquery.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-cloud-logging": {
      "serverUrl": "https://logging.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-cloud-monitoring": {
      "serverUrl": "https://monitoring.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "disabledTools": [
        "get_dashboard",
        "list_dashboards"
      ]
    },
    "google-cloud-run": {
      "serverUrl": "https://run.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "disabledTools": [
        "deploy_service_from_image",
        "deploy_service_from_archive",
        "deploy_service_from_file_contents"
      ]
    },
    "google-cloud-sql": {
      "serverUrl": "https://sqladmin.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "disabled": true
    },
    "google-cloud-trace": {
      "serverUrl": "https://cloudtrace.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-error-reporting": {
      "serverUrl": "https://clouderrorreporting.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-firestore": {
      "serverUrl": "https://firestore.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "google-resource-manager": {
      "serverUrl": "https://cloudresourcemanager.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    },
    "gemini-cloud-assist": {
      "serverUrl": "https://geminicloudassist.googleapis.com/mcp",
      "authProviderType": "google_credentials"
    }
  }
}

ج. مهارت‌ها را در ضد جاذبه بارگذاری کنید (اختیاری)

Antigravity مهارت‌ها را در دایرکتوری‌های استاندارد خاصی پیدا می‌کند. مهارت‌های DinoQuest را از مخزن کلون شده خود به پوشه سراسری مهارت‌های Antigravity کپی کنید: 

# Create the standard skills directory if it doesn't exist
mkdir -p ~/.gemini/antigravity/skills

# Copy all DinoQuest skills into the global skills folder
cp -r skills/* ~/.gemini/antigravity/skills/

د. شروع مجدد ضد جاذبه (اختیاری)

برای اعمال تغییرات mcp_config.json و بارگذاری مهارت‌های تازه کپی‌شده، برنامه Antigravity را مجدداً راه‌اندازی کنید .

پس از راه اندازی مجدد:

  1. تأیید کنید که سرورهای MCP گوگل و گیت‌هاب وضعیت سبز «متصل» را در تنظیمات نشان می‌دهند.
  2. مطمئن شوید که مهارت‌های DinoQuest در لیست مهارت‌های شما وجود دارند.

توجه: هر مهارت یک جدول ## Configuration در بالای SKILL.md خود دارد. پس از کپی کردن، باید مقادیر موجود در ~/.gemini/antigravity/skills/ /SKILL.md را به‌روزرسانی کنید. ~/.gemini/antigravity/skills/ /SKILL.md برای مطابقت با پروژه شما.

ه. اصلاح سرویس ابری در IDE محلی

  1. خطا را فعال کنید : URL DinoQuest مستقر شده (از مرحله قبل) را در مرورگر خود باز کنید.
  2. رفتن به جدول امتیازات : روی دکمه‌ی جدول امتیازات کلیک کنید. پیاده‌سازی فعلی جدول امتیازات عمداً ناکارآمد است - سعی می‌کند حجم عظیمی از داده‌ها را در حافظه بارگذاری کند و باعث خطای کمبود حافظه (OOM) شود.
  3. در Antigravity Agent Manager (Agent HUB)، از آن بخواهید که به بازیابی خطا و احتمالاً رفع علت اصلی آن کمک کند.
  • نکته ۱: بفهمید مشکل دینوکوئست چیست.
  • سوال دوم: آیا می‌توانید کد بازی Dinoquest را بررسی کنید و علت خطای کمبود حافظه را برطرف کنید؟

۶. گزارش‌ها را به BigQuery منتقل کنید و تجزیه و تحلیل ایجاد کنید

نقش عامل: عامل داده . تبدیل لاگ‌های خام به استراتژی محصول قابل اجرا نباید ساعت‌ها صرف پردازش دستی داده‌ها کند. با استفاده از کیت عامل داده و BigQuery MCP، ما یک خط لوله «صفر ETL» ایجاد می‌کنیم که لاگ‌ها را مستقیماً به BigQuery منتقل می‌کند و به عامل اجازه می‌دهد تا در کمتر از دو دقیقه یک داشبورد تحلیلی ممتاز ایجاد کند.

مهارت log-router-bq-report یک سینک Cloud Logging راه‌اندازی می‌کند که به‌طور مداوم گزارش‌های Cloud Run مربوط به DinoQuest را به BigQuery منتقل می‌کند، سپس داده‌ها را برای تولید گزارش‌های ترافیک و بینش‌های تحلیلی بازی جستجو می‌کند.

نمای کلی

الف. متغیرهای مهارت را پیکربندی کنید

skills/log-router-bq-report/SKILL.md را در مخزن DinoQuest خود باز کنید و بخش پیکربندی را در بالا به‌روزرسانی کنید: 

| Variable      | Your Value         |
|---------------|--------------------|
| SERVICE_NAME  | dinoquest          |
| BQ_DATASET    | dinoquest_logs     |
| LOG_SINK_NAME | dinoquest-bq-sink  |

ب. مهارت Antigravity را اجرا کنید

Antigravity را با استفاده از مخزن DinoQuest به عنوان زمینه باز کنید و به Gemini بگویید: 

Run the log-router-bq-report skill

این مهارت باعث می‌شود:

  1. پروژه GCP خود را به طور خودکار حل کنید
  2. بررسی کنید که آیا سینک BigQuery از قبل وجود دارد یا خیر - اگر وجود نداشته باشد، مجموعه داده و سینک را ایجاد می‌کند.
  3. اعطای مجوزهای IAM : این دستور به writerIdentity مربوط به sink، نقش BigQuery Data Editor را در مجموعه داده اعطا می‌کند.

توجه: درست مانند سینک Eventarc، ممکن است در طول این فرآیند هشداری از gcloud مشاهده کنید: «لطفاً به یاد داشته باشید که نقش ویرایشگر داده BigQuery را در مجموعه داده به serviceAccount:service-... اعطا کنید.» این مهارت به طور خودکار این کار را انجام می‌دهد.

ج. استفاده از Antigravity برای تولید گزارش

به سادگی از Antigravity بخواهید که «سینک لاگ BigQuery را تنظیم کرده و گزارش تحلیلی را تولید کند» . عامل موارد زیر را انجام خواهد داد:

  1. پیکربندی زیرساخت : ایجاد مجموعه داده BigQuery و مخزن ثبت وقایع ابری.
  2. مدیریت مجوزها : به طور خودکار نقش‌های IAM لازم را به هویت نویسنده‌ی سینک اعطا می‌کند.
  3. ایجاد بینش : گزارش‌ها را تجزیه و تحلیل کنید و یک داشبورد HTML تعاملی و باکیفیت با اندازه‌گیری بازی و تجزیه و تحلیل نرخ برد ایجاد کنید.

۷. عامل ترمیم خود ترمیم شونده

نقش عامل: عامل SRE . وقتی یک سرویس تولید ساعت ۲ بامداد از کار می‌افتد، شما نباید مجبور باشید از خواب بیدار شوید. این عامل به عنوان اولین پاسخ‌دهنده شما عمل می‌کند. این عامل که توسط گزارش‌های خطای Cloud Run از طریق Eventarc فعال می‌شود، به طور خودکار خرابی را تجزیه و تحلیل می‌کند، راه حلی پیشنهاد می‌دهد و یک خط لوله اصلاح را آغاز می‌کند - همه اینها قبل از اینکه حتی وارد کنسول شوید.

DinoAgent یک عامل ADK است که از طریق Eventarc به گزارش‌های خطای Cloud Run گوش می‌دهد، علت اصلی را تشخیص می‌دهد و به‌طور خودکار آن را اصلاح می‌کند - یا با افزایش حافظه، بازگرداندن ترافیک یا ثبت یک PR اصلاح کد در GitHub.

نمای کلی

الف. مخزن Remediation Agent را کلون کنید 

cd ~
git clone https://github.com/gca-americas/dinoquest-reme-agent.git
cd dinoquest-reme-agent

ساختار پروژه: 

dinoquest-reme-agent/
├── main.py              # Service entrypoint — receives Eventarc HTTP POST, runs agent
├── runner.py            # ADK Runner + session service
├── agent.py             # LlmAgent definition, loads skill from file
├── tools.py             # Cloud Run v2 API tools (list/get/rollback/update)
├── skills/
│   └── remediation/
│       ├── SKILL.md     # Agent playbook — edit this to change behavior
│       └── scripts/     # Shell scripts for the code-fix track
│           ├── clone_repo.sh
│           ├── read_file.sh
│           ├── apply_fix.sh
│           ├── commit_branch.sh
│           ├── open_pr.sh
│           └── rollback_fix.sh
├── requirements.txt
└── Dockerfile

ب. تنظیم دسترسی به گیت‌هاب (مسیر اصلاح کد)

مسیر اصلاح کد، مخزن DinoQuest شما را کلون می‌کند، فایل‌های منبع را می‌خواند، وصله‌ها را اعمال می‌کند و PRها را باز می‌کند. این مسیر به یک توکن دسترسی شخصی GitHub با محدوده repo نیاز دارد.

  1. به github.com/settings/tokens بروید → توکن جدید ایجاد کنید (کلاسیک)
  2. به آن یک نام بدهید، محدوده repo را انتخاب کنید → توکن تولید کنید → آن را کپی کنید

آن را در Secret Manager ذخیره کنید:

ابتدا، توکن گیت‌هاب خود را اکسپورت کنید: 

export GH_TOKEN=ghp_YOUR_TOKEN_HERE

سپس راز را ایجاد کنید: 

echo -n $GH_TOKEN | \
  gcloud secrets create github-token --data-file=-

ج. تنظیم اعلان‌های Slack (اختیاری)

وقتی یک اصلاح کامل می‌شود، DinoAgent خلاصه‌ای از آن را در یک کانال Slack منتشر می‌کند.

  1. به api.slack.com/apps بروید → ایجاد برنامه جدید → از ابتدا
  2. نام آن را DinoAgent بگذارید، فضای کاری خود را انتخاب کنید → ایجاد برنامه
  3. در قسمت ویژگی‌ها → وب‌هوک‌های ورودی → گزینه را فعال کنید
  4. روی افزودن وب‌هوک جدید به فضای کاری کلیک کنید → یک کانال انتخاب کنید → اجازه دهید
  5. آدرس وب هوک را کپی کنید ( https://hooks.slack.com/services/... )

آن را در Secret Manager ذخیره کنید: 

export SLACK_TOKEN=YOUR_SLACK_WEBHOOK
echo -n "https://hooks.slack.com/services/$SLACK_TOKEN" | \
  gcloud secrets create slack-webhook --data-file=-

د. حساب کاربری سرویس DinoAgent را ایجاد کنید 

gcloud iam service-accounts create remediation-agent \
  --display-name="Cloud Run Remediation Agent"

export SA="remediation-agent@${PROJECT_ID}.iam.gserviceaccount.com"

for ROLE in \
  roles/run.admin \
  roles/iam.serviceAccountUser \
  roles/eventarc.eventReceiver \
  roles/aiplatform.user \
  roles/artifactregistry.reader \
  roles/secretmanager.secretAccessor \
  roles/pubsub.publisher \
  roles/logging.viewer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${SA}" --role="$ROLE" \
    --condition=None
done

به آن دسترسی به اسرار را بدهید: 

for SECRET in github-token slack-webhook; do
  gcloud secrets add-iam-policy-binding $SECRET \
    --member="serviceAccount:${SA}" \
    --role="roles/secretmanager.secretAccessor"
done

ه. ساخت و استقرار DinoAgent در Cloud Run 

# Get Project Number for the CIAgent URL
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export CIAGENT_URL=https://ci-agent-${PROJECT_NUMBER}.${CLOUD_RUN_REGION}.run.app
export SA="remediation-agent@${PROJECT_ID}.iam.gserviceaccount.com"
export GITHUB_REPO_URL=https://github.com/YOUR_REPO
HARNESS_EVENTS_TOPIC=projects/$PROJECT_ID/topics/harness-events


AGENT_IMAGE="$CLOUD_RUN_REGION-docker.pkg.dev/${PROJECT_ID}/dinoquest/remediation-agent:latest"
gcloud builds submit --tag $AGENT_IMAGE .


gcloud run deploy remediation-agent \
  --image=$AGENT_IMAGE \
  --region=$CLOUD_RUN_REGION \
  --service-account=$SA \
  --memory=2Gi \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID},GOOGLE_GENAI_USE_VERTEXAI=True" \
  --set-env-vars="GITHUB_REPO_URL=${GITHUB_REPO_URL}" \
  --set-secrets="SLACK_WEBHOOK_URL=slack-webhook:latest" \
  --set-env-vars="HARNESS_EVENTS_TOPIC=${HARNESS_EVENTS_TOPIC}" \
  --set-env-vars="CIAGENT_URL=${CIAGENT_URL}" \
  --set-secrets="GITHUB_TOKEN=github-token:latest" \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --no-cpu-throttling \
  --timeout=300

و. تریگر Eventarc را سیم‌کشی کنید

برای دریافت گزارش‌های خطای Cloud Run، یک تاپیک Pub/Sub ایجاد کنید: 

gcloud pubsub topics create cloud-run-errors

یک سینک ثبت وقایع ابری ایجاد کنید که گزارش‌های خطا را از سرویس dinoquest شما فیلتر کرده و آنها را به تاپیک مورد نظر هدایت کند: 

export SERVICE_NAME=dinoquest
FILTER="resource.type=\"cloud_run_revision\" resource.labels.service_name=\"$SERVICE_NAME\" severity=ERROR NOT logName=~\"cloudaudit\" NOT httpRequest.requestUrl=~\"/_ah/health\""

gcloud logging sinks create cloud-run-errors-sink \
  pubsub.googleapis.com/projects/${PROJECT_ID}/topics/cloud-run-errors \
  --log-filter="$FILTER"

توجه: وقتی دستور بالا را اجرا می‌کنید، gcloud یک پیام اطلاعاتی چاپ می‌کند که می‌گوید: «لطفاً به یاد داشته باشید که به serviceAccount:service-... نقش Pub/Sub Publisher را در موضوع اعطا کنید.» مرحله بعدی دقیقاً همین کار را انجام می‌دهد.

به هویت نویسنده‌ی مخزن (حساب سرویس ذکر شده در هشدار) اجازه‌ی انتشار بدهید: 

SINK_SA=$(gcloud logging sinks describe cloud-run-errors-sink \
  --format='value(writerIdentity)')

gcloud pubsub topics add-iam-policy-binding cloud-run-errors \
  --member="${SINK_SA}" --role="roles/pubsub.publisher"

تأیید کنید که فعال است: 

gcloud eventarc triggers describe remediation-trigger --location=$CLOUD_RUN_REGION

به Eventarc اجازه دهید تا عامل اصلاح را فراخوانی کند: 

gcloud run services add-iam-policy-binding remediation-agent \
  --region=$CLOUD_RUN_REGION \
  --member="serviceAccount:${SA}" \
  --role="roles/run.invoker"

تریگر Eventarc را ایجاد کنید: 

gcloud eventarc triggers create remediation-trigger \
  --location=$CLOUD_RUN_REGION \
  --destination-run-service=remediation-agent \
  --destination-run-region=$CLOUD_RUN_REGION \
  --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
  --transport-topic=projects/${PROJECT_ID}/topics/cloud-run-errors \
  --service-account=${SA}

اکنون اصلاح کاملاً خودکار شده است. DinoAgent فراتر از مقیاس‌بندی زیرساخت، یک تحلیل ریشه‌ای عمیق روی کد برنامه انجام می‌دهد، یک وصله معنایی اعمال می‌کند و از ارتباط عامل به عامل (A2A) برای تحویل اصلاحیه به عامل CI برای تأیید و استقرار استفاده می‌کند. می‌توانید جزئیات پیاده‌سازی را در پایگاه کد reme-agent بررسی کنید.

۸. عامل CI را راه‌اندازی کنید

نقش عامل: خط لوله CI . دیگر با فایل‌های پیچیده YAML و اسکریپت‌های ساخت دستی کلنجار نروید. این عامل، لوله‌کشی عملیاتی PRهای شما را مدیریت می‌کند. تغییرات کد شما را می‌خواند، زمینه را درک می‌کند، تست‌های لازم را بررسی می‌کند و تصاویر Docker شما را از طریق Cloud Build می‌سازد و اطمینان حاصل می‌کند که هر کامیت قبل از رسیدن به شاخه اصلی، "توسط عامل تأیید" می‌شود.

ci-agent یک عامل خط لوله CI مستقل است که به عنوان یک سرویس Cloud Run مستقر شده است. این عامل، ساخت‌های Docker را به Cloud Build ارسال می‌کند، برای تکمیل نظرسنجی می‌کند، تصویر را در Artifact Registry تأیید می‌کند و به GitHub گزارش می‌دهد.

نمای کلی

چرا از یک عامل برای خط لوله CI خود استفاده کنید؟ برخلاف اسکریپت‌های استاتیک سنتی، یک خط لوله CI عاملیک موارد زیر را ارائه می‌دهد:

  1. طبقه‌بندی دامنه شناختی : این قابلیت به طور هوشمندانه عمق تست مورد نیاز - جابجایی بین بررسی نوع، تست واحد یا مجموعه‌های یکپارچه‌سازی کامل - را بر اساس تأثیر معنایی تغییرات کد شما تعیین می‌کند.
  2. مدیریت خودکار روابط عمومی : عامل می‌تواند به طور خودکار روابط عمومی ایجاد کند، خلاصه‌ای دقیق از تغییرات را ارسال کند و حتی اسکن مخفی و ممیزی‌های امنیتی را بدون دخالت انسان مدیریت کند.
  3. تشخیص خرابی در لحظه : وقتی یک ساخت با مشکل مواجه می‌شود، عامل فقط گزارش‌ها را نشان نمی‌دهد؛ بلکه رد پشته را تجزیه و تحلیل می‌کند، علت احتمالی را شناسایی می‌کند و یک تشخیص قابل خواندن توسط انسان را مستقیماً به PR ارسال می‌کند.

الف. مخزن CIAgent را کلون کنید 

cd ~
git clone https://github.com/gca-americas/dinoquest-ci-agent.git
cd dinoquest-ci-agent

ب. حساب کاربری سرویس CIAgent را ایجاد کنید 

gcloud iam service-accounts create ci-agent \
  --display-name="CIAgent CI Pipeline"

export SA="ci-agent@${PROJECT_ID}.iam.gserviceaccount.com"

# Grant necessary roles to the service account
for ROLE in \
  roles/cloudbuild.builds.editor \
  roles/cloudbuild.builds.builder \
  roles/artifactregistry.reader \
  roles/artifactregistry.writer \
  roles/aiplatform.user \
  roles/secretmanager.secretAccessor \
  roles/pubsub.publisher \
  roles/developerconnect.admin; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${SA}" --role="$ROLE" \
    --condition=None
done



# ci-agent needs to act as itself when running build steps
gcloud iam service-accounts add-iam-policy-binding $SA \
  --member="serviceAccount:${SA}" \
  --role="roles/iam.serviceAccountUser"

ج. مخزن گیت‌هاب را به Cloud Build متصل کنید

CIAgent ساخت‌ها را از طریق repoSource ارسال می‌کند، که مستلزم اتصال مخزن GitHub به Cloud Build Developer Connect است.

  1. به کنسول GCP → Cloud Build → مخازن بروید
  2. روی اتصال مخزن کلیک کنید
  3. گیت‌هاب (اپلیکیشن ساخت ابری گیت‌هاب) را انتخاب کنید
  4. مخزن YOUR_GITHUB_USERNAME/dinoquest خود را مجاز و انتخاب کنید.
  5. وقتی از شما خواسته شد که یک تریگر ایجاد کنید، روی «اتصال » و «رد شدن» کلیک کنید.
  6. نام اتصال خود را یادداشت کنید (پیش‌فرض معمولاً نام کاربری GitHub یا مشابه آن است).

د. به مأمور سیا دسترسی به اسرار را بدهید

ما از رمزهای ایجاد شده قبلی برای DinoAgent دوباره استفاده خواهیم کرد: 

gcloud secrets add-iam-policy-binding github-token \
  --member="serviceAccount:${SA}" \
  --role="roles/secretmanager.secretAccessor"

gcloud secrets add-iam-policy-binding slack-webhook-ci \
  --member="serviceAccount:${SA}" \
  --role="roles/secretmanager.secretAccessor"

ه. ساخت و استقرار CIAgent در Cloud Run 

# Set up required variables for orchestration
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export CDAGENT_URL=https://cd-agent-${PROJECT_NUMBER}.${CLOUD_RUN_REGION}.run.app
export CI_AGENT_URL=ci-agent-${PROJECT_NUMBER}.${CLOUD_RUN_REGION}.run.app
export GITHUB_OWNER="YOUR_GITHUB_USERNAME"
export CLOUD_BUILD_CONNECTION="YOUR_CONNECTION_NAME"  # Update this if your connection name is different
export CLOUD_BUILD_REPO="YOUR_GITHUB_USERNAME-dinoquest" # Update this if your connection name is different

export SLACK_TOKEN=YOUR_SLACK_WEBHOOK
echo -n "https://hooks.slack.com/services/$SLACK_TOKEN" | \
  gcloud secrets create slack-webhook-ci --data-file=-

export SA="ci-agent@${PROJECT_ID}.iam.gserviceaccount.com"
AGENT_IMAGE="$CLOUD_RUN_REGION-docker.pkg.dev/${PROJECT_ID}/dinoquest/ci-agent:latest"
gcloud builds submit --tag $AGENT_IMAGE .

gcloud run deploy ci-agent \
  --image=$AGENT_IMAGE \
  --region=$CLOUD_RUN_REGION \
  --service-account=$SA \
  --memory=1Gi \
  --timeout=600 \
  --allow-unauthenticated \
  --min-instances=1 \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID},GOOGLE_GENAI_USE_VERTEXAI=True" \
  --set-env-vars="HARNESS_EVENTS_TOPIC=${HARNESS_EVENTS_TOPIC}" \
  --set-env-vars="HOST=${CI_AGENT_URL},PROTOCOL=https" \
  --set-secrets="SLACK_WEBHOOK_URL=slack-webhook-ci:latest" \
  --set-env-vars="GITHUB_OWNER=${GITHUB_OWNER},GITHUB_REPO=dinoquest" \
  --set-env-vars="CLOUD_BUILD_CONNECTION=${CLOUD_BUILD_CONNECTION},CLOUD_BUILD_REPO=${CLOUD_BUILD_REPO},CLOUD_BUILD_REGION=${CLOUD_RUN_REGION}" \
  --set-env-vars="CDAGENT_URL=${CDAGENT_URL}" \
  --set-secrets="GITHUB_TOKEN=github-token:latest" \
  --min-instances=1

و. تنظیم دستور Slack slash

  1. به api.slack.com/apps بروید → ایجاد برنامه جدید → از ابتدا
  2. نام آن را CIAgent ، فضای کاری خود را انتخاب کنید → ایجاد برنامه
  3. در بخش ویژگی‌ها → دستورات اسلش → ایجاد دستور جدید
  4. دستور: /runci
  5. درخواست آدرس اینترنتی: آدرس اینترنتی CIAgent Cloud Run شما از بالا به همراه /slack (مثلاً https://ci-agent-xxx-.us-central1.run.app/slack )
  6. توضیح مختصر: Trigger CI
  7. ذخیره
  8. در قسمت تنظیمات → نصب برنامه ، روی نصب در فضای کاری و مجاز کردن کلیک کنید.

عامل CI به عنوان "مغز" در بالای سرویس‌های قدرتمند Google Cloud مانند Cloud Build و Artifact Registry قرار دارد. پس از تأیید ساخت، با فراخوانی عامل CD از طریق A2A ، مرحله نهایی استقرار را آغاز می‌کند و از انتقال یکپارچه بین چرخه‌های ساخت و انتشار اطمینان حاصل می‌کند.

۹. راه‌اندازی استقرار

نقش عامل: عامل CD . استقرار نباید یک جهش ایمانی باشد. این عامل ریسک را برای شما مدیریت می‌کند. ایمنی استقرار را ارزیابی می‌کند، تقسیم ترافیک قناری را مدیریت می‌کند و معیارهای بلادرنگ را رصد می‌کند تا تصمیم بگیرد که آیا یک نسخه را ارتقا دهید یا آن را به عقب برگردانید. این دروازه‌بان نهایی در گروه عامل‌های خودمختار شماست.

cd-agent یک عامل استقرار خودکار Canary است که به عنوان یک سرویس Cloud Run مستقر می‌شود. این عامل درخواست‌های استقرار A2A را از ci-agent دریافت می‌کند، امتیاز ریسک را محاسبه می‌کند، درصد Canary کالیبره شده با ریسک را تعیین می‌کند، معیارها را رصد می‌کند و به طور خودکار ارتقا یا عقب‌نشینی می‌کند. همچنین با استفاده از Firestore از استقرارهای گذشته یاد می‌گیرد.

نمای کلی

اتصال عامل‌ها مستقیماً یک «خط لوله شناختی» ایجاد می‌کند که در آن هر انتقال، انتقال غنی از قصد و زمینه است. برخلاف وب‌هوک‌های سنتی، ارتباط A2A امکان موارد زیر را فراهم می‌کند:

  1. اشتراک‌گذاری هوشمند محتوا : عامل‌ها کل خاطرات جلسه، تفاوت‌های PR و نمرات ریسک را منتقل می‌کنند و اطمینان حاصل می‌کنند که عامل بعدی قبل از شروع کار، «چرا»ی کامل را دارد.
  2. دست دادن‌های شناختی : عامل‌ها می‌توانند در مورد دروازه‌ها مذاکره کنند. به عنوان مثال، عامل CD می‌تواند در طول یک راه‌اندازی Canary، تست‌های دود خاصی را از عامل CI درخواست کند تا یک اصلاحیه را در زمان واقعی تأیید کند.
  3. اصلاح مشارکتی : اگر یک استقرار با شکست مواجه شود، عامل CD می‌تواند به صورت پیشگیرانه عامل اصلاح را با معیارهای شکست مطلع کند و قبل از اینکه حتی یک انسان فراخوانده شود، یک تحلیل ریشه‌ای مستقل را آغاز کند.
  4. مذاکره منابع : عامل‌ها می‌توانند در مورد نیازهای زیرساختی مذاکره کنند. برای مثال، عامل CI می‌تواند از عامل اصلاح بخواهد که در صورت شناسایی یک اصلاح در مقیاس بزرگ، ظرفیت ساخت بیشتری را فراهم کند، یا عامل CD می‌تواند قبل از انتشار اصلی، مقیاس‌بندی خوشه تولید را پیشنهاد دهد.
  5. اجماع چندعاملی : برای تغییرات پرخطر، چندین عامل (مثلاً عامل امنیتی و عامل CD) می‌توانند از طریق A2A یک «امضای مشترک» انجام دهند و اطمینان حاصل کنند که کد نه تنها ساخته و مستقر می‌شود، بلکه قبل از رسیدن به مرحله تولید، به سیاست‌های امنیتی نیز پایبند است.

الف. مخزن CDAgent را کلون کنید 

cd ~
git clone https://github.com/gca-americas/dinoquest-cd-agent.git
cd dinoquest-cd-agent

ب. ایجاد پایگاه داده Firestore

CDAgent الگوهای حافظه استقرار خود را در Firestore ذخیره می‌کند: 

gcloud firestore databases create \
  --region=$CLOUD_RUN_REGION \
  --project=$PROJECT_ID

(اگر قبلاً در این پروژه پایگاه داده ایجاد کرده‌اید، می‌توانید از این مرحله صرف نظر کنید.)

ج. حساب کاربری سرویس CDAgent را ایجاد کنید 

gcloud iam service-accounts create cd-agent \
  --display-name="CDAgent Canary Deployer"

export SA="cd-agent@${PROJECT_ID}.iam.gserviceaccount.com"

# Grant necessary roles
for ROLE in \
  roles/run.developer \
  roles/iam.serviceAccountUser \
  roles/artifactregistry.reader \
  roles/artifactregistry.writer \
  roles/monitoring.viewer \
  roles/datastore.user \
  roles/aiplatform.user \
  roles/run.admin \
  roles/pubsub.publisher; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${SA}" --role="$ROLE" \
    --condition=None
done

د. به مامور CDA دسترسی به اسرار را اعطا کنید

ما از توکن گیت‌هاب و وب‌هوک Slack که قبلاً استفاده کردیم، دوباره استفاده خواهیم کرد و به حساب سرویس محاسباتی Cloud Run دسترسی به کلید API Gemini را اعطا می‌کنیم تا برنامه مستقر بتواند از آن استفاده کند: 

gcloud secrets add-iam-policy-binding github-token \
  --member="serviceAccount:${SA}" \
  --role="roles/secretmanager.secretAccessor"

gcloud secrets add-iam-policy-binding slack-webhook-cd \
  --member="serviceAccount:${SA}" \
  --role="roles/secretmanager.secretAccessor"

# Grant the compute service account access to Gemini API key
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud secrets add-iam-policy-binding gemini-api-key \
  --project=$PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

ه. ساخت و استقرار CDAgent در Cloud Run 

export GITHUB_OWNER="YOUR_GITHUB_USERNAME"

export CD_AGENT_URL=cd-agent-${PROJECT_NUMBER}.${CLOUD_RUN_REGION}.run.app

export SLACK_TOKEN=YOUR_SLACK_WEBHOOK
echo -n "https://hooks.slack.com/services/$SLACK_TOKEN" | \
  gcloud secrets create slack-webhook-cd --data-file=-

AGENT_IMAGE="$CLOUD_RUN_REGION-docker.pkg.dev/${PROJECT_ID}/dinoquest/cd-agent:latest"
gcloud builds submit --tag $AGENT_IMAGE .


export SA="cd-agent@${PROJECT_ID}.iam.gserviceaccount.com"


gcloud run deploy cd-agent \
  --image=$AGENT_IMAGE \
  --region=$CLOUD_RUN_REGION \
  --service-account=$SA \
  --memory=1Gi \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=True" \
  --set-env-vars="HOST=${CD_AGENT_URL},PROTOCOL=https" \
  --set-env-vars="CD_TARGET_SERVICE=dinoquest" \
  --set-env-vars="HARNESS_EVENTS_TOPIC=${HARNESS_EVENTS_TOPIC}" \
  --set-env-vars="GITHUB_OWNER=${GITHUB_OWNER}" \
  --set-env-vars="GITHUB_REPO=dinoquest" \
  --set-env-vars="DEMO_MODE=true" \
  --set-env-vars="LEADERBOARD_ENABLED=true" \
  --set-secrets="SLACK_WEBHOOK_URL=slack-webhook-cd:latest" \
  --set-secrets="GITHUB_TOKEN=github-token:latest" \
  --allow-unauthenticated \
  --min-instances=1 \
  --no-cpu-throttling \
  --timeout=300

نکته: --min-instances=1 --no-cpu-throttling نمونه را گرم نگه می‌دارد تا بتواند به سرعت به دستورات Slack و A2A پاسخ دهد.

CD Agent آخرین دروازه‌بان محیط تولید شما است. این عامل، ریسک هر استقرار را ارزیابی می‌کند، یک Canary کالیبره شده با ریسک را اجرا می‌کند و معیارهای بلادرنگ را رصد می‌کند. در صورت شناسایی هرگونه ناهنجاری، یک بازگشت خودکار را آغاز می‌کند.

۱۰. ارتقا: باز کردن قفل سطح ۲ با گروه ماموران

الف. کل گروه را آزمایش کنید

  1. خطا را فعال کنید : URL DinoQuest مستقر شده (از مرحله قبل) را در مرورگر خود باز کنید.
  2. رفتن به جدول امتیازات : روی دکمه‌ی جدول امتیازات کلیک کنید. پیاده‌سازی فعلی جدول امتیازات عمداً ناکارآمد است - سعی می‌کند حجم عظیمی از داده‌ها را در حافظه بارگذاری کند و باعث خطای کمبود حافظه (OOM) شود.
  3. منتظر عامل بمانید : ظرف حدود ۶۰ ثانیه، remediation-agent رویداد خطا را از طریق Eventarc دریافت کرده و تشخیص خود را آغاز می‌کند.
  4. بررسی Slack : باید اعلانی در کانال Slack خود مشاهده کنید که شبیه به این است: خلاصه‌ای از DinoAgent Remediation
    • سرویس : دینوکوئست
    • عدم موفقیت در ویرایش : dinoquest-xxxx-xxxx
    • مدرک : «با استفاده از ۱۳ برابر MiB، از محدودیت حافظه ۱۲۸ مگابایتی فراتر رفت.»
    • چرا این ویرایش بد بود : نقطه پایانی /api/leaderboard به طور ناکارآمد xxxxx بود و باعث خطای OOM می‌شد.
    • اقدام انجام شده : افزایش حافظه از xMi به yGi برای سرویس dinoquest . یک نسخه جدید ایجاد شد.
    • علت ریشه‌ای PR : https://github.com/YOUR_USERNAME/DinoQuest/pull/x
  5. اصلاحات را تأیید کنید :
    • گیت‌هاب : مخزن خود را برای شاخه جدید و درخواست Pull بررسی کنید. عامل، کد برنامه را برای رفع نشت حافظه اساسی، اصلاح کرده است.
    • Cloud Run : در کنسول GCP، نسخه جدیدی از سرویس dinoquest را با تخصیص حافظه به‌روز شده مشاهده خواهید کرد.
    • جدول امتیازات : دوباره جدول امتیازات را امتحان کنید - اکنون به لطف افزایش حافظه و رفع مشکل احتمالی کد، باید با موفقیت بارگیری شود.

ب. تکامل: پیاده‌سازی منطق بازی سطح ۲

شما یک ویژگی جدید و قابل توجه اضافه خواهید کرد: سطح ۲ (نابودگر سیارک) . این به دایناسورهای دارای امتیاز بالا اجازه می‌دهد تا به حالت بازی جدیدی ارتقا یابند.

  1. به مخزن dinoquest خود برگردید : 
    cd ~/dinoquest
  2. ایجاد و رفتن به یک شاخه جدید : 
    git checkout -b level_2
  3. اعمال پچ سطح ۲ : اسکریپت ارائه شده را اجرا کنید تا کدبیس محلی خود را با دارایی‌ها، کامپوننت‌ها و منطق بازی سطح ۲ پچ کنید: 
    bash level_2_backup/levelup.sh
  4. تغییرات را کامیت و پوش کنید : 
    git add .
git commit -m "feat: add Level 2"
git push origin level_2

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

  1. Slack را باز کنید و به هر کانالی که برنامه CIAgent در آن نصب شده است، بروید.
  2. با تایپ دستور زیر، ساخت CI را آغاز کنید : 
    /runci run ci on branch level_2
  3. پیشرفت را زیر نظر داشته باشید :
    • Slack : عامل، دستور شما را تأیید کرده و همزمان با پیشرفت ساخت، به‌روزرسانی‌ها را ارسال می‌کند.
    • تئاتر دایناسورها : «حباب‌های فکری» را تماشا کنید، زیرا عامل تغییر را طبقه‌بندی می‌کند، کار ساخت ابر را ارسال می‌کند و با عامل CD ارتباط برقرار می‌کند.
    • گیت‌هاب : PR level_2 خود را بررسی کنید؛ خواهید دید که عامل، وضعیت کامیت‌ها و یک نظر کامل در مورد گزارش CI را ارسال می‌کند.
  4. روند را تماشا کنید :
    • برای دیدن نحوه تفکر، طبقه‌بندی تغییر و اجرای خط لوله توسط عامل CI، به Dino Theater مراجعه کنید.
    • برای مشاهده‌ی وضعیت کامیت و گزارش نهایی توسط CI Agent، GitHub PR خود را بررسی کنید.

۱۱. نتیجه‌گیری

شما یک پشته DevOps کامل و agentic روی Google Cloud ساخته‌اید:

کامپوننت

چه کاری انجام می‌دهد؟

داینو کوئست ( dinoquest کوئست ابری)

بازی مبتنی بر Gemini - رابط کاربری React + رابط کاربری FastAPI

تأیید فایربیس + فایراستور

احراز هویت کاربر و ذخیره پروفایل دایناسور

عامل اصلاح (Cloud Run + Eventarc)

عامل SRE که به طور خودکار خطاهای OOM و اشکالات کد را اصلاح می‌کند

گزارش-روتر-bq

عامل داده‌ای که گزارش‌ها را به BigQuery منتقل می‌کند و بینش‌هایی ایجاد می‌کند

CIAgent (اجرای ابری)

عامل CI که تست‌های محدوده را انجام می‌دهد، تصاویر را می‌سازد و CD را از طریق A2A فراخوانی می‌کند

CDAgent (اجرای ابری)

عامل CD که Canary با ریسک امتیازدهی شده را اجرا می‌کند، با قابلیت بازگشت خودکار، استقرار می‌یابد.

تمام رفتارهای عامل در دایرکتوری skills/ به عنوان کتاب‌های راهنمای Markdown قرار دارند - رفتار را با ویرایش مهارت تغییر دهید، نه با ویرایش کد. مهارت‌ها با Gemini روی Antigravity اجرا می‌شوند و با گفتن اینکه کدام مهارت را اجرا کند، فراخوانی می‌شوند.