חיבור של GitHub ל-Google Cloud באמצעות Developer Connect

1. מבוא

ב-Codelab הזה תיצרו חיבור מאובטח למאגר GitHub באמצעות Developer Connect, ותשתמשו בחיבור הזה כדי לפרוס סוכן ישירות באמצעות Agent Runtime בפלטפורמת הסוכנים של Gemini Enterprise.

הכלי Developer Connect יוצר קישוריות על ידי הדרכה לגבי הרשאות, הרשאה, אימות והגדרות רשת לכלי פיתוח שאינם של Google. כך אפשר להעביר את קוד האפליקציה לשירותי Google Cloud באופן ישיר ומובנה.

ב-Codelab הזה נשתמש בחיבור של מאגר Git של Developer Connect כדי לפרוס סוכן ישירות באמצעות Agent Runtime בפלטפורמת הסוכנים של Gemini Enterprise. ‫Developer Connect תומך ב-GitHub, ‏ GitHub Enterprise, ‏ Bitbucket Cloud, ‏ Bitbucket Data Center, ‏ Gitlab ו-GitLab Enterprise. ב-Codelab הזה נסביר איך להתחבר ל-GitHub.

הפעולות שתבצעו:

• יצירת סוכן בסיסי ב-Agent Runtime והעלאה שלו ל-GitHub
• שימוש ב-Developer Connect כדי לקשר את המאגר שלכם ב-GitHub ל-Google Cloud
• פריסת הסוכן ב-Agent Runtime באמצעות המאגר המחובר באופן מקורי
• הפעלת הסוכן המרוחק שנפרס ובדיקה שלו

הדרישות

• דפדפן אינטרנט כמו Chrome
• פרויקט ב-Google Cloud שהחיוב בו מופעל
• חשבון GitHub וטוקן גישה אישי (קלאסי) עם גישה למאגר

שיעור ה-Codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים. המשאבים שמנוהלים ב-Codelab הזה הם בעיקר ממשקי API בלי שרת (serverless), והעלות שלהם צריכה להיות פחות מדולר אחד.

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

1. לוחצים על Activate 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

הפעלת 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 שלכם אליו בצורה מאובטחת.

הגדרת הרשאות IAM

כדי לאשר ל-Developer Connect לגשת לפרויקט ב-Google Cloud, צריך ליצור זהות שירות.

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

יצירת החיבור והקישור

אפשר ליצור את החיבור והקישור באמצעות מסוף Google Cloud או gcloud CLI.

אפשרות 1: שימוש במסוף Google Cloud

1. במסוף Google Cloud, עוברים אל Developer Connect.
2. לוחצים על Connect (חיבור) בקטע GitHub.
3. נותנים שם לחיבור my-github-connection ובוחרים אותו ב-us-central1
4. פועלים לפי ההנחיות כדי לאשר את אפליקציית Developer Connect GitHub.
5. בוחרים את מאגר devconnect-agent כדי לקשר אותו לפרויקט.

אפשרות 2: שימוש ב-CLI של 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

אחרי הפקודה הראשונה לחיבור, יכול להיות שתתבקשו להשלים אימות 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

בהתאם לתלות בתוך requirements.txt, זמן הריצה של יצירת הסביבה יכול להימשך 2-5 דקות.

יכול להיות שתופיע השגיאה `RuntimeError: Failed to create Agent Engine Permission Denied . הבעיה נובעת מעיכוב בהפצה של חשבון שירות ב-IAM. אפשר לנסות שוב להריץ את הפקודה הזו, והפריסה אמורה להימשך.

בדיקת הנציג

אחרי שהפריסה מסתיימת, מריצים סקריפט כדי לשלוח שאילתה לנקודת הקצה של הנציג.

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, מוחקים את המשאבים שנוצרו במהלך ה-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

7. מזל טוב

מעולה! הצלחתם ליצור שילוב מאובטח של מאגר GitHub באמצעות Developer Connect, ופרסתם סוכן AI באופן מקורי ישירות מעץ המקור.

מה למדתם

• הגדרתם פרויקט בענן ב-Google Cloud עם Developer Connect ו-Vertex AI
• אחסון מאובטח של טוקן גישה אישי ב-Secret Manager
• חיבורים שנוצרו ב-Developer Connect באופן מפורש באמצעות ה-CLI של gcloud
• יצירת מופע של Vertex AI Agent Runtime באופן פרוגרמטי, באמצעות מיפוי האובייקט developer_connect_source.

השלבים הבאים

• כדי להמשיך לחקור, אפשר להשתמש ב-Gemini Code Assist שהותאם באמצעות השילוב של בסיס הקוד של Developer Connect.
• ניסוי ביצירה של סוכנים חזקים של Agent Runtime.

מסמכי עזר

• מאמרי העזרה של המוצר Developer Connect
• פריסת סוכן באמצעות Developer Connect