Implante apps rapidamente com o App Design Center

1. Introdução

Neste codelab, você vai aprender a implantar um aplicativo full-stack usando o App Design Center (ADC) do Google Cloud. Você vai implantar o aplicativo "The Cymbal London Concierge", que inclui um front-end Vue 3, um back-end FastAPI e um servidor MCP que contém os dados do aplicativo.

Com o ADC, você define a arquitetura do aplicativo visualmente e a implanta como uma única unidade, gerenciando dependências e conexões automaticamente.

Atividades deste laboratório

• Configure o App Design Center.
• Monte visualmente os componentes do aplicativo.
• Implante a arquitetura do aplicativo.
• Verifique o aplicativo em execução.
• Verifique se o aplicativo foi registrado no App Hub.
• Verifique as métricas, os rastreamentos e os registros do aplicativo no Application Monitoring.

O que é necessário

• Um navegador da Web, como o Chrome.
• Ter um projeto do Google Cloud com o faturamento ativado.

Este codelab é destinado a desenvolvedores de todos os níveis, incluindo iniciantes.

Duração estimada:45 minutos Custo estimado:menos de US $2,00

2. Configuração

Configurar o projeto

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
2. Depois de se conectar ao Cloud Shell, verifique sua autenticação:

   gcloud auth list
   

3. Confirme se o projeto está configurado:

   gcloud config get project
   

4. Se o projeto não estiver definido como esperado, faça o seguinte:

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

3. Configurar o App Design Center

Antes de montar o aplicativo, configure seu espaço de trabalho no ADC.

1. No console do Google Cloud, pesquise App Design Center e acesse-o.
2. Se esta for a primeira vez que você usa o ADC neste projeto, uma tela de configuração vai aparecer.
3. Clique em Acessar a configuração.

4. Será solicitado que você ative as APIs necessárias, caso elas ainda não estejam ativadas. Clique em Ativar para continuar.

4. Conheça os recursos do ADC

Nesta tarefa, você vai conhecer os principais componentes do ADC: espaços, catálogos e modelos.

ADC Spaces

Um espaço é um local para criar modelos e implantar apps. Cada espaço pertence a um projeto na nuvem do Google Cloud. O ADC cria um espaço padrão durante a configuração inicial, mas você pode criar outros espaços em regiões diferentes depois.

Para acessar seus espaços pelo terminal, siga estas etapas:

1. Clique em Abrir editor na barra de ferramentas do Cloud Shell ou use o terminal.
2. Execute este comando:

gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

Você vai ver uma saída parecida com esta, indicando que o espaço padrão está presente na região.

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. Montar o modelo

Nesta etapa, você vai assumir a função de um engenheiro da equipe de plataforma. Seu objetivo é criar um modelo reutilizável, seguro e em conformidade para aplicativos com agentes na sua organização. Você vai adicionar componentes e configurar restrições para garantir que qualquer aplicativo implantado com base nesse modelo esteja em conformidade com as políticas de nuvem da sua empresa.

1. Criar um design

1. No console do ADC, clique em Modelos > Criar modelo.
2. Nomeie o modelo simple-3-tier-agentic-app, já que ele será usado para implantar o aplicativo Cymbal London Concierge e outros semelhantes.

2. Adicionar o servidor MCP de dados

Esse componente processa as interações com o banco de dados e a pesquisa vetorial.

1. Clique em Adicionar componente > Cloud Run (serviço). Se você clicar nesse componente, vai aparecer um ID do componente no canto superior direito. Ele vai estar no formato cloud-run-1. Podemos mudar para data-mcp-server editando na visualização de código (discutida mais adiante), mas vamos deixar como está.
2. Insira o nome do serviço: data-mcp-server.
3. Em Mostrar configurações avançadas, defina Membros como: allUsers. Observação: em um ambiente de produção, você provavelmente restringiria isso, mas usamos aqui para simplificar o codelab.
4. Em Mostrar configurações avançadas, defina o ACESSO À VPC e a Saída como: PRIVATE_RANGES_ONLY.
5. Opcionalmente, em Mostrar configurações avançadas, desmarque Ativar arquivo secundário do Prometheus.
6. Clique em Salvar.

