اتصال گیت‌هاب به گوگل کلود با استفاده از Developer Connect

۱. مقدمه

در این آزمایشگاه کد، شما با استفاده از Developer Connect یک اتصال امن به مخزن GitHub ایجاد خواهید کرد و از آن اتصال برای استقرار مستقیم یک عامل با استفاده از Agent Runtime در Gemini Enterprise Agent Platform استفاده خواهید کرد.

Developer Connect با راهنمایی شما در مورد مجوزها، احراز هویت، و پیکربندی‌های شبکه به ابزارهای توسعه‌دهنده غیر گوگل، اتصال را برقرار می‌کند. این یک روش مستقیم و بومی برای وارد کردن کد برنامه شما به سرویس‌های Google Cloud فراهم می‌کند.

برای این آزمایشگاه کد، ما از یک اتصال مخزن گیت Developer Connect برای استقرار مستقیم یک عامل با استفاده از Agent Runtime در پلتفرم Gemini Enterprise Agent استفاده خواهیم کرد. Developer Connect از GitHub، GitHub Enterprise، Bitbucket Cloud، Bitbucket Data Center، Gitlab و GitLab Enterprise پشتیبانی می‌کند. در این آزمایشگاه کد، ما اتصال به گیت‌هاب را بررسی خواهیم کرد.

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

  • یک عامل پایه در Agent Runtime ایجاد کنید و آن را به GitHub ارسال کنید
  • از Developer Connect برای اتصال مخزن گیت‌هاب خود به گوگل کلود استفاده کنید
  • با استفاده از مخزن متصل خود، عامل را به صورت بومی در Agent Runtime مستقر کنید
  • عامل راه دور مستقر شده خود را فراخوانی و آزمایش کنید

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

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک حساب کاربری گیت‌هاب و یک توکن دسترسی شخصی (کلاسیک) با دسترسی به مخزن

این آزمایشگاه کد برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است. منابع مدیریت‌شده در این آزمایشگاه کد، عمدتاً APIهای بدون سرور هستند و باید کمتر از ۱ دلار قیمت داشته باشند.

۲. قبل از شروع

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

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

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

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
  2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید: 
    gcloud auth list
  3. تأیید کنید که پروژه شما پیکربندی شده است: 
    export PROJECT_ID=$(gcloud config get-value project)
  4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

فعال کردن APIها

این دستور را اجرا کنید تا تمام API های مورد نیاز برای Developer Connect و Vertex AI فعال شوند:

gcloud services enable \
  developerconnect.googleapis.com \
  aiplatform.googleapis.com

۳. کد منبع عامل را آماده کنید

ابتدا، یک مخزن گیت‌هاب جدید برای نگهداری کد منبع عامل خود ایجاد خواهید کرد و یک عامل استدلال ساده پایتون را به آن اضافه خواهید کرد.

  1. وارد حساب کاربری گیت‌هاب خود شوید.
  2. یک مخزن خصوصی جدید به نام devconnect-agent ایجاد کنید.
  3. آن را با README یا .gitignore مقداردهی اولیه نکنید .

فایل‌های عامل را به صورت محلی ایجاد کنید

به ترمینال Cloud Shell خود برگردید، یک دایرکتوری برای عامل خود ایجاد کنید و وابستگی‌های آن را تعریف کنید:

mkdir -p devconnect-agent/test
cd devconnect-agent

یک فایل requirements.txt در دایرکتوری test ایجاد کنید که کتابخانه‌های Agent Runtime را مشخص کند:

cat <<EOF > test/requirements.txt
google-cloud-aiplatform[agent_engines]
EOF

یک فایل my_agent.py در پوشه test ایجاد کنید. این اسکریپت یک عامل ساده را تعریف می‌کند که به کوئری‌های لیست پاسخ می‌دهد:

cat <<EOF > test/my_agent.py
class MyAgent:

  def query_none(self):
    return None

  def query_list(self):
    return [1, 2, 3]

  def register_operations(self):
    return {
        "": ["query_none", "query_list"],
    }

agent = MyAgent()
EOF

کد را به گیت‌هاب ارسال کنید

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

به جای `<YOUR_GITHUB_USERNAME>` نام کاربری گیت‌هاب خود و به جای `<YOUR_GITHUB_TOKEN>` توکن دسترسی شخصی خود را قرار دهید.

git init
git branch -M main
git add .
git commit -m "Initial commit of agent source"
git remote add origin https://<YOUR_GITHUB_TOKEN>@github.com/<YOUR_GITHUB_USERNAME>/devconnect-agent.git
git push -u origin main

۴. پیکربندی اتصال توسعه‌دهندگان

اکنون که مخزن شما در گیت‌هاب قرار دارد، Developer Connect به طور ایمن پروژه Google Cloud شما را به آن متصل می‌کند.

مجوزهای IAM را تنظیم کنید

با ایجاد یک شناسه سرویس، به Developer Connect اجازه دهید تا به پروژه Google Cloud شما دسترسی داشته باشد.

gcloud beta services identity create \
    --service=developerconnect.googleapis.com \
    --project=$PROJECT_ID

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

گزینه ۱: استفاده از کنسول گوگل کلود

  1. در کنسول گوگل کلود ، به بخش Developer Connect بروید.
  2. روی «اتصال» در زیر GitHub کلیک کنید
  3. نام اتصال خود را my-github-connection بگذارید و آن را در us-central1 انتخاب کنید.
  4. برای تأیید برنامه Developer Connect GitHub، دستورالعمل‌ها را دنبال کنید.
  5. مخزن devconnect-agent را برای پیوند دادن آن به پروژه خود انتخاب کنید.

