Questa pagina è stata tradotta dall'API Cloud Translation.

Implementazione delle storie utente di JIRA con l'IA generativa

1. Panoramica

In questo lab, creerai una soluzione per automatizzare l'implementazione delle storie di utilizzo di JIRA con GenAI.

Cosa imparerai a fare

Il laboratorio è composto da diverse parti principali:

Esegui il deployment dell'applicazione Cloud Run per l'integrazione con le API Gemini
Creare ed eseguire il deployment dell'app Atlassian Forge per JIRA
Agenti LangChain ReAct per l'automazione delle attività di GitLab

Prerequisiti

Questo lab presuppone familiarità con gli ambienti Cloud Console e Cloud Shell.

2. Configurazione e requisiti

Configurazione del progetto cloud

Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

Il nome del progetto è il nome visualizzato per i partecipanti al progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
L'ID progetto è univoco per tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo essere stato impostato). La console Cloud genera automaticamente una stringa univoca; di solito non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento al tuo ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare il tuo e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane invariato per tutta la durata del progetto.
Per tua informazione, esiste un terzo valore, un Numero progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le API/risorse Cloud. La partecipazione a questo codelab non ha costi, o quasi. Per arrestare le risorse ed evitare di incorrere in fatturazione al termine di questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud sono idonei al programma Prova senza costi di 300$.

Configurazione dell'ambiente

Apri la chat di Gemini.

In alternativa, digita "Chiedi a Gemini" nella barra di ricerca.

Abilita l'API Cloud AI Companion:

Fai clic su "Start chatting" e segui una delle domande di esempio o digita il tuo prompt per provarlo.

Prompt da provare:

Spiega Cloud Run in 5 punti chiave.
Sei un Product Manager di Google Cloud Run e devi spiegare Cloud Run a uno studente in 5 brevi punti chiave.
Sei un Product Manager di Google Cloud Run e devi spiegare Cloud Run a uno sviluppatore Kubernetes certificato in 5 brevi punti chiave.
Sei un Product Manager di Google Cloud Run. Spiega a uno sviluppatore senior quando utilizzeresti Cloud Run rispetto a GKE in 5 brevi punti chiave.

Consulta la guida ai prompt per scoprire di più su come scrivere prompt migliori.

In che modo Gemini for Google Cloud utilizza i tuoi dati

Impegno di Google per la privacy

Google è stata una delle prime aziende del settore a pubblicare un impegno in materia di privacy AI/ML, che illustra la nostra convinzione che i clienti debbano disporre del massimo livello di sicurezza e controllo sui propri dati archiviati nel cloud.

Dati che invii e ricevi

Le domande che fai a Gemini, incluse le informazioni di input o il codice che invii a Gemini per l'analisi o il completamento, sono chiamate prompt. Le risposte o i completamenti di codice che ricevi da Gemini sono chiamati risposte. Gemini non utilizza i tuoi prompt o le relative risposte come dati per addestrare i propri modelli.

Crittografia dei prompt

Quando invii prompt a Gemini, i tuoi dati vengono criptati in transito come input al modello sottostante in Gemini.

Dati del programma generati da Gemini

Gemini viene addestrato sul codice proprietario di Google Cloud e su codice di terze parti selezionato. Sei responsabile della sicurezza, dei test e dell'efficacia del tuo codice, incluse eventuali operazioni di completamento, generazione o analisi del codice offerte da Gemini.

Scopri di più su come Google gestisce i tuoi prompt.

3. Opzioni per testare i prompt

Hai a disposizione diverse opzioni per testare i prompt.

Vertex AI Studio

Vertex AI Studio fa parte della piattaforma Vertex AI di Google Cloud, progettata specificamente per semplificare e accelerare lo sviluppo e l'utilizzo dei modelli di IA generativa.

Google AI Studio

Google AI Studio è uno strumento basato sul web per la prototipazione e la sperimentazione della progettazione di prompt e dell'API Gemini.

App web Gemini (gemini.google.com)

L'app web Google Gemini (gemini.google.com) è uno strumento basato sul web progettato per aiutarti a esplorare e utilizzare la potenza dei modelli di IA di Gemini di Google.

App mobile Google Gemini per Android e app Google su iOS