3. Adicionar o back-end do agente

Este é o aplicativo FastAPI que orquestra o comportamento agêntico.

1. Clique em Adicionar componente > Cloud Run (serviço).
2. Dê o nome agent-backend a ela.
3. Em Mostrar campos avançados, marque a caixa Criar conta de serviço e adicione as seguintes funções em Funções do projeto da conta de serviço, uma de cada vez:
   • roles/monitoring.metricWriter
   • roles/logging.logWriter
   • roles/cloudtrace.agent
   • roles/telemetry.writer
   • roles/serviceusage.serviceUsageConsumer. Essas funções permitem que o agente use o Cloud Monitoring, o Cloud Logging e o Cloud Trace. Configuração de compliance:a equipe da plataforma aplica o princípio de privilégio mínimo listando explicitamente os papéis necessários.
   
4. Em Mostrar configurações avançadas, defina Membros como: allUsers.
5. Em Mostrar configurações avançadas, defina o ACESSO À VPC e a Saída como: PRIVATE_RANGES_ONLY.
6. Opcionalmente, em Mostrar configurações avançadas, desmarque Ativar sidecar do Prometheus.
7. Conecte agent-backend a data-mcp-server arrastando uma conexão de agent-backend para data-mcp-server.
8. Clique em Salvar.

4. Adicionar o front-end

A interface de front-end.

1. Clique em Adicionar componente > Cloud Run (serviço).
2. Insira o nome do serviço: frontend.
3. Em Mostrar configurações avançadas, desmarque Criar conta de serviço.
4. Em Mostrar configurações avançadas, defina o Ingress como: INGRESS_TRAFFIC_INTERNAL_LOADBALANCER. Configuração de compliance:o acesso público direto ao contêiner de front-end é bloqueado, forçando o tráfego pelo balanceador de carga.
5. Em Mostrar configurações avançadas, defina os Membros como: allUsers.
6. Opcionalmente, em Mostrar configurações avançadas, desmarque Ativar sidecar do Prometheus.
7. Clique em Salvar.
8. Conecte frontend a agent-backend arrastando uma conexão de frontend para agent-backend.

5. Adicionar um componente da Vertex AI

1. Clique em Adicionar componente > Vertex AI.
2. Dê o nome vertex-ai a ela.
3. Conecte-o ao agent-backend e ao data-mcp-server arrastando duas conexões do vertex-ai para o agent-backend e o data-mcp-server, respectivamente. Os papéis aiplatform.user já estão atribuídos às contas de serviço de agent-backend e data-mcp-server por estarem conectadas ao componente da Vertex AI.

6. Adicionar o balanceador de carga global

O balanceador de carga expõe seu front-end à Internet pública. No ADC, isso é dividido em um componente de back-end e um de front-end.

A. Adicionar o back-end do balanceador de carga

1. Clique em **Adicionar componente > Cloud Load Balancing global (backend).
2. Dê o nome galb-backend a ela.
3. Clique em Adicionar conexão e conecte a frontend.

B. Adicionar o front-end do balanceador de carga

1. Clique em **Adicionar componente > Cloud Load Balancing global (front-end).
2. Dê o nome galb-frontend a ela.
3. Clique em Adicionar conexão e conecte a galb-backend.
4. Conecte galb-frontend a galb-backend arrastando uma conexão de galb-frontend para galb-backend.

Compartilhar o modelo no catálogo

Um catálogo permite compartilhar modelos de apps em diferentes espaços, possibilitando a governança da arquitetura. Um catálogo funciona como um repositório central de modelos criados e aprovados para compartilhamento pela equipe da plataforma. Compartilhar catálogos entre espaços evita o trabalho duplicado em projetos comuns e agiliza os tempos de inicialização.

Agora, adicione seu modelo ao catálogo:

