使用 Developer Connect 將 GitHub 連結至 Google Cloud

1. 簡介

在本程式碼研究室中，您將使用 Developer Connect 建立與 GitHub 存放區的安全連線，並使用該連線，透過 Gemini Enterprise Agent Platform 的 Agent Runtime 直接部署服務專員。

Developer Connect 會逐步引導您完成權限、授權、驗證和網路設定，與非 Google 開發人員工具建立連線。這項功能提供直接的原生方式，將應用程式程式碼提取至 Google Cloud 服務。

在本程式碼實驗室中，我們將使用 Developer Connect Git 存放區連線，透過 Gemini Enterprise Agent Platform 的 Agent Runtime 直接部署代理。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 帳戶和具有存放區存取權的個人存取權杖 (傳統版)

本程式碼研究室適合各種程度的開發人員 (包括初學者)。本程式碼研究室管理的大多是無伺服器 API，費用應低於 $1 美元。

2. 事前準備

建立 Google Cloud 專案

1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

啟動 Cloud Shell

1. 按一下 Google Cloud 控制台頂端的「啟用 Cloud Shell」。
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

執行下列指令，啟用 Developer Connect 和 Vertex AI 的所有必要 API：

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

在 test 目錄中建立 requirements.txt 檔案，指定 Agent Runtime 程式庫：

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

在 test 目錄中建立 my_agent.py 檔案。這項指令碼定義了可回答清單查詢的簡單代理程式：

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. 按一下 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

在 Cloud Shell 中建立並執行 Python 指令碼，使用 Vertex AI SDK 部署代理程式。

如果您使用 Cloud 控制台連結存放區，請確認下列指令碼中的存放區連結名稱與 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 error . 這是因為 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 帳戶收取費用，請刪除本程式碼研究室建立的資源。

清理 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. 恭喜

恭喜！您使用 Developer Connect 安全地建立 GitHub 存放區整合，並直接從來源樹狀結構原生部署 AI 代理程式。

目前所學內容

• 已透過 Developer Connect 和 Vertex AI 設定 Google Cloud 雲端專案
• 將個人存取權杖安全地儲存在 Secret Manager 中
• 透過 gcloud CLI 明確產生的 Developer Connect 連線
• 使用 developer_connect_source 物件對應，以程式輔助方式建立 Vertex AI Agent Runtime 執行個體。

後續步驟

• 透過整合 Developer Connect 程式碼集，使用量身打造的 Gemini Code Assist 進一步探索。
• 嘗試建構強大的 Agent Runtime 代理程式。

參考文件

• Developer Connect 產品說明文件
• 使用 Developer Connect 部署代理程式