4. (SEZIONE FACOLTATIVA) Crea account di servizio

Questi passaggi sono stati eseguiti durante la configurazione del lab e non è necessario eseguirli.

Questi passaggi sono inclusi per mostrare come configurare un account di servizio e i ruoli IAM.

Torna alla console Google Cloud e attiva Cloud Shell facendo clic sull'icona a destra della barra di ricerca.

Nel terminale aperto, esegui i seguenti comandi per creare un nuovo account di servizio e le relative chiavi.

Utilizzerai questo account di servizio per effettuare chiamate API all'API Vertex AI Gemini dall'applicazione Cloud Run.

Configura i dettagli del progetto utilizzando i dettagli del progetto Qwiklabs.

Esempio: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

Crea un account di servizio e assegna i ruoli.

PROJECT_ID=$(gcloud config get-value project)
SERVICE_ACCOUNT_NAME='vertex-client'
DISPLAY_NAME='Vertex Client'
KEY_FILE_NAME='vertex-client-key'

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"


gcloud iam service-accounts keys create $KEY_FILE_NAME.json --iam-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

Se ti viene chiesto di autorizzare, fai clic su "Autorizza" per continuare.

Abilita i servizi richiesti per utilizzare le API Vertex AI e la chat Gemini.

gcloud services enable \
    generativelanguage.googleapis.com \
    aiplatform.googleapis.com \
    cloudaicompanion.googleapis.com \
    run.googleapis.com \
    cloudresourcemanager.googleapis.com

Abilita i servizi richiesti per utilizzare le API Vertex AI e la chat Gemini.

gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    runapps.googleapis.com \
    workstations.googleapis.com \
    servicemanagement.googleapis.com \
    secretmanager.googleapis.com \
    containerscanning.googleapis.com

(END OF OPTIONAL SECTION)

5. Concedere l'accesso a Cloud Workstations

Apri Cloud Workstations nella console Cloud.

Concedi l'accesso a Cloud Workstation per lo studente Qwiklabs di cui è stato eseguito il provisioning.

Copia il nome utente/l'indirizzo email Qwiklabs creato per questo progetto e utilizzalo per aggiungere un principale. Seleziona la workstation e fai clic su "PERMISSIONS".

Consulta i dettagli di seguito.

Fai clic sul pulsante "ADD PRINCIPAL".

Incolla l'indirizzo email dello studente di Qwiklabs e seleziona il ruolo "Cloud Workstations User".

Fai clic su "Start" e poi su "Launch" per aprire la workstation e procedere con i passaggi che seguono utilizzando il terminale integrato.

Clona il repository GitHub

Crea una cartella e clona il repository GitHub.

mkdir github
cd github
git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git

Utilizzando l'elemento di menu "File / Open Folder", apri "github/genai-for-developers".

6. Attivare Gemini Code Assist

Fai clic sull'icona "Gemini" nell'angolo in basso a destra, poi fai clic su "Login to Google Cloud".

Fai clic sul link nel terminale per avviare il flusso di autorizzazione.

Fai clic su "Apri" per seguire il link.

Seleziona il tuo account studente Qwiklabs e fai clic su "Accedi" nella schermata successiva.

Copia il codice di verifica:

Torna al terminale e incolla il codice.

Attendi il completamento dell'autenticazione, poi fai clic su "Seleziona un progetto Google".

Nella finestra popup, seleziona il tuo progetto Qwiklabs.

Esempio:

Apri il file "devai-api/app/routes.py", fai clic con il tasto destro del mouse in un punto qualsiasi del file e seleziona "Gemini > Explain this"" dal menu contestuale.

Esamina la spiegazione di Gemini per il file selezionato.

7. Toolkit LangChain

I toolkit di LangChain sono insiemi di strumenti progettati per semplificare e migliorare lo sviluppo di applicazioni con LangChain. Offrono varie funzionalità a seconda del toolkit specifico, ma in genere aiutano con:

Connessione a origini dati esterne: accedi e incorpora informazioni da API, database e altre origini esterne nelle tue applicazioni LangChain.
Tecniche di prompt avanzate: utilizza prompt predefiniti o creane di personalizzati per ottimizzare le interazioni con i modelli linguistici.
Creazione e gestione delle catene: crea facilmente catene complesse e gestiscile in modo efficiente.
Valutazione e monitoraggio: analizza il rendimento delle applicazioni e delle catene LangChain.

