Quy trình công việc ưu tiên tác nhân – Từ câu lệnh đến sản phẩm

1. Tổng quan

Chào mừng bạn đến với "Ngày thứ hai". Mặc dù việc tạo một ứng dụng và nhấn vào "Xuất bản" là một điều kỳ diệu, nhưng lưu lượng truy cập thực tế sẽ mang đến những lỗi thực tế. Thay vì dành cả ngày để vật lộn với YAML hoặc tìm kiếm trong nhật ký, bạn có thể tạo một nhóm các tác nhân chuyên biệt để quản lý hệ thống vận hành cho bạn. Lớp học lập trình này cho bạn biết cách ngăn xếp hợp nhất của Google Cloud (Eventarc, Cloud Run, Firestore, Cloud Build, BigQuery) giúp các tác nhân dễ dàng tìm nạp thông tin bảo mật, truyền trực tuyến nhật ký và khắc phục các vấn đề ngay lập tức.

Tổng quan

Trong lớp học lập trình này, bạn sẽ xây dựng DinoQuest (một trò chơi phiêu lưu về khủng long dựa trên Gemini) từ đầu và kết nối trò chơi này với một quy trình CI/CD hoàn toàn tự động. Khi hoàn tất, bạn sẽ có:

  • Một ứng dụng web DinoQuest đang hoạt động chạy trên Cloud Run (tên dịch vụ: dinoquest)
  • Một quy trình phân tích nhật ký truyền nhật ký Cloud Run vào BigQuery và tạo một trang tổng quan tương tác về thông tin chi tiết về trò chơi
  • Tác nhân khắc phục (remediation-agent) – một tác nhân khắc phục ADK theo dõi các lỗi Cloud Run và tự động khắc phục các lỗi đó, được triển khai dưới dạng dịch vụ Cloud Run riêng do Eventarc kích hoạt
  • Một CI Agent (ci-agent) đọc điểm khác biệt PR, phạm vi kiểm thử một cách thông minh, tạo một hình ảnh Docker thông qua Cloud Build và đăng trạng thái cam kết trở lại GitHub
  • Một CD Agent (tác nhân CD) có khả năng tính điểm rủi ro triển khai, phân chia lưu lượng truy cập, giám sát các chỉ số và tự động thăng cấp hoặc khôi phục

Kiến thức bạn sẽ học được

  • Cách triển khai một ứng dụng Vite + FastAPI full-stack trên Cloud Run dưới dạng một vùng chứa duy nhất
  • Cách định cấu hình Xác thực Firebase và Firestore cho ứng dụng React
  • Cách tạo và triển khai một tác nhân ADK phản ứng với các sự kiện Pub/Sub thông qua Eventarc
  • Cách định tuyến nhật ký Cloud Run đến BigQuery và truy vấn số liệu phân tích về trò chơi
  • Cách viết các kỹ năng dựa trên tác nhân cho CI và triển khai thử nghiệm

Bạn cần có

  • Một dự án trên Google Cloud đã bật tính năng thanh toán
  • Một dự án Firebase (có thể là cùng một dự án GCP)
  • Một tài khoản GitHub và một bản sao của kho lưu trữ DinoQuest
  • Truy cập vào Antigravity bằng Gemini (trình chạy tác nhân của Google)
  • gcloud CLI đã được cài đặt và xác thực – xem hướng dẫn cài đặt bên dưới
  • node ≥ 18 và npm
  • python3 ≥ 3.11
  • git và gh (GitHub CLI)

Cài đặt gcloud CLI

macOS

brew install --cask google-cloud-sdk

Hoặc tải trình cài đặt xuống từ cloud.google.com/sdk/docs/install.

Windows

winget install Google.CloudSDK

Hoặc tải trình cài đặt Windows (.exe) xuống từ cloud.google.com/sdk/docs/install rồi kích hoạt.

Sau khi cài đặt, hãy khởi động và xác thực:

gcloud init
gcloud auth login
gcloud auth application-default login

2. Thiết lập Firebase

Mọi tác nhân đều cần dữ liệu để suy luận. DinoQuest sử dụng Firestore và Firebase Auth để cung cấp một lớp dữ liệu sẵn sàng cho hoạt động sản xuất mà các tác nhân của chúng tôi sẽ khám phá, tìm hiểu và cập nhật sau này bằng ngôn ngữ tự nhiên.

Vì ứng dụng này được tạo thông qua AI Studio, nên ứng dụng được tích hợp chặt chẽ với Firebase. Việc sử dụng Firebase mang lại một số lợi ích, trong đó có kiến trúc được bảo mật trước và quyền truy cập dữ liệu được quản lý ngay từ đầu, đảm bảo trạng thái của trò chơi được bảo vệ ngay từ ngày đầu tiên.

A. Tạo một dự án Firebase

  1. Truy cập vào console.firebase.google.com
  2. Nhấp vào Thêm dự án (Nút này nằm trong lựa chọn tạo dự án mới) → chọn dự án GCP hiện có (hoặc tạo một dự án mới)
  3. Tắt Google Analytics nếu được nhắc → Tạo dự án (Hoặc bạn có thể chọn chế độ cài đặt mặc định)

B. Bật tính năng Xác thực bằng Google

  1. Trong bảng điều khiển của Firebase, hãy chuyển đến Bảo mật → Xác thực (Bắt đầu) → Phương thức đăng nhập
  2. Nhấp vào Google → bật chế độ Bật → lưu email hỗ trợ → Lưu

