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

1. مقدمة

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

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

في هذا الدرس التطبيقي حول الترميز، سنستخدم ميزة "ربط مستودع Git" في Developer Connect لنشر وكيل مباشرةً باستخدام Agent Runtime على "منصة وكلاء Gemini Enterprise". يتوافق 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، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

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
   

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

نفِّذ الأمر التالي لتفعيل جميع واجهات برمجة التطبيقات المطلوبة لخدمتَي 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.

الخيار 1: استخدام وحدة تحكّم Google Cloud

1. في وحدة تحكّم Google Cloud، انتقِل إلى Developer Connect.
2. انقر على ربط ضمن GitHub
3. أدخِل اسمًا لعملية الربط my-github-connection واختَرها في us-central1
4. اتّبِع التعليمات الظاهرة على الشاشة للسماح باستخدام تطبيق Developer Connect GitHub.
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 لنشر الوكيل باستخدام حزمة تطوير البرامج (SDK) الخاصة بمنصة Vertex AI.

إذا ربطت المستودع باستخدام 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

استنادًا إلى التبعيات داخل requirements.txt، قد يستغرق وقت تشغيل إنشاء البيئة من دقيقتَين إلى 5 دقائق.

قد تظهر لك رسالة الخطأ `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
• تم إنشاء مثيل Vertex AI Agent Runtime آليًا باستخدام عملية ربط الكائنات developer_connect_source.

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

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

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

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