1. Clique na guia Catálogos.
2. Clique em Adicionar modelos e selecione o modelo simple-3-tier-agentic-app.
3. Clique em Adicionar ao catálogo.

Você pode encontrar modelos em três locais: Modelos do Google (padrões predefinidos), Modelos compartilhados (compartilhados em toda a organização) e Modelos (projetos personalizados no seu espaço).

6. Implantar o aplicativo

Agora é hora de você assumir o papel de um desenvolvedor de apps que quer usar esse modelo para implantar o aplicativo cymbal-london-concierge.

1. No console do ADC, reabra o modelo na guia Modelos e clique no botão Configurar app.
2. Clique em Criar novo aplicativo.
3. Configure o aplicativo:
   • Nome do aplicativo: cymbal-london-concierge
   • Projeto de implantação: o ID do projeto
   • Região: us-central1
   • Atributos de entrada>Ambiente: Development
   • Atributos de entrada>Gravidade: Low
4. Clique em Criar aplicativo.Para uma implantação de produção, selecione "Produção" em "Ambiente" e "Alta" em "Gravidade". Essas são tags que ajudam suas equipes de SRE e operações a classificar e priorizar o trabalho em qualquer problema que ocorra.
5. Isso vai abrir a página de detalhes da implantação com o modelo de aplicativo. Como esse é apenas um modelo, ainda precisamos adicionar uma configuração específica para nosso aplicativo.
6. Vamos configurar o front-end. Clique no componente frontend.
   1. Clique em Contêineres > Editar contêiner.
   2. Precisamos substituir a imagem do contêiner genérica pela que queremos usar no aplicativo.
   3. Defina a Imagem do contêiner como: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
   4. Defina a porta http1 como 80.
   5. Defina as seguintes variáveis de ambiente:
      • API_BASE_URL: module.cloud-run-2.service_uri. Verifique se cloud-run-2 é o nome do componente de back-end do agente. Caso contrário, substitua pelo nome real do componente.
   6. Clique em Salvar.
7. Vamos configurar o back-end do agente. Clique no componente agent-backend.
   1. Clique em Contêineres > Editar contêiner.
   2. Precisamos substituir a imagem do contêiner genérica pela que queremos usar no aplicativo.
   3. Defina a Imagem do contêiner como: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1
   4. Defina as seguintes variáveis de ambiente:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DATA_BACKEND_URL: module.cloud-run-1.service_uri. Verifique se cloud-run-1 é o nome do componente do servidor mcp de dados. Caso contrário, substitua pelo nome real do componente.
   8. Defina a porta http1 como 8000.
   9. Clique em Salvar.
8. Vamos configurar o servidor mcp de dados. Clique no componente data-mcp-server.
   1. Clique em Contêineres > Editar contêiner.
   2. Precisamos substituir a imagem do contêiner genérica pela que queremos usar no aplicativo.
   3. Defina a Imagem do contêiner como: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1
   4. Defina as seguintes variáveis de ambiente:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DB_TYPE: sqlite
   8. EMBEDDING_MODEL: text-embedding-005
   9. Defina a porta http1 como 8002.
   10. Clique em Salvar.
   Em um cenário de produção real, você também configuraria um banco de dados como o CloudSQL ou o AlloyDB e forneceria a string de conexão do banco de dados para o servidor mcp de dados. Mas, neste laboratório, vamos usar um banco de dados na memória. Você também tornaria o servidor mcp e o banco de dados privados e acessíveis apenas pelo back-end do agente ou pela rede.
9. Clique no botão Código na parte de cima da página para conferir o código do Terraform do aplicativo. Você também pode baixar o código do Terraform para o aplicativo clicando no botão Get Code para armazená-lo na sua base de código.
10. Clique no botão Implantar no canto superior direito da página para implantar o aplicativo.
11. A página de implantação vai pedir que você crie uma conta de serviço para o pipeline de implantação ou escolha uma já existente. Clique em Criar conta de serviço (um nome será preenchido automaticamente) e em Continuar. Isso vai levar alguns segundos para criar uma nova conta de serviço.