گزینه ۲: استفاده از رابط خط فرمان gcloud

دستورات زیر را در Cloud Shell اجرا کنید تا مخزن GitHub خود را پیوند دهید.

ابتدا، باید به حساب کاربری سرویس Developer Connect دسترسی به Secret Manager را بدهید. 

# Get the service account
SERVICE_ACCOUNT=$(gcloud beta services identity create \
    --service=developerconnect.googleapis.com \
    --project=$PROJECT_ID \
    --format="value(email)")

# Grant access to Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$SERVICE_ACCOUNT" \
    --role="roles/secretmanager.admin"

# 1. Create the general Developer Connect connection to GitHub
gcloud developer-connect connections create my-github-connection \
    --location=us-central1 \
    --github-config-app=developer-connect
# 2. Link your specific agent repository to the connection
# Replace <YOUR_GITHUB_USERNAME> with your actual GitHub username
gcloud developer-connect connections git-repository-links create devconnect-agent \
    --connection=my-github-connection \
    --location=us-central1 \
    --clone-uri=https://github.com/<YOUR_GITHUB_USERNAME>/devconnect-agent.git

۵. عامل را از Developer Connect مستقر کنید

با اتصال ایمن مخزن خود، می‌توانید مستقیماً یک عامل Agent Runtime را با استفاده از لینک Developer Connect به صورت بومی مستقر کنید.

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

یک اسکریپت پایتون را به صورت محلی در Cloud Shell ایجاد و اجرا کنید تا عامل خود را با استفاده از Vertex AI SDK مستقر کنید.

cd ~
cat <<EOF > deploy.py
import vertexai

PROJECT_ID = "$PROJECT_ID"
LOCATION = "us-central1"

vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

# Define the full URI string for the Developer Connect repository link
repo_link = f"projects/{PROJECT_ID}/locations/{LOCATION}/connections/my-github-connection/gitRepositoryLinks/devconnect-agent"

print("Deploying to Agent Runtime from Developer Connect...")

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {
            "git_repository_link": repo_link,
            "revision": "main",
            "dir": "test",
        },
        "entrypoint_module": "my_agent",
        "entrypoint_object": "agent",
        "requirements_file": "requirements.txt",
        "class_methods": [
            {"name": "query_list", "api_mode": ""}
        ],
        "display_name": "DevConnect Agent",
    },
)

print(f"Agent Runtime deployed successfully: {remote_agent.api_resource.name}")
EOF

اعتبارنامه‌های پیش‌فرض برنامه را در gcloud پیکربندی کنید. 

gcloud auth application-default login

اسکریپت استقرار را اجرا کنید. توجه داشته باشید که این معماری به Vertex AI اجازه می‌دهد تا محدوده‌های اجرای محلی را به طور کامل دور بزند و تصویر عامل از راه دور را از منبع بسازد. 

python3 deploy.py

عامل را آزمایش کنید

پس از اتمام استقرار، یک اسکریپت را اجرا کنید تا از نقطه پایانی عامل خود پرس و جو کنید. 

cat <<EOF > invoke.py
import vertexai

PROJECT_ID = "$PROJECT_ID"
LOCATION = "us-central1"

client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

# Retrieve the latest reasoning engine
engines = list(client.agent_engines.list())
if engines:
    agent = client.agent_engines.get(name=engines[0].api_resource.name)
    print("Invoking remote agent via endpoint...")
    # NOTE: Invoking remote agent
    response = agent.query_list()
    print(f"Agent response: {response}")
else:
    print("No deployment found.")
EOF

python3 invoke.py

شما باید خروجی مشابه زیر را ببینید: 

Invoking remote agent via endpoint...
Agent response: [1, 2, 3]

۶. تمیز کردن

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

منابع Developer Connect و Agent Runtime را پاکسازی کنید: 

cat <<EOF > cleanup.py
import vertexai

PROJECT_ID = "$PROJECT_ID"
LOCATION = "us-central1"

client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

for engine in client.agent_engines.list():
    print(f"Deleting {engine.api_resource.name}")
    engine.delete()
EOF

python3 cleanup.py

منابع Developer Connect را پاکسازی کنید: 

gcloud developer-connect connections git-repository-links delete devconnect-agent \
    --connection=my-github-connection \
    --location=us-central1 \
    --quiet

gcloud developer-connect connections delete my-github-connection \
    --location=us-central1 \
    --quiet

۷. تبریک

تبریک! شما با استفاده از Developer Connect به طور ایمن یک مخزن GitHub یکپارچه ایجاد کردید و یک عامل هوش مصنوعی را مستقیماً از درخت منبع خود مستقر کردید.

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

  • یک پروژه Google Cloud را با Developer Connect و Vertex AI پیکربندی کردم
  • یک توکن دسترسی شخصی به صورت امن در Secret Manager ذخیره شد
  • اتصالات Developer Connect ایجاد شده به طور صریح از طریق gcloud CLI
  • با استفاده از نگاشت شیء developer_connect_source ، یک نمونه Vertex AI Agent Runtime به صورت برنامه‌نویسی شده ایجاد کردم.

مراحل بعدی

  • با استفاده از یکپارچه‌سازی کدبیس Developer Connect شما، با Gemini Code Assist که به صورت سفارشی‌سازی شده طراحی شده است، بیشتر کاوش کنید.
  • با ساختن عامل‌های قوی Agent Runtime آزمایش کنید.

اسناد مرجع