C. Thêm localhost làm miền được uỷ quyền

  1. Vẫn trong phần Xác thực, hãy nhấp vào thẻ Cài đặt
  2. Trong phần Miền được uỷ quyền, hãy xác nhận rằng localhost có trong danh sách (theo mặc định, miền này sẽ có trong danh sách)

D. Tạo cơ sở dữ liệu Firestore

  1. Chuyển đến Cơ sở dữ liệu và bộ nhớ → Cơ sở dữ liệu Firestore → Tạo cơ sở dữ liệu
  2. Chọn Phiên bản tiêu chuẩn → Tiếp theo
  3. Chọn khu vực us-central1 (hoặc chọn khu vực phù hợp với khu vực Cloud Run của bạn)
  4. Chọn Start in production mode (Bắt đầu ở chế độ phát hành công khai) → Create (Tạo)

Sau khi tạo, hãy ghi lại Mã cơ sở dữ liệu. Mã này sẽ có dạng (default) trừ phi bạn đã đặt tên cho cơ sở dữ liệu.

E. Đặt các quy tắc bảo mật của Firebase

Trong Firestore Database → Rules (Cơ sở dữ liệu Firestore → Quy tắc), hãy thay thế các quy tắc mặc định bằng:

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

Nhấp vào Xuất bản.

F. Thêm một ứng dụng web và nhận cấu hình

  1. Chuyển đến phần Cài đặt dự án (biểu tượng bánh răng) → thẻ Chung
  2. Di chuyển đến Ứng dụng của bạn → nhấp vào Thêm ứng dụng → chọn biểu tượng Web ()
  3. Đặt tên cho tệp là dinoquest → Đăng ký ứng dụng
  4. Sao chép đối tượng firebaseConfig xuất hiện – bạn sẽ cần đối tượng này trong giây lát

3. Chạy trò chơi

Vai trò của nhân viên hỗ trợ: Môi trường. Trước khi có thể thiết lập để các tác nhân hoạt động, chúng ta cần có một thế giới để chúng quản lý. Trong bước này, chúng ta sẽ triển khai phiên bản "Ngày đầu tiên" của DinoQuest. Thao tác này sẽ tạo ra dịch vụ, nhật ký và trạng thái trực tiếp mà nhóm của chúng ta sẽ khám phá và quản lý sau này.

Tổng quan

Chọn một trong hai lựa chọn bên dưới. Tạo ra một GEMINI_API_KEY mà bạn sử dụng giống hệt nhau trong mọi bước sau này – không cần thay đổi gì khác.

A. Thiết lập khoá Gemini API

Vertex AI cho phép bạn tạo khoá Gemini API được liên kết trực tiếp với dự án GCP của bạn và được tính phí cho dự án đó, bằng cách sử dụng tài khoản dịch vụ mặc định của dự án mà không cần tài khoản AI Studio riêng.

  1. Xuất mã dự án của bạn trên Google Cloud Platform:
    export PROJECT_ID=<YOUR_PROJECT_ID>
  2. Bật các API bắt buộc và cấp các quyền cần thiết cho tài khoản dịch vụ mặc định của 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. Mở trang khoá API Vertex AI trong Cloud Console
  4. Nhấp vào Tạo thông tin xác thực → chọn Khoá API
  5. Trong hộp thoại tạo, hãy làm như sau:
    • Đặt tên cho khoá là Dino_Key
    • Chọn hộp Xác thực các lệnh gọi API thông qua tài khoản dịch vụ
    • Trong mục Tài khoản dịch vụ, hãy chọn tài khoản dịch vụ điện toán mặc định (PROJECT_NUMBER-compute@developer.gserviceaccount.com)
    • Trong phần Chọn hạn chế cho API, hãy đánh dấu vào GEMINI API
    • Nhấp vào Tạo
  6. Sao chép khoá đã tạo.

Lựa chọn B – AI Studio (nhanh nhất cho quá trình phát triển cục bộ)

  1. Truy cập vào aistudio.google.com
  2. Nhấp vào Lấy khoá API trong thanh bên trái
  3. Nhấp vào Tạo khoá API → chọn dự án của bạn trên GCP → sao chép khoá

Một trong hai khoá được đặt là GEMINI_API_KEY trong các bước tiếp theo – phần phụ trợ sẽ xử lý chúng giống nhau.

Sao chép kho lưu trữ

Kho lưu trữ của khoá học nằm trong https://github.com/gca-americas/dinoquest. Trước tiên, vui lòng phát triển nhánh tệp này vào tài khoản GitHub của riêng bạn. Thay vào đó, chúng tôi sẽ để tác nhân xử lý kho lưu trữ của bạn.

Sau khi phân nhánh, hãy sao chép nhánh main của kho lưu trữ DinoQuest đã phân nhánh và nhập thư mục dự án:

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

B. Thiết lập các biến môi trường

Trong mọi thiết bị đầu cuối bash mới mà bạn mở trong lớp học lập trình này, hãy nhớ đặt các biến môi trường thiết yếu này. Thay thế các giá trị trình giữ chỗ bằng thông tin chi tiết thực tế về dự án của bạn:

Trước tiên, hãy xuất URL kho lưu trữ GitHub:

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

Sau đó, hãy xuất các biến môi trường còn lại:

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

Xác nhận rằng cấu trúc trông chính xác:

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

B. Tạo tệp môi trường phụ trợ

Trước tiên, hãy xuất khoá Gemini API:

export GEMINI_API_KEY=YOUR_GEMINI_API_KEY_FROM_STEP_2

Sau đó, hãy tạo tệp .env:

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

C. Bật tính năng Kiểm tra ứng dụng Firebase / Tài khoản dịch vụ (cho Cloud Run)

Khi chạy trên Cloud Run, phần phụ trợ sẽ sử dụng Thông tin xác thực mặc định của ứng dụng để giao tiếp với Firebase mà không cần tệp khoá tài khoản dịch vụ. Cuộc gọi firebase_admin.initialize_app() trong backend/main.py sẽ tự động nhận cuộc gọi này.

Đối với quá trình phát triển cục bộ, hãy xác thực một lần:

gcloud auth application-default login

D. Tạo tệp cấu hình ứng dụng Firebase

Trong thư mục frontend/, hãy tạo firebase-applet-config.json bằng cấu hình của bạn ở bước trước:

{
  "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)"
}

Lưu ý: firestoreDatabaseId phải khớp với mã nhận dạng cơ sở dữ liệu mà bạn đã tạo ở bước trước. Nếu bạn sử dụng giá trị mặc định, hãy giữ nguyên là "(default)".

Đưa các thay đổi trở lại kho lưu trữ của bạn:

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

C. Chạy DinoQuest cục bộ

1. Bật các API bắt buộc

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

2. Bắt đầu DinoQuest

Tập lệnh start.sh tạo giao diện người dùng React và chuyển thiết bị đầu cuối sang phần phụ trợ FastAPI, nơi phân phát các tệp tĩnh đã biên dịch:

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

Mở http://localhost:8000 trong trình duyệt. Bạn sẽ thấy màn hình tiêu đề DinoQuest. Đăng nhập bằng Google, tạo khủng long đầu tiên và xác nhận rằng khủng long đó được lưu vào Firestore.

Khắc phục sự cố: Nếu bạn thấy một trang trống hoặc lỗi xác thực Firebase, hãy kiểm tra kỹ để đảm bảo rằng frontend/firebase-applet-config.json có các giá trị chính xác và localhost nằm trong danh sách các miền được uỷ quyền.

E. Triển khai DinoQuest lên Cloud Run

1. Thiết lập dự án

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

3. Tạo một kho lưu trữ Artifact Registry

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

4. Lưu trữ khoá Gemini API trong 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"

5. Tạo hình ảnh vùng chứa bằng Cloud Build

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

Thao tác này sẽ chạy Dockerfile nhiều giai đoạn: trước tiên, thao tác này sẽ tạo ứng dụng React, sau đó đóng gói đầu ra vào hình ảnh FastAPI. Quá trình này mất khoảng 3 đến 5 phút.

6. Triển khai lên Cloud Run

Trước tiên, hãy xuất email của quản trị viên:

export ADMIN_EMAIL=<YOUR_TEST_ACCOUNT_EMAIL>

Sau đó, hãy triển khai dịch vụ:

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"

Khi lệnh hoàn tất, Cloud Run sẽ in một URL dịch vụ. Sao chép URL này – bạn sẽ cần URL này để uỷ quyền cho miền trong Firebase.

7. Uỷ quyền cho miền Cloud Run trong Firebase

Để cho phép người dùng đăng nhập từ ứng dụng đã triển khai, bạn phải thêm URL Cloud Run vào các miền được uỷ quyền của Firebase:

  1. Quay lại bảng điều khiển của Firebase → Xác thực → Cài đặt → Miền được uỷ quyền
  2. Nhấp vào Thêm miền
  3. Dán URL dịch vụ Cloud Run của bạn (ví dụ: dinoquest-xxxxx.us-central1.run.app) – xoá tiền tố https://
  4. Nhấp vào Lưu

8. Gieo dữ liệu Bảng xếp hạng

Để trò chơi của bạn có một số "sự sống" ban đầu và đảm bảo các tác nhân của bạn có dữ liệu, bạn có thể gieo một số điểm số ban đầu vào bảng xếp hạng.

  1. Đảm bảo bạn đang ở thư mục gốc dinoquest:
    cd ~/dinoquest
  2. Tạo và kích hoạt môi trường ảo:
    python3 -m venv venv
source venv/bin/activate
  3. Cài đặt phần phụ thuộc Firestore bắt buộc:
    pip install google-cloud-firestore
  4. Chạy tập lệnh gieo hạt:
    python3 prep/seed_scores.py
  5. Huỷ kích hoạt môi trường ảo:
    deactivate

Giờ đây, bạn có thể mở URL dịch vụ trong trình duyệt của mình – DinoQuest đã hoạt động đầy đủ!

4. Thiết lập Rạp chiếu phim Dino

Vai trò của nhân viên hỗ trợ: Người trực quan hoá. Làm cách nào để giám sát một nhóm gồm các đặc vụ tự trị? Dino Theater cung cấp một cửa sổ theo thời gian thực để bạn có thể quan sát cách các tác nhân của mình hoạt động. Thay vì nhìn chằm chằm vào nhật ký trên thiết bị đầu cuối, bạn có thể xem các tác nhân suy luận, gọi cho nhau và thực hiện các tác vụ trên đám mây trong một trang tổng quan trực quan, trực tiếp.

Tổng quan

A. Triển khai Dino Theater lên Cloud Run

Trước tiên, hãy quay lại thư mục chính rồi sao chép mã Dino Theater:

cd ~
git clone https://github.com/gca-americas/dinoquest-theater.git
cd dinoquest-theater
  1. Tạo và đẩy vùng chứa:
    gcloud builds submit --tag $CLOUD_RUN_REGION-docker.pkg.dev/$PROJECT_ID/dinoquest/dino-theater:latest .
  2. Thiết lập tài khoản dịch vụ và quyền:
    # 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. Triển khai ứng dụng:
    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
    Lưu ý: Bạn nên giữ kết nối SSE hoạt động giữa các sự kiện.    --min-instances=1
  4. Xác minh xem URL này có hoạt động hay không: Mở URL của dịch vụ đã triển khai trong trình duyệt (ví dụ: https://dino-theater-xxx-uc.a.run.app/demo).

5. DevOps dựa trên tác nhân trong IDE

Vai trò của nhân viên: Native Antigravity. Để thu hẹp khoảng cách giữa IDE và đám mây, chúng tôi kết nối Antigravity với các máy chủ MCP được quản lý của Google Cloud. Điều này giúp tác nhân gốc của bạn có "mắt" để nhìn vào dự án, cho phép tác nhân này phân tích cú pháp nhật ký, kiểm tra các chỉ số và suy luận về cơ sở hạ tầng mà bạn không cần phải xử lý khoá API hoặc chuyển đổi ngữ cảnh sang bảng điều khiển.

Trước khi chạy bất kỳ kỹ năng nào, bạn cần định cấu hình quyền truy cập của Antigravity vào Google Cloud và tải sổ tay kỹ năng DinoQuest.

A. Cài đặt dịch vụ MCP được quản lý của Google

Dịch vụ MCP được quản lý của Google cung cấp quyền truy cập vào tất cả các API của Google Cloud thông qua một điểm cuối được lưu trữ duy nhất.

Xác thực bằng Thông tin xác thực mặc định của ứng dụng:

gcloud auth application-default login

B. Định cấu hình mcp_config.json

Tạo hoặc cập nhật mcp_config.json trong thư mục cấu hình Antigravity (thường là ~/.gemini/antigravity/mcp_config.json) hoặc từ bảng điều khiển. Điều này cho phép Antigravity truy cập vào các công cụ của Google Cloud và GitHub mà các kỹ năng cần:

{
  "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"
    }
  }
}

C. Tải các kỹ năng vào Antigravity (Không bắt buộc)

Antigravity phát hiện các kỹ năng trong các thư mục chuẩn cụ thể. Sao chép các kỹ năng DinoQuest từ kho lưu trữ đã sao chép vào thư mục kỹ năng Antigravity chung:

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

D. Khởi động lại Antigravity(Không bắt buộc)

Để áp dụng các thay đổi mcp_config.json và tải các kỹ năng mới sao chép, hãy khởi động lại ứng dụng Antigravity.

Sau khi khởi động lại:

  1. Xác minh rằng các máy chủ MCP google và github có trạng thái "Đã kết nối" màu xanh lục trong phần Cài đặt.
  2. Kiểm tra để đảm bảo kỹ năng DinoQuest xuất hiện trong danh sách kỹ năng của bạn.

Lưu ý: Mỗi kỹ năng đều có một bảng ## Configuration ở đầu SKILL.md. Sau khi sao chép, bạn nên cập nhật các giá trị trong ~/.gemini/antigravity/skills//SKILL.md cho khớp với dự án của mình.

E. Khắc phục dịch vụ đám mây trong IDE cục bộ

  1. Kích hoạt lỗi: Mở URL DinoQuest đã triển khai (từ bước cuối cùng) trong trình duyệt.
  2. Chuyển đến Bảng xếp hạng: Nhấp vào nút Bảng xếp hạng. Việc triển khai bảng xếp hạng hiện tại cố ý không hiệu quả – bảng xếp hạng này sẽ cố gắng tải một lượng lớn dữ liệu vào bộ nhớ, kích hoạt lỗi Hết bộ nhớ (OOM).
  3. Trong Antigravity Agent Manager (Agent HUB), hãy yêu cầu công cụ này giúp khắc phục lỗi và có thể sửa nguyên nhân gốc rễ.
  • Câu lệnh 1: Tìm hiểu xem dinoquest có vấn đề gì.
  • Câu lệnh 2: Bạn có thể xem mã của trò chơi Dinoquest và khắc phục nguyên nhân gây ra lỗi hết bộ nhớ không?

6. Truyền trực tuyến nhật ký sang BigQuery và tạo số liệu phân tích

Vai trò của nhân viên hỗ trợ: Nhân viên hỗ trợ dữ liệu. Việc chuyển đổi nhật ký thô thành chiến lược sản phẩm hữu ích không nên mất hàng giờ để xử lý dữ liệu theo cách thủ công. Bằng cách sử dụng Data Agent Kit và BigQuery MCP, chúng tôi tạo một pipeline "Zero ETL" (Không cần trích xuất, chuyển đổi và tải dữ liệu) để truyền trực tiếp nhật ký vào BigQuery, cho phép tác nhân tạo trang tổng quan số liệu phân tích cao cấp trong vòng chưa đầy 2 phút.

Kỹ năng log-router-bq-report thiết lập một đích nhận Cloud Logging liên tục truyền nhật ký Cloud Run của DinoQuest vào BigQuery, sau đó truy vấn dữ liệu để tạo báo cáo lưu lượng truy cập và thông tin chi tiết về hoạt động phân tích trò chơi.

Tổng quan