12. Depois que a conta de serviço for criada, a página será atualizada, e você verá a opção "Selecionar conta de serviço" com uma marca de seleção ao lado.

13. Em seguida, clique em Implantar na parte de baixo da página.
14. Essa operação leva alguns minutos. Quando a implantação estiver concluída, uma marca de seleção verde vai aparecer ao lado de cada componente. Também é possível verificar o status da implantação clicando no botão Link para registros, que abre os registros do Cloud Build. Pode levar alguns minutos para que o botão apareça.

![Deployment Logs](./img/10b_logs.png)

15. É possível conferir os registros do Cloud Build para ver o status da implantação ou se há erros que podem ocorrer durante a implantação do aplicativo. Você também pode acessar diretamente os registros do Cloud Build pesquisando Cloud Build no console do Google Cloud e clicando em Histórico. A implantação do aplicativo leva de 5 a 8 minutos.

![Cloud Build](./img/10c_cloudbuild.png)

16. Quando a implantação for concluída, uma marca de seleção verde vai aparecer ao lado do campo Status da implantação.

![Deployment Complete](./img/11_deployed.png)

7. Verificar o aplicativo

Vamos testar se o agente está ativo. Na seção outputs da página de detalhes da implantação, você vai encontrar o URL do componente de front-end. Copie e cole o URL no navegador. Use http e não https. Aceite também os avisos que aparecerem no navegador, porque o front-end está usando http.

Converse com o app e peça para ele criar um roteiro de viagem para Londres.

8. App Hub e monitoramento de aplicativos

1. No console do ADC, clique no botão Ver app no App Hub no canto superior direito da página.

2. Isso vai abrir o app no App Hub. O App Hub é um local central para visualizar e gerenciar todos os seus aplicativos, fazendo a transição de uma visualização centrada em recursos para uma centrada em aplicativos. Criar um app usando a ADC cria automaticamente um app no App Hub. Todas as cargas de trabalho e serviços que compõem o aplicativo vão aparecer aqui. Em vez de ver os recursos na nuvem como individuais, você pode vê-los como parte de um único aplicativo, simplificando o gerenciamento e a governança.

3. Clique no botão Ver em Observabilidade. Isso vai abrir o aplicativo no console do Observability.
4. Abra a visualização do painel. O painel oferece uma visão geral do desempenho e da integridade do aplicativo com métricas como os quatro sinais de ouro: taxa de solicitação, taxa de erros, latência e saturação. Esse monitoramento focado no aplicativo é essencial para manter a confiabilidade. Você também pode conferir Registros e Rastreamentos do aplicativo para correlacionar indicadores e identificar gargalos. Isso é especialmente importante em um aplicativo de agente complexo como este, em que respostas lentas da Vertex AI ou do servidor Data MCP podem prejudicar a experiência do usuário.

5. Exploração guiada: faça uma pergunta específica ao agente no app (por exemplo, "Quais são os melhores lugares para visitar em Londres?"). Em seguida, volte ao console de observabilidade e confira a lista Traces. Encontre o rastreamento correspondente à sua solicitação. Clique nele para ver a visualização detalhada em cascata. Observe como é possível ver o tempo gasto no front-end, no back-end do agente e nas chamadas para a Vertex AI. Isso permite identificar exatamente onde a latência é introduzida.

9. Parabéns

Parabéns! Você implantou uma arquitetura de aplicativo de três níveis usando o ADC.

O que você aprendeu

• Como montar visualmente uma arquitetura de nuvem usando o ADC.
• Como configurar o ADC e ativar APIs pela interface.
• Como implantar aplicativos usando o ADC.
• Como usar o App Hub para ter uma visão centrada no aplicativo dos seus recursos.
• Como monitorar a integridade do aplicativo usando o painel de observabilidade.

Documentos de referência

• Documentação do ADC
• Documentação do App Hub
• Monitoramento de aplicativos