Alcuni dei toolkit LangChain più utilizzati includono:

Toolkit per l'esecuzione di agenti: strumenti per lo sviluppo di agenti che possono interagire con il mondo reale tramite azioni come la navigazione sul web o l'esecuzione di codice.
Prompt Engineering Toolkit: una raccolta di risorse per creare prompt efficaci.

Toolkit GitLab

In questo lab utilizzerai il Toolkit di GitLab per automatizzare la creazione delle richieste di unione di GitLab.

Il toolkit Gitlab contiene strumenti che consentono a un agente LLM di interagire con un repository Gitlab. Lo strumento è un wrapper per la libreria python-gitlab.

Il toolkit GitLab può eseguire le seguenti attività:

Crea file: crea un nuovo file nel repository.
Leggi file: legge un file dal repository.
Aggiorna file: aggiorna un file nel repository.
Crea richiesta pull: crea una richiesta pull dal ramo di lavoro del bot al ramo base.
Get Issue: recupera i problemi dal repository.
Get Issue: recupera i dettagli di un problema specifico.
Commenta il problema: pubblica un commento su un problema specifico.
Elimina file: elimina un file dal repository.

8. Configurazione del repository e del toolkit GitLab

Apri GitLab, crea un nuovo progetto pubblico e configura il token di accesso al progetto in "Settings / Access Tokens".

Utilizza i seguenti dettagli:

Nome token: devai-api-qwiklabs
Ruolo: Maintainer
Seleziona gli ambiti: api

Copia e incolla il valore del token di accesso in un file temporaneo sul tuo laptop, lo userai nei passaggi successivi.

9. Prepararsi a eseguire il deployment dell'applicazione in Cloud Run

Torna all'istanza Cloud Workstations e utilizza un terminale esistente o apri un nuovo terminale.

Ottieni le credenziali di accesso per il tuo account utente tramite un flusso di autorizzazione basato sul web.

Fai clic sul link e segui i passaggi per generare il codice di verifica.

gcloud auth login

Configura i dettagli del progetto utilizzando i dettagli del progetto Qwiklabs.

Esempio: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR-QWIKLABS-PROJECT-ID

Imposta le altre variabili di ambiente:

export PROJECT_ID=$(gcloud config get-value project)
export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api

Imposta le variabili di ambiente richieste per l'integrazione di GitLab.

export GITLAB_PERSONAL_ACCESS_TOKEN=gitlab-token

Per evitare di esporre informazioni sensibili nel terminale, è consigliabile utilizzare read -s, un modo sicuro per impostare le variabili di ambiente senza che il valore venga visualizzato nella cronologia dei comandi della console. Dopo averlo eseguito, devi incollare il valore e premere Invio.

Questo comando richiede l'aggiornamento dell'ID utente e del nome del repository GitLab.

Esempio: export GITLAB_REPOSITORY="gitrey/qwiklabs-test"

export GITLAB_REPOSITORY="USERID/REPOSITORY"

Imposta le altre variabili di ambiente:

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

10. Configurazione del monitoraggio di LangSmith LLM

Crea un account LangSmith e genera una chiave API di servizio nella sezione Impostazioni. https://docs.smith.langchain.com/

Imposta le variabili di ambiente richieste per l'integrazione di LangSmith.

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LANGCHAIN_API_KEY=langchain-service-api-key

11. Configurazione di JIRA

Questi valori non vengono utilizzati in questo laboratorio, quindi non è necessario aggiornarli con i valori specifici del tuo progetto JIRA prima di eseguire i comandi.

Imposta le variabili di ambiente necessarie per il deployment del servizio Cloud Run.

export JIRA_API_TOKEN=jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

12. Esegui il deployment di Devai-API in Cloud Run

Verifica di trovarti nella cartella corretta.

cd ~/github/genai-for-developers/devai-api

Per questo lab, seguiamo le best practice e utilizziamo Secret Manager per archiviare e fare riferimento ai valori del token di accesso e della chiave API LangChain in Cloud Run.