A. Định cấu hình các biến kỹ năng

Mở skills/log-router-bq-report/SKILL.md trong kho lưu trữ DinoQuest rồi cập nhật phần Configuration (Cấu hình) ở trên cùng:

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

B. Chạy kỹ năng trong Antigravity

Mở Antigravity với kho lưu trữ DinoQuest làm bối cảnh và yêu cầu Gemini:

Run the log-router-bq-report skill

Kỹ năng này sẽ:

  1. Tự động giải quyết dự án GCP
  2. Kiểm tra xem đích BigQuery đã tồn tại hay chưa – nếu chưa, thì đích này sẽ tạo tập dữ liệu và đích.
  3. Cấp quyền IAM: Thao tác này sẽ cấp cho writerIdentity của đích nhận vai trò Người chỉnh sửa dữ liệu BigQuery đối với tập dữ liệu.

Lưu ý: Tương tự như đích Eventarc, bạn có thể thấy cảnh báo từ gcloud trong quá trình này: "Hãy nhớ cấp cho serviceAccount:service-... vai trò Người chỉnh sửa dữ liệu BigQuery đối với tập dữ liệu." Kỹ năng này sẽ tự động xử lý việc này.

C. Sử dụng Antigravity để tạo báo cáo

Bạn chỉ cần yêu cầu Antigravity "thiết lập bồn lưu trữ dữ liệu nhật ký BigQuery và tạo báo cáo số liệu phân tích". Nhân viên hỗ trợ sẽ:

  1. Định cấu hình cơ sở hạ tầng: Tạo tập dữ liệu BigQuery và nguồn Cloud Logging.
  2. Quản lý quyền: Tự động cấp các vai trò IAM cần thiết cho danh tính người ghi của đích nhận.
  3. Tạo thông tin chi tiết: Phân tích nhật ký và tạo một trang tổng quan HTML tương tác, cao cấp với số liệu đo từ xa về trò chơi và phân tích tỷ lệ thắng.

7. Tác nhân khắc phục tự phục hồi

Vai trò của nhân viên hỗ trợ: Nhân viên hỗ trợ SRE. Khi một dịch vụ sản xuất gặp lỗi lúc 2 giờ sáng, bạn không cần phải thức dậy. Tác nhân này đóng vai trò là nhân viên ứng cứu đầu tiên. Được kích hoạt bởi nhật ký lỗi Cloud Run thông qua Eventarc, công cụ này sẽ tự động phân tích sự cố, đề xuất cách khắc phục và khởi động quy trình khắc phục – tất cả đều diễn ra trước khi bạn đăng nhập vào bảng điều khiển.

DinoAgent là một tác nhân ADK lắng nghe nhật ký lỗi Cloud Run thông qua Eventarc, chẩn đoán nguyên nhân gốc và tự động khắc phục – bằng cách tăng bộ nhớ, khôi phục lưu lượng truy cập hoặc gửi yêu cầu kéo bản sửa lỗi mã trên GitHub.

Tổng quan

A. Sao chép kho lưu trữ Remediation Agent

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

Cấu trúc dự án:

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

B. Thiết lập quyền truy cập vào GitHub (làn đường sửa lỗi)

Theo dõi việc sửa lỗi mã sẽ sao chép kho lưu trữ DinoQuest, đọc tệp nguồn, áp dụng các bản vá và mở các yêu cầu kéo. Bạn cần có Mã truy cập cá nhân GitHub với phạm vi repo.

  1. Truy cập vào github.com/settings/tokens → Generate new token (classic) (Tạo mã thông báo mới (cổ điển))
  2. Đặt tên cho khoá truy cập, chọn phạm vi repo → Tạo mã thông báo → sao chép mã thông báo đó

Lưu trữ trong Secret Manager:

Trước tiên, hãy xuất mã thông báo GitHub:

export GH_TOKEN=ghp_YOUR_TOKEN_HERE

Sau đó, hãy tạo mã bí mật:

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

C. Thiết lập thông báo trên Slack (không bắt buộc)

Khi quá trình khắc phục hoàn tất, DinoAgent sẽ đăng thông tin tóm tắt lên một kênh Slack.

  1. Truy cập vào api.slack.com/apps → Create New App (Tạo ứng dụng mới) → From scratch (Từ đầu)
  2. Đặt tên cho ứng dụng DinoAgent, chọn không gian làm việc → Tạo ứng dụng
  3. Trong phần Tính năng → Webhook đến → bật
  4. Nhấp vào Thêm webhook mới vào không gian làm việc → chọn một kênh → Cho phép
  5. Sao chép URL webhook (https://hooks.slack.com/services/...)

Lưu trữ trong Secret Manager:

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

D. Tạo tài khoản dịch vụ 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

Cấp cho ứng dụng quyền truy cập vào các giá trị bí mật:

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

E. Tạo và triển khai DinoAgent lên 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

F. Kết nối trình kích hoạt Eventarc

Tạo một chủ đề Pub/Sub để nhận nhật ký lỗi Cloud Run:

gcloud pubsub topics create cloud-run-errors

Tạo một đích nhận Cloud Logging để lọc nhật ký lỗi từ dịch vụ dinoquest và định tuyến nhật ký đó đến chủ đề:

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"

Lưu ý: Khi bạn chạy lệnh trên, gcloud sẽ in một thông báo Thông tin có nội dung: "Vui lòng nhớ cấp cho serviceAccount:service-... vai trò Nhà xuất bản Pub/Sub trên chủ đề." Bước tiếp theo sẽ xử lý chính xác vấn đề đó.

Cấp cho danh tính người ghi của đích nhận (tài khoản dịch vụ được đề cập trong cảnh báo) quyền xuất bản:

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"

Xác minh xem tính năng này có đang hoạt động hay không:

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

Cấp cho Eventarc quyền gọi tác nhân khắc phục:

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

Tạo điều kiện kích hoạt 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}

