1. Visão geral
Neste laboratório, você vai criar uma solução para automatizar a implementação de histórias de uso do JIRA com a IA generativa.
O que você vai aprender
Há várias partes principais no laboratório:
- Implantar o aplicativo do Cloud Run para integração com as APIs Gemini
- Criar e implantar o app Atlassian Forge para JIRA
- Agentes LangChain ReAct para automação de tarefas do GitLab
Pré-requisitos
- Para fazer este laboratório, é preciso saber usar o console do Cloud e os ambientes do Cloud Shell.
2. Configuração e requisitos
Configuração do projeto do Cloud
- Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.
- O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
- O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como
PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto. - Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.
- Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.
Configuração do ambiente
Abra o chat do Gemini.
Ou digite "Pergunte ao Gemini" na barra de pesquisa.
Ative a API Cloud AI Companion:
Clique em Start chatting e siga uma das perguntas de exemplo ou digite seu próprio comando para testar.
Sugestões de comandos:
- Explicar o Cloud Run em cinco pontos principais.
- Você é gerente de produto do Google Cloud Run e explica o Cloud Run para um estudante em cinco pontos-chave.
- Você é gerente de produto do Google Cloud Run e explica o Cloud Run para um desenvolvedor certificado do Kubernetes em cinco pontos-chave.
- Você é gerente de produto do Google Cloud Run e explica a um desenvolvedor sênior em cinco pontos principais quando usar o Cloud Run em vez do GKE.
Confira o guia de comandos para saber como escrever comandos melhores.
Como o Gemini para o Google Cloud usa seus dados
Compromisso do Google com a privacidade
O Google foi um dos primeiros no setor a publicar um compromisso de privacidade de IA/ML, que descreve que os clientes precisam ter o mais alto nível de segurança e controle sobre os dados armazenados na nuvem.
Dados que você envia e recebe
As perguntas que você faz ao Gemini, incluindo qualquer informação de entrada ou código que você envia para análise ou conclusão, são chamadas de comandos. As respostas ou códigos que você recebe do Gemini são chamados de respostas. O Gemini não usa seus comandos nem as respostas deles como dados para treinar os modelos.
Criptografia de instruções
Quando você envia comandos para o Gemini, os dados são criptografados em trânsito como entrada para o modelo subjacente no Gemini.
Dados do programa gerados pelo Gemini
O Gemini é treinado com base no código próprio do Google Cloud e em códigos de terceiros selecionados. Você é responsável pela segurança, testes e eficácia do seu código, incluindo qualquer preenchimento, geração ou análise de código que o Gemini oferece.
Saiba mais sobre como o Google processa suas solicitações.
3. Opções para testar solicitações
Você tem várias opções para testar comandos.
O Vertex AI Studio faz parte da plataforma Vertex AI do Google Cloud, projetada especificamente para simplificar e acelerar o desenvolvimento e o uso de modelos de IA generativa.
O Google AI Studio é uma ferramenta baseada na Web para prototipagem e experimentação com engenharia de comando e a API Gemini.
- Web app Gemini (gemini.google.com)
O web app Gemini (gemini.google.com) é uma ferramenta baseada na Web projetada para ajudar você a explorar e usar o poder dos modelos de IA do Gemini do Google.
- App Google Gemini para dispositivos móveis no Android e Google app no iOS
4. (SEÇÃO OPTATIVA) Criar uma conta de serviço
Essas etapas foram executadas durante a configuração do laboratório. Não é necessário executá-las.
Estas etapas mostram como configurar uma conta de serviço e papéis do IAM.
Volte ao console do Google Cloud e ative o Cloud Shell clicando no ícone à direita da barra de pesquisa.
No terminal aberto, execute os comandos a seguir para criar uma nova conta de serviço e chaves.
Você vai usar essa conta de serviço para fazer chamadas de API para a API Vertex AI Gemini no aplicativo do Cloud Run.
Configure os detalhes do projeto usando os detalhes do projeto do Qwiklabs.
Exemplo: qwiklabs-gcp-00-2c10937585bb
gcloud config set project YOUR_QWIKLABS_PROJECT_ID
Crie uma conta de serviço e conceda papéis.
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 for preciso autorizar, clique em "Autorizar" para continuar.
Ative os serviços necessários para usar as APIs Vertex AI e o chat Gemini.
gcloud services enable \
generativelanguage.googleapis.com \
aiplatform.googleapis.com \
cloudaicompanion.googleapis.com \
run.googleapis.com \
cloudresourcemanager.googleapis.com
Ative os serviços necessários para usar as APIs Vertex AI e o 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. Conceder acesso às Estações de trabalho do Cloud
Abra o Cloud Workstations no Console do Cloud.
Conceda acesso à estação de trabalho do Cloud para o estudante provisionado do Qwiklabs.
Copie o nome de usuário/e-mail do Qwiklabs criado para este projeto e use-o para adicionar um principal. Selecione a estação de trabalho e clique em "PERMISSIONS".
Confira os detalhes a seguir.
Clique no botão "ADD PRINCIPAL".
Cole o e-mail do estudante do Qwiklabs e selecione o papel "Cloud Workstations User".
Clique em "Start" e em "Launch" para abrir a estação de trabalho e seguir as etapas a seguir usando o terminal integrado.
Clone o repositório do GitHub
Crie uma pasta e clone o repositório do GitHub.
mkdir github
cd github
git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git
Usando o item de menu "File / Open Folder", abra "github/genai-for-developers".
6. Ativar o Gemini Code Assist
Clique no ícone "Gemini" no canto inferior direito e em "Login to Google Cloud".
Clique no link no terminal para iniciar o fluxo de autorização.
Clique em "Abrir" para acessar o link.
Selecione sua conta de estudante do Qwiklabs e clique em "Fazer login" na próxima tela.
Copiar o código de verificação:
Volte ao terminal e cole o código.
Aguarde a conclusão da autenticação e clique em "Selecionar um projeto do Google".
Na janela pop-up, selecione seu projeto do Qwiklabs.
Exemplo:
Abra o arquivo "devai-api/app/routes.py" e clique com o botão direito do mouse em qualquer lugar do arquivo. Em seguida, selecione "Gemini > Explain this"" no menu de contexto.
Analise a explicação do Gemini para o arquivo selecionado.
7. Kits de ferramentas do LangChain
Os Kits de ferramentas do LangChain são conjuntos de ferramentas criadas para simplificar e aprimorar o desenvolvimento de aplicativos com o LangChain. Eles oferecem várias funcionalidades, dependendo do kit de ferramentas específico, mas, em geral, ajudam com:
- Conexão a fontes de dados externas: acesse e incorpore informações de APIs, bancos de dados e outras fontes externas nos seus aplicativos do LangChain.
- Técnicas avançadas de comando: use comandos pré-criados ou crie comandos personalizados para otimizar as interações com modelos de linguagem.
- Criação e gerenciamento de cadeias: crie e gerencie cadeias complexas com facilidade.
- Avaliação e monitoramento: analise o desempenho das suas cadeias e aplicativos do LangChain.
Alguns dos Kits de ferramentas LangChain mais conhecidos incluem:
- Kits de ferramentas para executores de agentes: ferramentas para desenvolver agentes que possam interagir com o mundo real por meio de ações como navegação na Web ou execução de código.
- Kit de ferramentas de engenharia de comandos: uma coleção de recursos para criar comandos eficientes.
Kit de ferramentas do GitLab
Neste laboratório, você vai usar o Toolkit do GitLab para automatizar a criação de solicitações de mesclagem do GitLab.
O kit de ferramentas do Gitlab contém ferramentas que permitem que um agente de LLM interaja com um repositório do Gitlab. A ferramenta é um wrapper para a biblioteca python-gitlab.
O kit de ferramentas do GitLab pode realizar as seguintes tarefas:
- Create File: cria um novo arquivo no repositório.
- Read File: lê um arquivo do repositório.
- Atualizar arquivo: atualiza um arquivo no repositório.
- Criar solicitação de envio: cria uma solicitação de envio da ramificação de trabalho do bot para a ramificação base.
- Get Issues: busca problemas no repositório.
- Get Issue: busca detalhes sobre um problema específico.
- Comentário sobre o problema: publica um comentário sobre um problema específico.
- Excluir arquivo: exclui um arquivo do repositório.
8. Configuração do repositório e do kit de ferramentas do GitLab
Abra o GitLab, crie um projeto público e configure o token de acesso do projeto em "Settings / Access Tokens".
Use os seguintes detalhes:
- Nome do token:
devai-api-qwiklabs - Papel:
Maintainer - Selecione os escopos:
api
Copie e cole o valor do token de acesso em um arquivo temporário no seu laptop. Ele será usado nas próximas etapas.
9. Preparar para implantar o aplicativo no Cloud Run
Volte para a instância do Cloud Workstations e use o terminal atual ou abra um novo.
Receba as credenciais de acesso da sua conta de usuário por um fluxo de autorização baseado na Web.
Clique no link e siga as etapas para gerar o código de verificação.
gcloud auth login
Configure os detalhes do projeto usando os detalhes do projeto do Qwiklabs.
Exemplo: qwiklabs-gcp-00-2c10937585bb
gcloud config set project YOUR-QWIKLABS-PROJECT-ID
Defina o restante das variáveis de ambiente:
export PROJECT_ID=$(gcloud config get-value project)
export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api
Defina as variáveis de ambiente necessárias para a integração do GitLab.
export GITLAB_PERSONAL_ACCESS_TOKEN=gitlab-token
Para evitar a exposição de informações sensíveis no terminal, a prática recomendada é usar read -s, uma maneira segura de definir variáveis de ambiente sem que o valor apareça no histórico de comandos do console. Depois de executar, cole o valor e pressione Enter.
Esse comando exige que você atualize o ID de usuário e o nome do repositório do GitLab.
Exemplo: export GITLAB_REPOSITORY="gitrey/qwiklabs-test"
export GITLAB_REPOSITORY="USERID/REPOSITORY"
Defina o restante das variáveis de ambiente:
export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"
10. Configuração de rastreamento de LLM do LangSmith
Crie uma conta da LangSmith e gere uma chave da API Service na seção "Configurações". https://docs.smith.langchain.com/
Defina as variáveis de ambiente necessárias para a integração do LangSmith.
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
export LANGCHAIN_API_KEY=langchain-service-api-key
11. Configuração do JIRA
Esses valores não são usados neste laboratório, então não é necessário atualizar para os valores específicos do seu projeto do JIRA antes de executar os comandos.
Defina as variáveis de ambiente necessárias para a implantação do serviço do 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. Implantar a API Devai no Cloud Run
Verifique se você está na pasta certa.
cd ~/github/genai-for-developers/devai-api
Neste laboratório, seguimos as práticas recomendadas e usamos o Secret Manager para armazenar e referenciar os valores do token de acesso e da chave da API LangChain no Cloud Run.
Armazene o token de acesso do JIRA no Secret Manager.
echo -n $JIRA_API_TOKEN | \
gcloud secrets create JIRA_API_TOKEN \
--data-file=-
Armazene o token de acesso do GitLab no Secret Manager.
echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
--data-file=-
Armazene a chave da API LangChain no Secret Manager.
echo -n $LANGCHAIN_API_KEY | \
gcloud secrets create LANGCHAIN_API_KEY \
--data-file=-
Implantar o aplicativo no 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
Responda Y para criar o repositório do Docker no 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
Analise o fluxo gcloud run deploy SERVICE_NAME --source=. abaixo. Saiba mais.
Nos bastidores, esse comando usa o buildpacks e o Cloud Build do Google Cloud para criar automaticamente imagens de contêiner a partir do código-fonte sem ter que instalar o Docker na máquina ou configurar os pacotes de criação ou o Cloud Build. Ou seja, o comando único descrito acima faz o que exigiria os comandos gcloud builds submit e gcloud run deploy.
Se você tiver fornecido um Dockerfile(como fizemos neste repositório), o Cloud Build vai usá-lo para criar imagens de contêiner em vez de depender dos buildpacks para detectar e criar imagens de contêiner automaticamente. Para saber mais sobre buildpacks, consulte a documentação.
Revise os registros do Cloud Build no Console.
Revise a imagem Docker criada no Artifact Registry.
Abra cloud-run-source-deploy/devai-api e analise as vulnerabilidades detectadas automaticamente. Verifique se há correções disponíveis e como elas podem ser corrigidas com base na descrição.
Revise os detalhes da instância do Cloud Run no console do Cloud.
Teste o endpoint executando o 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
(SEÇÃO OPTATIVA) Configurar a estação de trabalho do Cloud
O Cloud Workstations oferece ambientes de desenvolvimento gerenciados no Google Cloud com segurança integrada e ambientes de desenvolvimento pré-configurados, mas personalizáveis. Em vez de exigir que os desenvolvedores instalem softwares e executem scripts de configuração, crie uma configuração de estação de trabalho que especifique seu ambiente de maneira reproduzível. Todas as atualizações de uma configuração de estação de trabalho são aplicadas automaticamente às estações de trabalho na próxima vez que elas forem iniciadas. Os desenvolvedores acessam as estações de trabalho por um ambiente de desenvolvimento integrado baseado em navegador, em vários editores de código locais (como o VSCode ou os ambientes de desenvolvimento integrado do JetBrains, como o IntelliJ IDEA Ultimate e o PyCharm Professional) ou por SSH.
O Cloud Workstations usa os seguintes recursos do Google Cloud para gerenciar seus ambientes de desenvolvimento:
- Os clusters de estações de trabalho definem um grupo de estações de trabalho em uma determinada região e a rede VPC a que estão conectadas. Os clusters da estação de trabalho não estão relacionados aos clusters do Google Kubernetes Engine (GKE).
- As configurações da estação de trabalho atuam como modelos para as estações de trabalho. A configuração da estação de trabalho define detalhes como o tipo de instância da máquina virtual (VM) da estação de trabalho, o armazenamento permanente, o ambiente de definição de imagem do contêiner, qual ambiente de desenvolvimento integrado (IDE) ou editor de código usar e muito mais. Os administradores e as equipes da plataforma também podem usar regras do Identity and Access Management (IAM) para conceder acesso a equipes ou a desenvolvedores individuais.
- As estações de trabalho são ambientes de desenvolvimento pré-configurados que fornecem um ambiente de desenvolvimento integrado na nuvem, ferramentas de linguagem, bibliotecas e muito mais. As estações de trabalho podem ser iniciadas ou interrompidas sob demanda e executadas em VMs do Compute Engine no seu projeto, com um disco persistente anexado para armazenar dados entre sessões.
Os administradores e as equipes de plataforma criam configurações de estação de trabalho que são compartilhadas com a equipe de desenvolvimento. Cada desenvolvedor cria uma estação de trabalho com base em uma configuração.
Neste laboratório, você está usando um ambiente de desenvolvimento integrado baseado em navegador, mas o Cloud Workstations também oferece suporte a outras interfaces de desenvolvimento comuns:
- Você pode usar seus próprios ambientes de desenvolvimento integrados do JetBrains pelo JetBrains Gateway.
- Se você usa o VSCode local, também pode acessar suas estações de trabalho para desenvolvimento remoto via SSH.
- Também é possível configurar túneis SSH e até mesmo TCP na estação de trabalho usando a máquina local.
(SEÇÃO OPCIONAL) Criar cluster de estações de trabalho
Essas etapas foram executadas durante a configuração do laboratório. Não é necessário executá-las.
Estas etapas mostram como configurar o cluster, a configuração e a estação de trabalho do Cloud Workstations.
Revise esta seção e passe para a seção "Plataforma Forge".
Criar cluster de estações de trabalho:
gcloud workstations clusters create ws-cluster --region=us-central1
Criar configuração de estações de trabalho
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
Criar estação de trabalho
gcloud workstations create devai-workstation \
--cluster=ws-cluster \
--config=devai-config \
--region=us-central1
Confira as estações de trabalho disponíveis no console do Cloud. Inicie e abra "devai-workstation".
Ative "Gemini" no canto inferior direito, siga o fluxo de login na nova guia do navegador e copie o código gerado de volta para o console para concluir o login.
Abra o chat "Gemini" no painel à esquerda e pergunte ao 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. Plataforma Forge
O Forge é uma plataforma que permite aos desenvolvedores criar apps integrados aos produtos da Atlassian, como Jira, Confluence, Compass e Bitbucket.
Instalar a CLI do Forge
Execute os comandos abaixo no terminal.
Faça o download do Node Version Manager ( nvm) e disponibilize-o no caminho da sessão atual do terminal.
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
Instale o nvm.
Selecione a versão mais recente do Node.js LTS executando o seguinte no terminal:
nvm install --lts
nvm use --lts
Instale a CLI do Forge globalmente executando o seguinte:
npm install -g @forge/cli
Neste laboratório, vamos usar variáveis de ambiente para fazer login.
Configurar projeto do JIRA
Use sua conta pessoal para criar/acessar projetos do JIRA.
Revise seus projetos do JIRA: https://admin.atlassian.com/
Crie um novo projeto do JIRA usando sua conta pessoal.
Acesse https://team.atlassian.com/your-work, clique em 
e selecione 
. Depois disso, selecione "JIRA Software" - "Testar agora". Siga as instruções para concluir a criação do projeto/site.
Selecione o software JIRA.
Crie um novo projeto.
14. Token da API Atlassian
Crie ou use um token de API da Atlassian para fazer login na CLI.
A CLI usa seu token ao executar comandos.
- Acesse https://id.atlassian.com/manage/api-tokens.
- Clique em Criar token de API.
- Insira um rótulo para descrever o token da API. Por exemplo, forge-api-token.
- Clique em Criar.
- Clique em Copiar para a área de transferência e feche a caixa de diálogo.
Execute o comando abaixo no terminal do Cloud Workstations.
Faça login na CLI do Forge para começar a usar os comandos do Forge.
Defina seu endereço de e-mail do JIRA/FORGE. Substitua pelo seu endereço de e-mail.
export FORGE_EMAIL=your-email
Defina o token da API Forge. Substitua pelo seu token da API do JIRA.
export FORGE_API_TOKEN=your-jira-api-token
Execute o comando abaixo para testar a CLI do Forge. Responda "No" quando solicitado a coletar análises.
forge settings set usage-analytics false
Verifique se você fez login.
forge whoami
Exemplo de saída.
Logged in as John Green (johngreen@email.com) Account ID: 123090:aaabbcc-076a-455c-99d0-d1aavvccdd
Criar um aplicativo Forge
Verifique se você está na pasta "~/github/genai-for-developers".
Execute o comando para criar um aplicativo do Forge.
forge create
Use os seguintes valores quando solicitado:
- Nome do aplicativo:
devai-jira-ui-qwiklabs - Selecione uma categoria:
UI Kit - Selecione um produto:
Jira - Selecione um modelo:
jira-issue-panel
Mude para a pasta do aplicativo.
cd devai-jira-ui-qwiklabs/
Execute o comando de implantação.
forge deploy
Exemplo de resposta:
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.
Instale o aplicativo.
forge install
Use os seguintes valores quando solicitado:
- Selecione um produto:
Jira - Digite o URL do site:
your-domain.atlassian.net
Exemplo de resposta:
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
Abra seu site do JIRA e crie uma nova tarefa com a seguinte descrição:
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.
Ao abrir a tarefa, você vai encontrar o botão "devai-jira-ui-qwiklabs".
Clique no botão e revise as mudanças na interface.
Acessar registros de back-end do Forge.
forge logs
Atlassian Developer Console
Também é possível conferir e gerenciar apps implantados no Console do desenvolvedor da Atlassian.
Analisar registros: alternar para o ambiente Development,
Revisar o manifesto e o código-fonte do aplicativo Forge
Abra o arquivo "devai-jira-ui-qwiklabs/manifest.yml" e use o Gemini Code Assist para explicar o código.
Leia a explicação.
Abra os seguintes arquivos e peça ao Gemini Code Assist para explicar:
devai-jira-ui-qwiklabs/src/frontend/index.jsxdevai-jira-ui-qwiklabs/src/resolvers/index.js
Atualizar o app Forge com o endpoint do Cloud Run da API DevAI
Verifique se o ID do projeto do GCP está definido:
gcloud config get project
Caso contrário, defina seu projeto do GCP usando o ID do projeto na página do laboratório do Qwiklabs:
Exemplo: qwiklabs-gcp-00-2c10937585bb
gcloud config set project YOUR_QWIKLABS_PROJECT_ID
Defina o URL do serviço do 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
Confirme executando o comando abaixo:
forge variables list
Exemplo de saída
Atualizar o manifesto e o código do aplicativo Forge
Esses snippets de código podem ser encontrados no repositório na pasta sample-devai-jira-ui.
Abra o arquivo de manifesto no editor: devai-jira-ui-qwiklabs/manifest.yml
Adicione as linhas abaixo no final do arquivo. Substitua o endpoint do Cloud Run pelo que você implantou.
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
Abra o arquivo de indexadores/resolvers no editor: devai-jira-ui-qwiklabs/src/resolvers/index.js
Adicione as linhas abaixo após a função getText atual.
resolver.define('getApiKey', (req) => {
return process.env.LLM_API_KEY;
});
resolver.define('getDevAIApiUrl', (req) => {
return process.env.DEVAI_API_URL;
});
Abra o arquivo de front-end/índice no editor: devai-jira-ui-qwiklabs/src/frontend/index.jsx
Substitua index.jsx pelo conteúdo abaixo. Atualize o link para o ID do usuário/repositório do GitLab.
Há dois lugares em que você precisa atualizar YOUR-GIT-USERID e YOUR-GIT-REPO.
Procure esta linha no arquivo e faça as alterações:
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>
);
Reimplantar o aplicativo Forge
Adicione dependências no arquivo package.json:
"@forge/api": "4.0.0",
Instale as dependências:
npm install
Implante o aplicativo atualizado:
forge deploy
Exemplo de resposta:
ℹ 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.
Instalar o aplicativo atualizado:
forge install --upgrade
Exemplo de resposta:
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.
Testar o aplicativo Forge
Abra ou crie uma tarefa do JIRA no seu projeto.
Se o painel anterior já tiver sido adicionado, você vai precisar removê-lo.
Clique em "..." e selecione "Remover" no menu. Depois disso, clique no botão novamente.
Verificar comentários do Jira
Depois que você receber uma resposta da API DEVAI, dois comentários serão adicionados ao problema do JIRA.
- Solicitação de mesclagem do GitLab
- Detalhes da implementação da história de usuário do Gemini
Alterne entre as guias "History" e "Comments" para atualizar a visualização.
Ativar a criação de solicitações de mesclagem do GitLab
Abra o arquivo devai-api/app/routes.py e remova a marca de comentário das linhas abaixo no método 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)
Reimplantar o aplicativo do Cloud Run
Verifique se você está na pasta certa.
cd ~/github/genai-for-developers/devai-api
Se você estiver usando a mesma sessão de terminal, talvez todas as variáveis de ambiente ainda estejam definidas.
Confira executando "echo $GITLAB_REPOSITORY" no terminal.
Siga estas etapas para redefinir o terminal se uma nova sessão tiver sido aberta.
Redefina as variáveis de ambiente necessárias antes de implantar o aplicativo novamente.
Esse comando exige que você atualize o ID de usuário e o nome do repositório do GitLab.
export GITLAB_REPOSITORY="USERID/REPOSITORY"
Defina o restante das variáveis de 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
O kit de ferramentas do GitLab vai usar a ramificação "devai" para enviar as mudanças para a solicitação de mesclagem.
Verifique se você já criou essa ramificação.
Implantar o aplicativo no 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
Verificar a integração completa
Inicie o processo na tarefa do JIRA clicando no botão novamente e verifique a saída no repositório do GitLab, na seção "Solicitação de mesclagem" e em LangSmith.
Detalhes do pedido de mesclagem do GitLab.
Rastros de LLM do LangSmith
Abra o portal do LangSmith e analise o rastro do LLM para a chamada de criação de problemas do JIRA.
Exemplo de rastreamento de LLM do LangSmith.
(SEÇÃO OPCIONAL) Enviar suas alterações para o repositório do GitHub
Acesse o site do GitHub e crie um novo repositório para enviar as mudanças deste laboratório ao seu repositório pessoal.
Volte para a instância do Cloud Workstations e defina o nome de usuário e o e-mail do Git no terminal.
Atualize os valores antes de executar os comandos.
git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"
Gere uma chave SSH e adicione-a ao repositório do GitHub.
Atualize seu e-mail antes de executar os comandos.
Não insira a senha longa e pressione Enter várias vezes para concluir a geração de chaves.
ssh-keygen -t ed25519 -C "your-email-address"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
Adicione a chave pública gerada à sua conta do GitHub.
Abra https://github.com/settings/keys e clique em "New SSH key".
Para o nome da chave, use "qwiklabs-key" e copie e cole a saída do último comando.
Volte ao terminal, confirme e envie as mudanças.
cd ~/github/genai-for-developers
git remote rm origin
Defina a origem remota usando o repositório criado acima.
Substitua pelo URL do repositório.
git remote add origin git@github.com:YOUR-GITHUB-USERID/YOUR-GITHUB-REPO.git
Adicione, confirme e envie as mudanças.
git add .
git commit -m "lab changes"
git push -u origin main
15. Parabéns!
Parabéns, você concluiu o laboratório!
O que aprendemos:
- Como implantar aplicativos do Cloud Run para integração com as APIs Gemini.
- Como criar e implantar o app Atlassian Forge para JIRA.
- Como usar os agentes LangChain ReAct para automatizar tarefas do GitLab.
- Como analisar rastros de LLM no LangSmith.
O que vem em seguida:
- Mais sessões práticas estão chegando!
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto ou mantenha o projeto e exclua cada um dos recursos.
Excluir o projeto
O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para este tutorial.
©2024 Google LLC Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de empresas e produtos podem ser marcas registradas das empresas a que estão associados.