Memorizza il token di accesso JIRA in Secret Manager.

echo -n $JIRA_API_TOKEN | \
 gcloud secrets create JIRA_API_TOKEN \
 --data-file=-

Memorizza il token di accesso GitLab in Secret Manager.

echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
 gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
 --data-file=-

Memorizza la chiave API LangChain in Secret Manager.

echo -n $LANGCHAIN_API_KEY | \
 gcloud secrets create LANGCHAIN_API_KEY \
 --data-file=-

Esegui il deployment dell'applicazione in Cloud Run.

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

Rispondi Y per creare il repository Docker di Artifact Registry.

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in 
region [us-central1] will be created.

Do you want to continue (Y/n)?  y

Esamina il flusso gcloud run deploy SERVICE_NAME --source=. di seguito. Scopri di più.

Dietro le quinte, questo comando utilizza buildpacks e Cloud Build di Google Cloud per creare automaticamente immagini container dal codice sorgente senza dover installare Docker sulla tua macchina o configurare i buildpack o Cloud Build. In altre parole, il singolo comando descritto sopra esegue l'operazione che altrimenti richiederebbe i comandi gcloud builds submit e gcloud run deploy.

Se hai fornito il Dockerfile(come abbiamo fatto in questo repository), Cloud Build lo utilizzerà per creare immagini container anziché fare affidamento sui buildpack per rilevare e creare automaticamente le immagini container. Per scoprire di più sui buildpack, consulta la documentazione.

Esamina i log di Cloud Build nella console.

Esamina l'immagine Docker creata in Artifact Registry.

Apri cloud-run-source-deploy/devai-api e controlla le vulnerabilità rilevate automaticamente. Controlla quelli per cui sono disponibili correzioni e scopri come possono essere corretti in base alla descrizione.

Esamina i dettagli dell'istanza Cloud Run in Cloud Console.

Testa l'endpoint eseguendo il comando curl.

curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"prompt": "Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything."}' \
   $(gcloud run services list --filter="(devai-api)" --format="value(URL)")/generate

(SEZIONE FACOLTATIVA) Configura Cloud Workstation

Cloud Workstations fornisce ambienti di sviluppo gestiti su Google Cloud con sicurezza integrata e ambienti di sviluppo preconfigurati, ma personalizzabili. Anziché richiedere agli sviluppatori di installare il software ed eseguire script di configurazione, puoi creare una configurazione della workstation che specifichi il tuo ambiente in modo riproducibile. Eventuali aggiornamenti alla configurazione di una workstation vengono applicati automaticamente alle workstation al successivo avvio. Gli sviluppatori accedono alle workstation tramite un IDE basato su browser, da più editor di codice locali (ad esempio VSCode o IDE JetBrains come IntelliJ IDEA Ultimate e PyCharm Professional) o tramite SSH.

Cloud Workstations utilizza le seguenti risorse Google Cloud per gestire gli ambienti di sviluppo:

I cluster di workstation definiscono un gruppo di workstation in una determinata regione e la rete VPC a cui sono collegate. I cluster di workstation non sono correlati ai cluster di Google Kubernetes Engine (GKE).
Le configurazioni delle workstation fungono da modelli per le workstation. La configurazione della workstation definisce dettagli come il tipo di istanza della macchina virtuale (VM) della workstation, lo spazio di archiviazione permanente, l'ambiente che definisce l'immagine del contenitore, l'IDE o l'editor di codice da utilizzare e altro ancora. Gli amministratori e i team della piattaforma possono anche utilizzare le regole IAM (Identity and Access Management) per concedere l'accesso ai team o ai singoli sviluppatori.
Le workstation sono ambienti di sviluppo preconfigurati che forniscono un IDE cloud, strumenti per il linguaggio, librerie e altro ancora. Le workstation possono essere avviate o arrestate su richiesta ed eseguite su VM Compute Engine nel tuo progetto, con un disco permanente collegato per archiviare i dati tra le sessioni.

Gli amministratori e i team della piattaforma creano configurazioni delle workstation che condividono con il team di sviluppo. Ogni sviluppatore crea una workstation in base a una configurazione.

In questo lab utilizzi un'IDE basata su browser, ma Cloud Workstations supporta anche altre interfacce di sviluppo comuni:

Puoi utilizzare i tuoi IDE JetBrains locali tramite JetBrains Gateway
Se utilizzi VSCode locale, puoi anche accedere alle tue workstation per lo sviluppo remoto tramite SSH.
Puoi anche configurare tunnel SSH e persino TCP alla tua workstation dalla tua macchina locale

(SEZIONE FACOLTATIVA) Crea cluster di workstation

Questi passaggi sono stati eseguiti durante la configurazione del lab e non è necessario eseguirli.

Questi passaggi sono inclusi per mostrare come configurare il cluster, la configurazione e la workstation Cloud Workstations.

Esamina questa sezione e vai alla sezione sulla piattaforma Forge.

Crea il cluster di workstation:

gcloud workstations clusters create ws-cluster --region=us-central1

Crea configurazione delle workstation

gcloud workstations configs create devai-config \
--cluster=ws-cluster \
--machine-type=e2-standard-8 \
--region=us-central1 \
--running-timeout=21600 \
--idle-timeout=1800 \
--container-predefined-image=codeoss \
--pd-disk-size=200 \
--pd-disk-type=pd-standard \
--service-account=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com \
--pool-size=1

Crea workstation

gcloud workstations create devai-workstation \
--cluster=ws-cluster \
--config=devai-config \
--region=us-central1

Visualizza le workstation disponibili nella console Cloud. Avvia e lancia "devai-workstation".

Attiva "Gemini" nell'angolo in basso a destra, segui il flusso di accesso nella nuova scheda del browser e copia di nuovo il codice generato nella console per completare l'accesso.

Apri la chat "Gemini" nel riquadro a sinistra e chiedi a Gemini:

"You are a Cloud Workstations Product Manager, tell me about Cloud Workstations".

"You are Cloud Workstations Product Manager, Can I create my custom Cloud Workstations image with my company tools so new developers can onboard in minutes?".

(END OF OPTIONAL SECTION)

13. Piattaforma Forge

Forge è una piattaforma che consente agli sviluppatori di creare app che si integrano con i prodotti Atlassian, come Jira, Confluence, Compass e Bitbucket.

Installa Forge CLI

Esegui i comandi riportati di seguito nel terminale.

Scarica Node Version Manager ( nvm) e rendilo disponibile nel percorso nella sessione del terminale corrente.

cd ~/github/genai-for-developers

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash


export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

Installa nvm.

Seleziona la versione LTS di Node.js più recente eseguendo il seguente comando nel terminale:

nvm install --lts
nvm use --lts

Installa Forge CLI a livello globale eseguendo:

npm install -g @forge/cli

Per questo lab, utilizzeremo le variabili di ambiente per accedere.

Configura il progetto JIRA

Utilizza il tuo account personale per creare/visualizzare i progetti JIRA.

Esamina i progetti JIRA esistenti: https://admin.atlassian.com/

Crea un nuovo progetto JIRA utilizzando il tuo account personale.

Vai alla pagina https://team.atlassian.com/your-work, fai clic su e poi seleziona . Dopodiché seleziona "JIRA Software" - "Prova ora". Segui le istruzioni per completare la creazione del progetto/del sito.

Seleziona JIRA Software.

Crea un nuovo progetto.

14. Token API Atlassian

Crea o utilizza un token API Atlassian esistente per accedere all'interfaccia a riga di comando.

L'interfaccia a riga di comando utilizza il token quando esegui i comandi.

Vai alla pagina https://id.atlassian.com/manage/api-tokens.
Fai clic su Crea token API.
Inserisci un'etichetta per descrivere il token API. Ad esempio, forge-api-token.
Fai clic su Crea.
Fai clic su Copia negli appunti e chiudi la finestra di dialogo.

Esegui il comando riportato di seguito nel terminale di Cloud Workstations.

Accedi all'interfaccia a riga di comando Forge per iniziare a utilizzare i comandi Forge.

Imposta il tuo indirizzo email JIRA/FORGE. Sostituisci con il tuo indirizzo email.

export FORGE_EMAIL=your-email

Imposta il token API Forge. Sostituisci con il token dell'API JIRA.

export FORGE_API_TOKEN=your-jira-api-token