Giờ đây, quy trình khắc phục đã hoàn toàn tự động. Ngoài việc chỉ mở rộng quy mô cơ sở hạ tầng, DinoAgent còn thực hiện phân tích sâu về nguyên nhân gốc rễ đối với mã xử lý ứng dụng, áp dụng bản vá ngữ nghĩa và sử dụng giao tiếp Agent-to-Agent (A2A) để chuyển bản sửa lỗi cho CI Agent nhằm xác minh và triển khai. Bạn có thể khám phá thông tin chi tiết về cách triển khai trong cơ sở mã reme-agent.

8. Thiết lập tác nhân CI

Vai trò của tác nhân: Quy trình CI. Không cần phải vật lộn với các tệp YAML phức tạp và tập lệnh bản dựng thủ công. Tác nhân này quản lý cơ sở hạ tầng hoạt động của các yêu cầu kéo. Công cụ này đọc các thay đổi về mã của bạn, hiểu ngữ cảnh, xác định phạm vi các kiểm thử cần thiết và tạo hình ảnh Docker thông qua Cloud Build, đảm bảo mọi cam kết đều được "đại lý phê duyệt" trước khi đến nhánh chính.

ci-agent là một tác nhân quy trình CI tự động được triển khai dưới dạng một dịch vụ Cloud Run. Công cụ này gửi các bản dựng Docker đến Cloud Build, thăm dò ý kiến để hoàn tất, xác minh hình ảnh trong Artifact Registry và báo cáo cho GitHub.

Tổng quan

Tại sao nên sử dụng một tác nhân cho quy trình CI? Không giống như các tập lệnh tĩnh truyền thống, quy trình CI dựa trên tác nhân cung cấp:

  1. Phân loại phạm vi nhận thức: Tính năng này xác định một cách thông minh độ sâu cần thiết của quy trình kiểm thử (chuyển đổi giữa các quy trình kiểm tra loại, kiểm thử đơn vị hoặc bộ kiểm thử tích hợp đầy đủ) dựa trên tác động về ngữ nghĩa của các thay đổi về mã.
  2. Quản lý PR tự động: Tác nhân có thể tự động tạo PR, đăng bản tóm tắt chi tiết về các thay đổi, thậm chí quản lý quy trình quét bí mật và kiểm tra bảo mật mà không cần sự can thiệp của con người.
  3. Chẩn đoán lỗi theo thời gian thực: Khi một bản dựng gặp lỗi, tác nhân không chỉ hiển thị nhật ký mà còn phân tích dấu vết ngăn xếp, xác định nguyên nhân có thể xảy ra và đăng thông tin chẩn đoán dễ đọc trực tiếp lên yêu cầu kéo.

A. Sao chép kho lưu trữ CIAgent

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

B. Tạo tài khoản dịch vụ 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"

C. Kết nối kho lưu trữ GitHub với Cloud Build

CIAgent gửi bản dựng thông qua repoSource. Để làm được việc này, bạn cần kết nối kho lưu trữ GitHub với Cloud Build Developer Connect.

  1. Chuyển đến Bảng điều khiển GCP → Cloud Build → Kho lưu trữ
  2. Nhấp vào Kết nối kho lưu trữ
  3. Chọn GitHub (Ứng dụng GitHub Cloud Build)
  4. Uỷ quyền và chọn kho lưu trữ YOUR_GITHUB_USERNAME/dinoquest
  5. Nhấp vào Kết nối và Bỏ qua khi được nhắc tạo điều kiện kích hoạt.
  6. Ghi lại tên kết nối của bạn (theo mặc định, tên này thường là tên người dùng GitHub hoặc tên tương tự).

D. Cấp quyền truy cập vào các giá trị bí mật cho CIAgent

Chúng ta sẽ dùng lại các khoá bí mật đã tạo trước đó cho 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"

E. Tạo và triển khai CIAgent lên 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

