Connettere GitHub a Google Cloud con Developer Connect

1. Introduzione

In questo codelab, creerai una connessione sicura a un repository GitHub utilizzando Developer Connect e la utilizzerai per eseguire il deployment diretto di un agente utilizzando Agent Runtime sulla piattaforma Gemini Enterprise Agent.

Developer Connect stabilisce la connettività guidandoti attraverso le configurazioni di autorizzazioni, autorizzazione, autenticazione e networking per strumenti di sviluppo non Google. In questo modo, puoi inserire il codice dell'applicazione nei servizi Google Cloud in modo diretto e nativo.

Per questo codelab, utilizzeremo una connessione al repository Git di Developer Connect per eseguire il deployment diretto di un agente utilizzando Agent Runtime sulla piattaforma Gemini Enterprise Agent. Developer Connect supporta GitHub, GitHub Enterprise, Bitbucket Cloud, Bitbucket Data Center, Gitlab e GitLab Enterprise. In questo codelab, esamineremo una connessione a GitHub.

In questo lab proverai a:

• Crea un agente di base in Agent Runtime ed eseguine il push su GitHub
• Utilizza Developer Connect per collegare il tuo repository GitHub a Google Cloud
• Esegui il deployment dell'agente su Agent Runtime utilizzando il repository connesso in modo nativo
• Richiamare e testare l'agente remoto di cui è stato eseguito il deployment

Che cosa ti serve

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata
• Un account GitHub e un token di accesso personale (classico) con accesso al repository

Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti. Le risorse gestite in questo codelab sono principalmente API serverless e dovrebbero costare meno di 1 $.

2. Prima di iniziare

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
2. Una volta connesso a Cloud Shell, verifica l'autenticazione:

   gcloud auth list
   

3. Verifica che il progetto sia configurato:

   export PROJECT_ID=$(gcloud config get-value project)
   

4. Se il progetto non è impostato come previsto, impostalo:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Abilita API

Esegui questo comando per abilitare tutte le API richieste per Developer Connect e Vertex AI:

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

L'abilitazione di Developer Connect attiva automaticamente l'API Secret Manager. Secret Manager viene utilizzato per archiviare in modo sicuro le credenziali di accesso a GitHub, in modo che Developer Connect possa comunicare in modo sicuro con GitHub.

3. Prepara il codice sorgente dell'agente

Innanzitutto, creerai un nuovo repository GitHub per contenere il codice sorgente dell'agente e vi aggiungerai un semplice agente di ragionamento Python.

1. Accedi al tuo account GitHub.
2. Crea un nuovo repository privato denominato devconnect-agent.
3. Non inizializzarlo con un file README o .gitignore.

Crea i file dell'agente localmente

Nel terminale Cloud Shell, crea una directory per l'agente e definisci le relative dipendenze:

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

Crea un file requirements.txt nella directory test specificando le librerie di Agent Runtime:

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

Crea un file my_agent.py nella directory test. Questo script definisce un semplice agente che risponde alle query di elenco:

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

Esegui il push del codice su GitHub

Inizializza un repository Git ed esegui il push del codice nel repository GitHub appena creato.

Sostituisci `<YOUR_GITHUB_USERNAME>` con il tuo nome utente GitHub e `<YOUR_GITHUB_TOKEN>` con il tuo token di accesso personale.

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. Configura Developer Connect

Ora che il repository si trova su GitHub, Developer Connect lo collegherà in modo sicuro al tuo progetto Google Cloud.

Configurare le autorizzazioni IAM

Autorizza Developer Connect ad accedere al tuo progetto Google Cloud generando un'identità di servizio.

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

Crea la connessione e il collegamento

Puoi creare la connessione e il collegamento utilizzando la console Google Cloud o la CLI gcloud.

Opzione 1: utilizzo della console Google Cloud

1. Nella console Google Cloud, vai a Developer Connect.
2. Fai clic su Connetti in GitHub.
3. Assegna un nome alla connessione my-github-connection e selezionala in us-central1.
4. Segui le istruzioni per autorizzare l'app GitHub Developer Connect.
5. Seleziona il repository devconnect-agent per collegarlo al tuo progetto.

Opzione 2: utilizzo di gcloud CLI

Esegui questi comandi in Cloud Shell per collegare il repository GitHub.

Innanzitutto, devi concedere al service account Developer Connect l'accesso a 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

Dopo il primo comando di connessione, potrebbe esserti chiesto di completare una verifica OAuth all'interno del browser per consentire a Developer Connect. Segui il link sullo schermo se ti viene chiesto di autorizzare l'integrazione.

5. Esegui il deployment dell'agente da Developer Connect

Con il repository connesso in modo sicuro, puoi eseguire il deployment diretto di un agente Agent Runtime sfruttando il link Developer Connect in modo nativo.

Esegui il deployment di Agent Runtime

Crea ed esegui uno script Python localmente in Cloud Shell per eseguire il deployment dell'agente utilizzando l'SDK Vertex AI.

Se hai connesso il repository utilizzando la console Cloud, assicurati che il nome del link del repository nello script riportato di seguito corrisponda al nome del link del repository 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

Configura le credenziali predefinite dell'applicazione in gcloud.

gcloud auth application-default login

Esegui lo script di deployment. Tieni presente che questa architettura consente a Vertex AI di bypassare completamente gli ambiti di esecuzione locali e di creare l'immagine dell'agente remoto dall'origine.

python3 deploy.py

A seconda delle dipendenze all'interno di requirements.txt, il tempo di esecuzione della creazione dell'ambiente può richiedere 2-5 minuti.

Potresti visualizzare l'errore `RuntimeError: Failed to create Agent Engine Permission Denied` . Ciò è dovuto a un ritardo di propagazione del service account IAM. Puoi riprovare a eseguire questo comando e il deployment dovrebbe procedere.

Testare l'agente

Al termine del deployment, esegui uno script per interrogare l'endpoint dell'agente.

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

Dovresti visualizzare un output simile al seguente:

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

6. Esegui la pulizia

Per evitare addebiti continui al tuo account Google Cloud, elimina le risorse create durante questo codelab.

Libera spazio nelle risorse di Developer Connect e 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

Esegui la pulizia delle risorse 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. Complimenti

Complimenti! Hai stabilito in modo sicuro un'integrazione del repository GitHub utilizzando Developer Connect e hai eseguito il deployment nativo di un agente AI direttamente dall'albero delle origini.

Cosa hai imparato

• Configurato un progetto Google Cloud con Developer Connect e Vertex AI
• Archiviazione sicura di un token di accesso personale in Secret Manager
• Connessioni Developer Connect generate in modo esplicito tramite gcloud CLI
• È stata creata un'istanza di Vertex AI Agent Runtime in modo programmatico, utilizzando il mapping degli oggetti developer_connect_source.

Passaggi successivi

• Esplora ulteriormente con Gemini Code Assist, personalizzato utilizzando l'integrazione del codebase di Developer Connect.
• Sperimenta la creazione di agenti Agent Runtime robusti.

Documenti di riferimento

• Documentazione del prodotto Developer Connect
• Esegui il deployment di un agente utilizzando Developer Connect