Testa l'interfaccia a riga di comando di Forge eseguendo il comando seguente. Rispondi "No" quando ti viene chiesto di raccogliere i dati e le analisi.

forge settings set usage-analytics false

Verifica di aver eseguito l'accesso.

forge whoami

Esempio di output.

Logged in as John Green (johngreen@email.com)
Account ID: 123090:aaabbcc-076a-455c-99d0-d1aavvccdd

Creare un'applicazione Forge

Verifica di essere nella cartella "~/github/genai-for-developers".

Esegui il comando per creare un'applicazione Forge.

forge create

Quando richiesto, utilizza i seguenti valori:

Nome dell'app: devai-jira-ui-qwiklabs
Seleziona una categoria: UI Kit
Seleziona un prodotto: Jira
Seleziona un modello: jira-issue-panel

Vai alla cartella dell'applicazione.

cd devai-jira-ui-qwiklabs/

Esegui il comando di deployment.

forge deploy

Esempio di output:

Deploying your app to the development environment.
Press Ctrl+C to cancel.

Running forge lint...
No issues found.

✔ Deploying devai-jira-ui-qwiklabs to development...

ℹ Packaging app files
ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

Installa l'applicazione.

forge install

Quando richiesto, utilizza i seguenti valori:

Seleziona un prodotto: Jira
Inserisci l'URL del sito: your-domain.atlassian.net

Esempio di output:

Select the product your app uses.

? Select a product: Jira

Enter your site. For example, your-domain.atlassian.net

? Enter the site URL: genai-for-developers.atlassian.net

Installing your app onto an Atlassian site.
Press Ctrl+C to cancel.

? Do you want to continue? Yes

✔ Install complete!

Your app in the development environment is now installed in Jira on genai-for-developers.atlassian.net

Apri il tuo sito JIRA e crea una nuova attività JIRA con la seguente descrizione:

Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything.

Quando apri l'attività, vedrai il pulsante "devai-jira-ui-qwiklabs".

Fai clic sul pulsante e rivedi le modifiche nell'interfaccia utente.

Visualizza i log del backend di Forge.

forge logs

Atlassian Developer Console

Puoi anche visualizzare e gestire le app di cui è stato eseguito il deployment in Atlassian Developer Console.

Esamina i log: passa all'ambiente Development,

Esamina il manifest e il codice sorgente dell'applicazione Forge

Apri il file "devai-jira-ui-qwiklabs/manifest.yml" e utilizza Gemini Code Assist per spiegarlo.

Esamina la spiegazione.

Apri i seguenti file e chiedi a Gemini Code Assist di spiegarli:

devai-jira-ui-qwiklabs/src/frontend/index.jsx
devai-jira-ui-qwiklabs/src/resolvers/index.js

Aggiorna l'app Forge con l'endpoint Cloud Run dell'API DevAI

Controlla se l'ID PROGETTO GOOGLE CLOUD è impostato:

gcloud config get project

In caso contrario, imposta il progetto Google Cloud utilizzando l'ID progetto dalla pagina del lab Qwiklabs:

Esempio: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

Imposta l'URL del servizio Cloud Run:

export DEVAI_API_URL=$(gcloud run services list --filter="(devai-api)" --format="value(URL)")

forge variables set DEVAI_API_URL $DEVAI_API_URL

Conferma eseguendo il comando riportato di seguito:

forge variables list

Esempio di output

Aggiorna il codice e il file manifest dell'applicazione Forge

Questi snippet di codice sono disponibili nel repository nella cartella sample-devai-jira-ui.

Apri il file manifest nell'editor: devai-jira-ui-qwiklabs/manifest.yml

Aggiungi le righe riportate di seguito alla fine del file. Sostituisci l'endpoint Cloud Run con quello che hai disegnato.

permissions:
  scopes:
    - read:jira-work
    - write:jira-work
  external:
    fetch:
      client:
        - devai-api-gjerpi6qqq-uc.a.run.app/generate # replace with YOUR CLOUD RUN URL

Apri il file resolvers/index nell'editor: devai-jira-ui-qwiklabs/src/resolvers/index.js

Aggiungi le righe riportate di seguito dopo la funzione getText esistente.

