ربط GitHub بخدمة Google Cloud باستخدام Developer Connect

1- مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ اتصالاً آمنًا بمستودع GitHub باستخدام Developer Connect، وستستخدم هذا الاتصال لنشر وكيل مباشرةً باستخدام Agent Runtime على Gemini Enterprise Agent Platform.

تنشئ أداة Developer Connect الاتصال من خلال إرشادك خلال أذونات وأذونات الوصول والمصادقة وإعدادات الشبكات لأدوات المطوّرين غير التابعة لـ Google. ويوفّر ذلك طريقة مباشرة وأصلية لجلب الرمز البرمجي لتطبيقك إلى خدمات Google Cloud.

في هذا الدرس التطبيقي حول الترميز، سنستخدم اتصال مستودع Git في Developer Connect لنشر وكيل مباشرةً باستخدام Agent Runtime على Gemini Enterprise Agent Platform. تتوافق أداة Developer Connect مع GitHub وGitHub Enterprise وBitbucket Cloud وBitbucket Data Center وGitlab وGitLab Enterprise. في هذا الدرس التطبيقي حول الترميز، سنشرح عملية الاتصال بـ GitHub.

الإجراءات التي ستنفذّها

• إنشاء وكيل أساسي على Agent Runtime ودفعه إلى GitHub
• استخدام Developer Connect لربط مستودع GitHub بـ Google Cloud
• نشر الوكيل على Agent Runtime باستخدام المستودع المرتبط بشكلٍ أصلي
• استدعاء الوكيل البعيد الذي تم نشره واختباره

المتطلبات

• متصفّح ويب مثل Chrome
• مشروع على Google Cloud تم تفعيل الفوترة له
• حساب على GitHub ورمز دخول شخصي (كلاسيكي) مع إذن الوصول إلى المستودع

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين من جميع المستويات، بما في ذلك المبتدئون. إنّ الموارد المُدارة في هذا الدرس التطبيقي حول الترميز هي في الغالب واجهات برمجة تطبيقات بلا خادم، ومن المفترض أن تكلّف أقل من دولار واحد.

2. قبل البدء

إنشاء مشروع على Google Cloud

1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرّف على كيفية التحقّق مما إذا كانت الفوترة مفعّلة في مشروع.

بدء Cloud Shell

1. انقر على تفعيل Cloud Shell في أعلى Google Cloud Console.
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
   

تفعيل واجهات برمجة التطبيقات

نفِّذ هذا الأمر لتفعيل جميع واجهات برمجة التطبيقات المطلوبة لـ Developer Connect وVertex AI:

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

يؤدي تفعيل Developer Connect إلى تفعيل Secret Manager API تلقائيًا. يُستخدم Secret Manager لتخزين بيانات اعتماد الوصول إلى GitHub بشكلٍ آمن، ما يتيح لـ Developer Connect التواصل مع GitHub بأمان.

3. إعداد رمز مصدر الوكيل

أولاً، ستنشئ مستودع GitHub جديدًا لتخزين رمز مصدر الوكيل، وستضيف إليه وكيلاً بسيطًا للاستدلال مكتوبًا بلغة Python.

1. سجِّل الدخول إلى حسابك على GitHub.
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

دفع الرمز إلى GitHub

هيِّئ مستودع Git وادفَع الرمز إلى مستودع GitHub الذي أنشأته حديثًا.

استبدِل `<YOUR_GITHUB_USERNAME>` باسم مستخدم GitHub و`<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

4. ضبط Developer Connect

بعد أن يصبح مستودعك على GitHub، ستربط أداة Developer Connect مشروعك على Google Cloud به بشكلٍ آمن.

إعداد أذونات إدارة الهوية وإمكانية الوصول

فوِّض أداة Developer Connect للوصول إلى مشروعك على Google Cloud من خلال إنشاء هوية خدمة.

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

إنشاء الاتصال والربط

يمكنك إنشاء الاتصال والربط باستخدام Google Cloud Console أو gcloud CLI.

الخيار 1: استخدام Google Cloud Console

1. في Google Cloud Console، انتقِل إلى Developer Connect.
2. انقر على ربط ضِمن GitHub
3. سمِّ الاتصال my-github-connection واختَره في us-central1
4. اتّبِع التعليمات الظاهرة على الشاشة لتفويض تطبيق GitHub في Developer Connect.
5. اختَر مستودع devconnect-agent لربطه بمشروعك.

الخيار 2: استخدام gcloud CLI

نفِّذ الأوامر التالية في 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

بعد أمر الاتصال الأول، قد يُطلب منك إكمال عملية التحقّق من OAuth داخل المتصفّح للسماح لـ Developer Connect. اتّبِع الرابط الظاهر على الشاشة إذا طُلب منك تفويض عملية التكامل.

5. نشر الوكيل من Developer Connect

بعد ربط مستودعك بشكلٍ آمن، يمكنك نشر وكيل Agent Runtime مباشرةً باستخدام رابط Developer Connect بشكلٍ أصلي.

نشر Agent Runtime

أنشِئ نصًا برمجيًا بلغة Python ونفِّذه محليًا في Cloud Shell لنشر وكيلك باستخدام Vertex AI SDK.

إذا ربطت مستودعك باستخدام Cloud Console، يُرجى التأكّد من أنّ اسم رابط المستودع في النص البرمجي أدناه يطابق اسم رابط مستودع Git.

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

قد يستغرِق وقت تشغيل إنشاء البيئة من دقيقتَين إلى 5 دقائق، وذلك حسب التبعيات ضِمن requirements.txt.

قد تظهر لك رسالة الخطأ `RuntimeError: Failed to create Agent Engine Permission Denied error . ويحدث ذلك بسبب تأخير في نشر حساب خدمة إدارة الهوية وإمكانية الوصول. يمكنك إعادة محاولة تنفيذ هذا الأمر، ومن المفترض أن تكتمل عملية النشر.

اختبار الوكيل

بعد اكتمال عملية النشر، نفِّذ نصًا برمجيًا للاستعلام عن نقطة نهاية الوكيل.

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]

6. تَنظيم

لتجنُّب فرض رسوم مستمرة على حسابك على Google Cloud، احذف الموارد التي أنشأتها خلال هذا الدرس التطبيقي حول الترميز.

نظِّف موارد 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

7. تهانينا

تهانينا! لقد أنشأت عملية تكامل آمنة لمستودع GitHub باستخدام Developer Connect ونشرت وكيل ذكاء اصطناعي بشكلٍ أصلي مباشرةً من شجرة المصدر.

ما تعلّمته

• ضبط مشروع على Google Cloud باستخدام Developer Connect وVertex AI
• تخزين رمز دخول شخصي بشكلٍ آمن في Secret Manager
• إنشاء اتصالات Developer Connect بشكلٍ صريح من خلال gcloud CLI
• إنشاء مثيل Agent Runtime في Vertex AI برمجيًا باستخدام عملية الربط بين الكائنات developer_connect_source

الخطوات التالية

• استكشِف المزيد باستخدام Gemini Code Assist الذي تم تخصيصه باستخدام عملية تكامل قاعدة الرموز البرمجية في Developer Connect.
• جرِّب إنشاء وكلاء Agent Runtime قويين.

المستندات المرجعية

• مستندات منتج Developer Connect
• نشر وكيل باستخدام Developer Connect