F. Thiết lập lệnh dấu gạch chéo trên Slack

  1. Truy cập vào api.slack.com/apps → Create New App (Tạo ứng dụng mới) → From scratch (Từ đầu)
  2. Đặt tên cho ứng dụng CIAgent, chọn không gian làm việc → Tạo ứng dụng
  3. Trong phần Tính năng → Lệnh dấu gạch chéo → Tạo lệnh mới
  4. Lệnh: /runci
  5. URL yêu cầu: URL CIAgent Cloud Run của bạn ở trên có thêm /slack (ví dụ: https://ci-agent-xxx-.us-central1.run.app/slack)
  6. Mô tả ngắn: Trigger CI
  7. Lưu
  8. Trong phần Cài đặt → Cài đặt ứng dụng, hãy nhấp vào Cài đặt vào Workspace rồi nhấp vào Cho phép.

Tác nhân CI đóng vai trò là "bộ não" nằm trên các dịch vụ mạnh mẽ của Google Cloud như Cloud Build và Artifact Registry. Sau khi bản dựng được xác minh, bản dựng sẽ kích hoạt giai đoạn triển khai cuối cùng bằng cách gọi CD Agent thông qua A2A, đảm bảo quá trình chuyển giao liền mạch giữa các chu kỳ bản dựng và phát hành.

9. Thiết lập quy trình triển khai

Vai trò của nhân viên hỗ trợ: Nhân viên hỗ trợ CD. Không nên triển khai một cách mù quáng. Tác nhân này sẽ quản lý rủi ro cho bạn. Nó tính điểm mức độ an toàn khi triển khai, quản lý việc phân chia lưu lượng truy cập theo phương pháp phát hành thử nghiệm và giám sát các chỉ số theo thời gian thực để quyết định có nên phát hành hay quay lại một bản phát hành hay không. Đây là người kiểm soát cuối cùng trong nhóm tác nhân tự trị của bạn.

cd-agent là một tác nhân triển khai thử nghiệm độc lập được triển khai dưới dạng một dịch vụ Cloud Run. Nó nhận các yêu cầu triển khai A2A từ ci-agent, tính toán điểm số rủi ro, đặt tỷ lệ canary được điều chỉnh theo rủi ro, giám sát các chỉ số và tự động quảng bá hoặc khôi phục. Ứng dụng này cũng học hỏi từ các hoạt động triển khai trước đây bằng cách sử dụng Firestore.

Tổng quan

Việc kết nối trực tiếp các tác nhân sẽ tạo ra một "quy trình nhận thức", trong đó mỗi lần chuyển giao là một lần chuyển giao phong phú về ý định và bối cảnh. Không giống như webhook truyền thống, giao tiếp A2A cho phép:

  1. Chia sẻ bối cảnh thông minh: Các tác nhân truyền toàn bộ bộ nhớ phiên, chênh lệch PR và điểm số rủi ro, đảm bảo tác nhân tiếp theo có đầy đủ thông tin "tại sao" trước khi bắt đầu công việc.
  2. Cognitive Handshakes (Bắt tay nhận thức): Các tác nhân có thể thương lượng các cổng. Ví dụ: CD Agent có thể yêu cầu CI Agent thực hiện các kiểm thử nhanh cụ thể trong quá trình triển khai canary để xác minh bản sửa lỗi theo thời gian thực.
  3. Khắc phục cộng tác: Nếu quá trình triển khai không thành công, CD Agent có thể chủ động thông báo cho Remediation Agent về các chỉ số không thành công, bắt đầu phân tích nguyên nhân gốc rễ một cách tự động trước khi có người được thông báo.
  4. Thương lượng về tài nguyên: Các tác nhân có thể thương lượng về nhu cầu cơ sở hạ tầng. Ví dụ: CI Agent có thể yêu cầu Remediation Agent cung cấp thêm dung lượng bản dựng nếu phát hiện thấy một hoạt động cải tiến quy mô lớn, hoặc CD Agent có thể đề xuất mở rộng quy mô cụm phát hành công khai trước khi phát hành một bản phát hành chính.
  5. Sự đồng thuận của nhiều tác nhân: Đối với những thay đổi có mức độ rủi ro cao, nhiều tác nhân (ví dụ: Tác nhân bảo mật và Tác nhân CD) có thể thực hiện "quy trình phê duyệt chung" thông qua A2A, đảm bảo rằng mã không chỉ được tạo và triển khai mà còn tuân thủ các chính sách bảo mật trước khi được đưa vào sản xuất.

A. Sao chép kho lưu trữ CDAgent

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

B. Tạo cơ sở dữ liệu Firestore

CDAgent lưu trữ các mẫu bộ nhớ triển khai trong Firestore:

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

(Nếu đã tạo cơ sở dữ liệu trong dự án này, bạn có thể bỏ qua bước này.)

C. Tạo tài khoản dịch vụ 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

D. Cấp quyền truy cập vào các giá trị bí mật cho CDAgent

Chúng ta sẽ sử dụng lại mã thông báo GitHub và webhook Slack từ trước đó, đồng thời cấp cho tài khoản dịch vụ điện toán Cloud Run quyền truy cập vào Khoá API Gemini để ứng dụng đã triển khai có thể sử dụng khoá này:

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"

E. Tạo và triển khai CDAgent lên 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

Lưu ý: --min-instances=1 --no-cpu-throttling giữ cho phiên bản luôn ở trạng thái sẵn sàng để có thể nhanh chóng phản hồi các lệnh trên Slack và A2A.

CD Agent là người kiểm soát cuối cùng của môi trường thực tế. Nó đánh giá rủi ro của từng hoạt động triển khai, thực thi canary được hiệu chỉnh theo rủi ro và giám sát các chỉ số theo thời gian thực. Nếu phát hiện thấy bất kỳ điểm bất thường nào, hệ thống sẽ bắt đầu quá trình khôi phục tự động.

10. Mở rộng quy mô: Mở khoá Cấp độ 2 bằng Nhóm tác nhân

A. Kiểm thử Full Swarm

  1. Kích hoạt lỗi: Mở URL DinoQuest đã triển khai (từ bước cuối cùng) trong trình duyệt.
  2. Chuyển đến Bảng xếp hạng: Nhấp vào nút Bảng xếp hạng. Việc triển khai bảng xếp hạng hiện tại cố ý không hiệu quả – bảng xếp hạng này sẽ cố gắng tải một lượng lớn dữ liệu vào bộ nhớ, kích hoạt lỗi Hết bộ nhớ (OOM).
  3. Chờ Agent: Trong khoảng 60 giây, remediation-agent sẽ nhận được sự kiện lỗi thông qua Eventarc và bắt đầu chẩn đoán.
  4. Kiểm tra Slack: Bạn sẽ thấy một thông báo trong kênh Slack của mình có dạng như sau:DinoAgent Remediation Summary (Tóm tắt về biện pháp khắc phục của DinoAgent)
    • Dịch vụ: dinoquest
    • Bản sửa đổi không thành công: dinoquest-xxxx-xxxx
    • Bằng chứng: "Đã vượt quá giới hạn bộ nhớ 128 MiB với 13x MiB được sử dụng."
    • Lý do bản sửa đổi này không phù hợp: Điểm cuối /api/leaderboard đã xxxxx một cách không hiệu quả, gây ra lỗi OOM.
    • Hành động đã thực hiện: Tăng bộ nhớ từ xMi lên yGi cho dịch vụ dinoquest. Một bản sửa đổi mới đã được tạo.
    • PR nguyên nhân gốc rễ: https://github.com/YOUR_USERNAME/DinoQuest/pull/x
  5. Xác minh kết quả sửa lỗi:
    • GitHub: Kiểm tra kho lưu trữ của bạn để tìm một nhánh mới và một Yêu cầu hợp nhất. Tác nhân đã vá mã xử lý ứng dụng để khắc phục tình trạng rò rỉ bộ nhớ cơ bản.
    • Cloud Run: Trong Bảng điều khiển GCP, bạn sẽ thấy một bản sửa đổi mới của dịch vụ dinoquest với mức phân bổ bộ nhớ đã cập nhật.
    • Bảng xếp hạng: Thử lại bảng xếp hạng. Giờ đây, bảng xếp hạng sẽ tải thành công nhờ bộ nhớ tăng lên và bản sửa lỗi mã cuối cùng.

B. Tiến hoá: Triển khai logic trò chơi cấp 2

Bạn sẽ thêm một tính năng mới quan trọng: Cấp độ 2 (Tiểu hành tinh huỷ diệt). Nhờ đó, những chú khủng long đạt điểm cao có thể chuyển sang một chế độ chơi mới.

  1. Quay lại kho lưu trữ dinoquest: 
    cd ~/dinoquest
  2. Tạo và chuyển sang một nhánh mới: 
    git checkout -b level_2
  3. Áp dụng bản vá Cấp 2: Chạy tập lệnh được cung cấp để vá cơ sở mã cục bộ bằng các thành phần, tài sản và logic trò chơi Cấp 2: 
    bash level_2_backup/levelup.sh
  4. Xác nhận và đẩy các thay đổi: 
    git add .
git commit -m "feat: add Level 2"
git push origin level_2

Thay vì dùng curl để kích hoạt tác nhân theo cách thủ công, chúng ta sẽ dùng Lệnh gạch chéo của Slack mà bạn đã định cấu hình trước đó. Đây là cách bạn tương tác với quy trình CI tự động trong một tình huống thực tế.

  1. Mở Slack rồi chuyển đến một kênh bất kỳ có cài đặt ứng dụng CIAgent.
  2. Kích hoạt bản dựng CI bằng cách nhập lệnh sau:
    /runci run ci on branch level_2
  3. Theo dõi tiến trình:
    • Slack: Agent sẽ xác nhận lệnh của bạn và đăng thông tin cập nhật khi bản dựng tiến hành.
    • Dino Theater: Xem "bong bóng suy nghĩ" khi tác nhân phân loại thay đổi, gửi công việc Cloud Build và giao tiếp với tác nhân CD.
    • GitHub: Kiểm tra level_2 PR của bạn; bạn sẽ thấy tác nhân đăng trạng thái cam kết và một bình luận báo cáo CI đầy đủ.
  4. Xem quy trình:
    • Kiểm tra Dino Theater để xem CI Agent suy nghĩ, phân loại thay đổi và chạy quy trình.
    • Kiểm tra yêu cầu kéo (PR) trên GitHub để xem CI Agent đăng trạng thái cam kết và báo cáo cuối cùng.

11. Kết luận

Bạn đã tạo một ngăn xếp DevOps dựa trên tác nhân hoàn chỉnh trên Google Cloud:

Thành phần

Ý nghĩa

DinoQuest (Cloud Run dinoquest)

Trò chơi dựa trên Gemini – Giao diện người dùng React + phần phụ trợ FastAPI

Firebase Auth + Firestore

Xác thực người dùng và lưu trữ hồ sơ khủng long

Tác nhân khắc phục (Cloud Run + Eventarc)

Tác nhân SRE tự động khắc phục lỗi OOM và lỗi mã

log-router-bq-report

Tác nhân dữ liệu truyền trực tuyến nhật ký đến BigQuery và tạo thông tin chi tiết

CIAgent (Cloud Run)

Tác nhân CI có phạm vi kiểm thử, tạo hình ảnh và gọi CD thông qua A2A

CDAgent (Cloud Run)

Tác nhân CD chạy các bản triển khai thử nghiệm có tính điểm rủi ro và tính năng tự động khôi phục

Mọi hành vi của Agent đều nằm trong thư mục skills/ dưới dạng sổ tay Markdown – thay đổi hành vi bằng cách chỉnh sửa kỹ năng, chứ không phải mã. Các kỹ năng chạy trên Antigravity với Gemini và được kích hoạt bằng cách cho tác nhân biết kỹ năng nào cần chạy.