resolver.define('getApiKey', (req) => {
  return process.env.LLM_API_KEY;
});

resolver.define('getDevAIApiUrl', (req) => {
  return process.env.DEVAI_API_URL;
});

Apri il file frontend/index nell'editor: devai-jira-ui-qwiklabs/src/frontend/index.jsx

Sostituisci index.jsx con i contenuti riportati di seguito. Aggiorna il link al tuo ID utente/repository GitLab.

Devi aggiornare YOUR-GIT-USERID e YOUR-GIT-REPO in due punti.

Cerca questa riga nel file e apporta le modifiche:

https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests

import React from 'react';
import ForgeReconciler, { Text, Link, useProductContext } from '@forge/react';
import { requestJira } from '@forge/bridge';
import { invoke } from '@forge/bridge';
import api, { route, assumeTrustedRoute } from '@forge/api';

// const apiKey = await invoke("getApiKey")
const devAIApiUrl = await invoke("getDevAIApiUrl")


const App = () => {
  const context = useProductContext();

  const [description, setDescription] = React.useState();

  const fetchDescriptionForIssue = async () => {
    const issueId = context?.extension.issue.id;
  
    const res = await requestJira(`/rest/api/2/issue/${issueId}`);
    const data = await res.json();
    
    // const genAI = new GoogleGenerativeAI(apiKey);
    // const model = genAI.getGenerativeModel({ model: "gemini-pro"});
    // const prompt = `You are principal software engineer at Google and given requirements below to implement.\nPlease provide implementation details and documentation.\n\nREQUIREMENTS:\n\n${data.fields.description}`
    // const result = await model.generateContent(prompt);
    // const text = result.response.text();
    // const jsonText = JSON.stringify(text);

    const bodyGenerateData = `{"prompt": ${JSON.stringify(data.fields.description)}}`;

    const generateRes = await api.fetch(devAIApiUrl+'/generate',
      {
        body: bodyGenerateData,
        method: 'post',
        headers: { 'Content-Type': 'application/json' },
      }
    )


    const resData = await generateRes.text();
    const jsonText = JSON.stringify(resData);

    const bodyData = `{
      "body": ${jsonText}
    }`;

    console.log("bodyData", bodyData)
    // Add Gemini response as a comment on the JIRA issue
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: bodyData
    });
    // Add link to the GitLab merge request page as a comment
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: `{"body": "[GitLab Merge Request|https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests]"}`
    });


    return "Response will be added as a comment. Please refresh in a few moments.";
  };

  React.useEffect(() => {
    if (context) {
      fetchDescriptionForIssue().then(setDescription);
    }
  }, [context]);

  return (
    <>
      <Text>{description}</Text>
      <Link href='https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests' openNewTab={true}>GitLab Merge Request</Link>
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Esegui nuovamente il deployment dell'applicazione Forge

Aggiungi le dipendenze nel file package.json:

"@forge/api": "4.0.0",

Installa le dipendenze:

npm install

Esegui il deployment dell'applicazione aggiornata:

forge deploy

Esempio di output:

ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

We've detected new scopes or egress URLs in your app.
Run forge install --upgrade and restart your tunnel to put them into effect.

Installa l'applicazione aggiornata:

forge install --upgrade

Esempio di output:

Upgrading your app on the Atlassian site.

Your app will be upgraded with the following additional scopes:
- read:jira-work
- write:jira-work

Your app will exchange data with the following urls:
- devai-api-7su2ctuqpq-uc.a.run.app

? Do you want to continue? Yes

✔ Upgrade complete!

Your app in the development environment is now the latest in Jira on genai-for-developers.atlassian.net.

Testa l'applicazione Forge

Apri un'attività JIRA esistente o creane una nuova nel tuo progetto JIRA.

Dovrai rimuovere il riquadro precedente se è già stato aggiunto.

Fai clic su "..." e seleziona Rimuovi dal menu. Dopodiché, puoi fare di nuovo clic sul pulsante.

Controllare i commenti di Jira

Una volta ricevuta una risposta dall'API DEVAI, verranno aggiunti due commenti al problema JIRA.

Richiesta di unione GitLab
Dettagli sull'implementazione delle storie utente di Gemini

Passa dalle schede "History" a "Comments" per aggiornare la visualizzazione.

Attivare la creazione di richieste di unione GitLab

Apri il file devai-api/app/routes.py e rimuovi i commenti dalle righe riportate di seguito nel metodo generate_handler:

print(f"{response.text}\n")

    # resp_text = response.candidates[0].content.parts[0].text

    # pr_prompt = f"""Create GitLab merge request using provided details below.
    # Create new files, commit them and push them to opened merge request.
    # When creating new files, remove the lines that start with ``` before saving the files.

    # DETAILS: 
    # {resp_text}
    # """

    # print(pr_prompt)
    # agent.invoke(pr_prompt)

Esegui nuovamente il deployment dell'applicazione Cloud Run

Verifica di trovarti nella cartella corretta.

cd ~/github/genai-for-developers/devai-api

Se utilizzi la stessa sessione del terminale, è possibile che tutte le variabili di ambiente siano ancora impostate.

Controlla eseguendo "echo $GITLAB_REPOSITORY" nel terminale.

Segui questi passaggi per reimpostarli se è stata aperta una nuova sessione del terminale.

Assicurati di reimpostare le variabili di ambiente richieste prima di eseguire nuovamente il deployment dell'applicazione.

Questo comando richiede l'aggiornamento dell'ID utente e del nome del repository GitLab.

export GITLAB_REPOSITORY="USERID/REPOSITORY"

Imposta le altre variabili di ambiente:

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api
export PROJECT_ID=$(gcloud config get-value project)

export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

Il toolkit GitLab utilizzerà il branch "devai" per inviare le modifiche per la richiesta di unione.

Verifica di aver già creato il ramo.

Esegui il deployment dell'applicazione in Cloud Run.

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --min-instances=1 \
  --max-instances=3

Verificare l'integrazione end-to-end

Avvia il processo dall'attività JIRA facendo di nuovo clic sul pulsante e verifica l'output nel repository GitLab, nella sezione Merge request e in LangSmith.

Dettagli della richiesta di unione di GitLab.

Tracce LLM LangSmith

Apri il portale LangSmith ed esamina la traccia LLM per la chiamata di creazione del problema JIRA.

Esempio di traccia LLM LangSmith.

(SEZIONE FACOLTATIVA) Esegui il push delle modifiche nel repository GitHub

Vai al sito web di GitHub e crea un nuovo repository per eseguire il push delle modifiche per questo lab nel tuo repository personale.

Torna all'istanza Cloud Workstations e imposta il nome utente e l'indirizzo email di Git nel terminale.

Aggiorna i valori prima di eseguire i comandi.

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

Genera la chiave SSH e aggiungila al repository GitHub.

Aggiorna l'email prima di eseguire i comandi.

Non inserire la passphrase e premere Invio più volte per completare la generazione della chiave.

ssh-keygen -t ed25519 -C "your-email-address"

eval "$(ssh-agent -s)"

ssh-add ~/.ssh/id_ed25519

cat ~/.ssh/id_ed25519.pub

Aggiungi la chiave pubblica generata al tuo account GitHub.

Apri https://github.com/settings/keys e fai clic su "New SSH key".

Per il nome della chiave, utilizza "qwiklabs-key" e copia/incolla l'output dell'ultimo comando.

Torna al terminale, esegui il commit e il push delle modifiche.

cd ~/github/genai-for-developers

git remote rm origin

Imposta l'origine remota utilizzando il repository creato sopra.

Sostituisci con l'URL del tuo repository.

git remote add origin git@github.com:YOUR-GITHUB-USERID/YOUR-GITHUB-REPO.git

Aggiungi, esegui il commit e il push delle modifiche.

git add .

git commit -m "lab changes"

git push -u origin main

15. Complimenti!

Complimenti, hai completato il lab.

Argomenti trattati:

Come eseguire il deployment di applicazioni Cloud Run per l'integrazione con le API Gemini.
Come creare ed eseguire il deployment dell'app Atlassian Forge per JIRA.
Come utilizzare gli agenti LangChain ReAct per l'automazione delle attività di GitLab.
Come esaminare le tracce LLM in LangSmith.

Passaggi successivi

Saranno presto disponibili altre sessioni pratiche.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto che hai creato per il tutorial.