1. Introdução
Visão geral
Neste laboratório, mostramos como implementar com segurança uma invocação orientada por eventos de um agente do ADK implantado no Cloud Run usando os serviços do Eventarc e do Pub/Sub. Na maioria das vezes, um agente é chamado diretamente por um usuário ou outro agente. No entanto, quando um agente está sendo integrado a fluxos de trabalho baseados em eventos, fazer uma chamada direta exige mudanças no software atual. Acionar uma invocação de agente com base em um evento permite incorporar um agente aos fluxos de trabalho atuais sem mudanças neles.
Atividades deste laboratório
Neste laboratório, você vai criar um aplicativo de agente do ZooKeeper com um agente de IA e usar algumas ferramentas para fornecer informações sobre animais no zoológico imaginário.
Você vai implantar o aplicativo ZooKeeper como um serviço no Cloud Run, que é uma plataforma de computação sem servidor totalmente gerenciada que executa contêineres sem estado na infraestrutura do Google. Em seguida, você vai configurar um gatilho do Eventarc que vai invocar o endpoint do serviço para processar de forma assíncrona as mensagens publicadas em um tópico do Pub/Sub. Você vai garantir que a implantação siga as práticas recomendadas, incluindo o uso de contas de serviço do IAM designadas, a concessão de acesso com privilégios mínimos e a minimização de uma possível superfície de ataque expondo o endpoint do aplicativo ZooKeeper apenas ao Eventarc. Você vai fazer isso com a ajuda do Cloud Shell e do console do Cloud. Você vai usar as bibliotecas do ADK e do SDK Cloud para Python. Para verificar o comportamento, use a CLI gcloud.
O que você vai aprender
- Implante o agente do ADK no Google Cloud Run.
- Integre o gatilho do Eventarc com o agente do ADK em execução no Google Cloud Run.
- Proteja sua implantação e integração com o Eventarc usando o princípio de acesso com privilégio mínimo com a ajuda do Google Cloud IAM.
- Publicar e extrair mensagens do Pub/Sub.
- Minimizar a exposição pública do aplicativo implantado no Google Cloud Run.
O que é necessário
- Navegador da Web Chrome †
- Uma Conta do Google pessoal ‡
- Um projeto do Google Cloud vinculado a uma conta de faturamento ativa
Sua conta precisa ter acesso ao IAM do projeto para provisionar recursos e configurar o acesso do IAM a eles.
† A experiência do usuário com outros navegadores pode ser diferente da descrita no laboratório.
‡ O uso de uma conta corporativa ou escolar pode limitar a realização de algumas operações descritas no laboratório.
2. configuração do ambiente
Para garantir um ambiente de desenvolvimento totalmente funcional para o laboratório, você vai usar o Google Cloud Shell, que tem todas as ferramentas necessárias pré-instaladas. Siga as instruções para configurar o ambiente.
Caso não tenha, crie uma Conta do Google.
Instruções de configuração
- Use sua Conta do Google para fazer login no Console do Google Cloud.
- 👉 Abra o seletor de projetos na barra de navegação superior (pode estar escrito "Selecionar um projeto" ou mostrar o nome de um projeto atual) ou clique no atalho de teclado
Ctrl+Oe escolha um projeto atual ou crie um novo.A criação de um novo projeto leva alguns segundos. Aguarde até que ele esteja pronto e selecione-o usando o seletor de projetos.
- 👉 Clique no ícone do Cloud Shell na parte de cima do console do Google Cloud. (marcado com o retângulo vermelho):
Se solicitado, clique em **Autorizar** na caixa de diálogo pop-up para aprovar o uso das credenciais da sua conta pelo Cloud Shell.
- 👉💻 Verifique se a CLI gcloud está configurada para usar o projeto selecionado (ou criado). Execute o comando a seguir para verificar o ID do projeto configurado:
gcloud config get-value projectYour active configuration is: [cloudshell-19597] [PROJECT_ID]
[PROJECT_ID]é o ID do projeto selecionado ou criado.👉💻 Se outro valor aparecer, execute o comando a seguir para configurar o ID do projeto como padrão para os comandos da CLI gcloud:gcloud config set project [YOUR_PROJECT_ID]gcloud config set project lab-project-id-example-123
gcloud projects list \ --format='value(projectId)' \ --sort-by='~createTime'
- 👉💻 Configure o local para provisionar recursos e o ID e o número do projeto nas variáveis de ambiente:
export LOCATION="us-central1" export PROJECT_ID=$(gcloud config get-value project) export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") - 👉💻 Ative as APIs do Google necessárias para este laboratório.
gcloud services enable \ aiplatform.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ pubsub.googleapis.comOperation "operations/ab12345c-6e7f-8ghi-jkl9-m0e1d23456f7" finished successfully.
3. Implantar o aplicativo de demonstração do ZooKeeper
As etapas a seguir provisionam e configuram recursos, incluindo a implantação do aplicativo de IA generativa.
Configurar recursos do Pub/Sub
Você vai criar dois tópicos do Pub/Sub. Um será usado por um serviço de terceiros para enviar eventos ao seu aplicativo de IA generativa. Outro para o aplicativo publicar os resultados do processamento de eventos.
- 👉💻 Crie um tópico do Pub/Sub usado para acionar o aplicativo de IA generativa:
gcloud pubsub topics create invoke_agent export INVOKE_TOPIC_ID=$(gcloud pubsub topics describe invoke_agent --format="value(name)") - 👉💻 Crie um tópico do Pub/Sub em que o aplicativo possa postar as respostas:
gcloud pubsub topics create agent_responses export RESPONSE_TOPIC_ID=$(gcloud pubsub topics describe agent_responses --format="value(name)") gcloud pubsub subscriptions create agent_responses \ --topic=agent_responses
Configurar contas de serviço e políticas do IAM no nível do projeto
Você vai criar duas contas de serviço para limitar o escopo de acesso do serviço do Cloud Run e do gatilho do Eventarc ao mínimo, seguindo o princípio de acesso com privilégio mínimo. O serviço do Cloud Run exige permissões para gravar registros e rastreamentos, chamar o LLM do Gemini no Google Vertex AI e postar resultados em um tópico do Pub/Sub. O acesso mínimo do gatilho do Eventarc exige permissões para chamar o serviço ZooKeeper do Cloud Run e acessar o Pub/Sub para ler os eventos postados. Estas instruções orientam você a conceder à conta de serviço do gatilho as permissões necessárias para representar o serviço do sistema Pub/Sub. Depois de criar o recurso de gatilho do Eventarc, execute o comando que concede o papel roles/run.invoker para permitir que a conta de serviço do gatilho chame o serviço do Cloud Run.
- 👉💻 Crie uma conta de serviço para o serviço do Cloud Run:
gcloud iam service-accounts create zookeeper-cloudrun-sa export ZOOKEEPER_SA="zookeeper-cloudrun-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Conceda à conta de serviço permissões para gravar registros e rastreamentos e usar modelos do Gemini na Vertex AI:
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/logging.logWriter" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/cloudtrace.agent" \ --condition=None gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/aiplatform.user" \ --condition=None - 👉💻 Conceda à conta de serviço permissões para postar mensagens no tópico "agent_responses":
gcloud pubsub topics add-iam-policy-binding agent_responses \ --member="serviceAccount:${ZOOKEEPER_SA}" \ --role="roles/pubsub.publisher" - 👉💻 Crie uma conta de serviço para o gatilho do Eventarc:
gcloud iam service-accounts create zookeeper-trigger-sa export TRIGGER_SA="zookeeper-trigger-sa@${PROJECT_ID}.iam.gserviceaccount.com" - 👉💻 Conceda à conta de serviço do sistema do Pub/Sub permissões para fazer solicitações push autenticadas:
gcloud iam service-accounts add-iam-policy-binding "${TRIGGER_SA}" \ --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Como implantar o app ZooKeeper no Cloud Run
Você vai baixar o código do aplicativo de demonstração no GitHub. e implante o código no Cloud Run.
- 👉💻 Baixe o aplicativo de IA agêntica:
mkdir zoo-keeper-lab && cd zoo-keeper-lab git init git remote add origin https://github.com/GoogleCloudPlatform/devrel-demos git config set core.sparseCheckout true echo "ai-ml/agent-labs/adk_invoke_with_pubsub/" >> .git/info/sparse-checkout git pull origin main --depth 1 cd ai-ml/agent-labs/adk_invoke_with_pubsub/ - 👉💻 Implante o aplicativo de IA com agentes no Cloud Run:
gcloud run deploy zookeeper-agent \ --region="${LOCATION}" \ --source="." \ --no-allow-unauthenticated \ --quiet \ --service-account="${ZOOKEEPER_SA}" \ --set-env-vars="REPLY_TOPIC_ID=${RESPONSE_TOPIC_ID}"
Configurar o gatilho do Eventarc
Depois de preparar todos os recursos (tópicos do Pub/Sub, contas de serviço do IAM e serviço do Cloud Run), é hora de configurar o recurso de gatilho do Eventarc. Você vai criar o recurso de gatilho do Eventarc e conceder permissões para chamar o serviço do Cloud Run à conta de serviço do gatilho.
- 👉💻 Crie um gatilho do Eventarc:
gcloud eventarc triggers create invoke-agent \ --location="${LOCATION}" \ --destination-run-service="zookeeper-agent" \ --destination-run-path="/zookeeper" \ --destination-run-region="${LOCATION}" \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --transport-topic="${INVOKE_TOPIC_ID}" \ --service-account="${TRIGGER_SA}" - 👉💻 Conceda permissões à conta de serviço do gatilho para invocar o serviço do Cloud Run:
gcloud run services add-iam-policy-binding zookeeper-agent \ --region="${LOCATION}" \ --member="serviceAccount:${TRIGGER_SA}" \ --role="roles/run.invoker"
4. Analisar o funcionamento da solução
Agora revise o que você acabou de implantar. O diagrama a seguir reflete todos os recursos e como eles interagem entre si. Você vai usar a gcloud CLI para publicar uma mensagem no tópico "invoke_agent". Isso simula um evento que um serviço de terceiros registra no serviço de mensagens para invocar o aplicativo de IA generativa.
A implantação é protegida seguindo o acesso com privilégio mínimo. O serviço do Cloud Run exige autenticação (consulte o argumento --no-allow-unauthenticated na etapa 9 da seção anterior). Somente identidades com a função roles/run.invoker ou permissões semelhantes podem chamar o serviço. Esse papel é concedido apenas à conta de serviço do gatilho do Eventarc. Da mesma forma, o acesso ao tópico "invoke_agent" é minimizado para impedir a publicação não autorizada de eventos. Ainda é possível chamar o agente do ZooKeeper diretamente, ignorando a postagem no tópico do Pub/Sub. Consulte a seção 6 para saber como ocultar o endpoint do aplicativo do acesso público.
Executar o fluxo de trabalho
Você vai simular um evento externo publicando uma pergunta em linguagem natural no ZooKeeper.
👉💻 Use o seguinte comando para postar uma mensagem no tópico do Pub/Sub:
gcloud pubsub topics publish invoke_agent \
--message='{"user_id": "important_app", "prompt": "How many animals are in the zoo?"}'
Na realidade, as informações do evento provavelmente terão um formato menos legível. Para processar o evento, um aplicativo de IA generativa precisa ter instruções detalhadas sobre o formato, os dados e o que o agente deve fazer com as informações.
Você pode verificar se o agente recebeu o evento, processou a solicitação e postou a resposta no tópico "agent_responses". Para ler a resposta, use a assinatura "agent_responses". O codelab usa o mesmo ID para o tópico e a assinatura das respostas.
👉💻 Use o comando a seguir para ler a resposta do agente na assinatura do Pub/Sub:
gcloud pubsub subscriptions pull agent_responses --auto-ack
A saída vai imprimir uma tabela com os metadados da mensagem e o payload contendo a resposta de que há 33 espécies no zoológico. A flag --auto-ack reconhece automaticamente a mensagem depois que ela é extraída, então ela não será entregue novamente.
Como funciona
Para conferir o código-fonte do aplicativo de IA com agente, abra o Editor do Cloud Shell e veja os arquivos na pasta ~/zoo-keeper-lab. Você também pode conferir o código-fonte no GitHub.
- O arquivo main.py implementa um aplicativo da Web FastAPI básico com um único manipulador que processa eventos do Eventarc.
- O processor.py analisa a mensagem do evento para recuperar o ID do usuário e a solicitação. Em seguida, ele cria uma nova sessão no executor do ADK e chama o agente do Zookeeper para processar a solicitação. A resposta do agente é postada no tópico do Pub/Sub "agent_responses".
- A subpasta zookeeper_agent hospeda o código-fonte do agente do ADK. É possível executar o comando
adk run zookeeper_agentna pasta raiz do aplicativo para interagir com o agente usando a CLI do ADK.
Como resolver o problema
Se algum dos comandos anteriores falhar, leia a mensagem de erro com atenção. Se a implantação no Cloud Run falhar, a primeira etapa será determinar em qual estágio do processo ocorreu a falha.
- Se a saída do comando "gcloud run deploy..." informar que o build falhou, consulte o URL dos registros de build na saída e abra em uma janela separada.
- Se a saída mostrar algo como "não foi possível iniciar o serviço" ou semelhante, isso significa que o serviço é implantado, mas a execução falha na verificação de integridade. Nesse caso, abra o Explorador de registros ou consulte o parágrafo a seguir para ver o comando da CLI gcloud. Leia os registros para encontrar a causa raiz da falha.
E se você postar uma mensagem no Pub/Sub, mas o agente não responder ou a resposta parecer estranha?
👉💻 Use o comando a seguir para ler os registros de aplicativos postados na execução recente:
gcloud logging read \
'resource.type = "cloud_run_revision" AND \
resource.labels.service_name = "zookeeper-agent" AND \
resource.labels.location = "us-central1"'
Os registros rastreiam a execução e informam erros, como payload de mensagem incorreto ou não analisável, resposta inválida do modelo do Gemini, configurações de ambiente inválidas e outros possíveis problemas.
5. Reforçar a segurança da implantação
O serviço do Cloud Run implantado expõe um endpoint público que pode ser chamado por qualquer pessoa na Internet. Embora o endpoint esteja protegido contra invocação não autorizada e valide rigorosamente a estrutura da solicitação, ele ainda deixa esse vetor de ataque que permite ataques de negação de serviço e de negação de carteira. Como o único caminho de invocação do serviço no design atual é pelo gatilho do Eventarc, o serviço não precisa expor o endpoint à Internet.
👉💻 Feche esse vetor de ataque restringindo as chamadas ao serviço para que sejam feitas apenas da coleção limitada de fontes, incluindo gatilhos do Eventarc:
gcloud run services update zookeeper-agent --region=${LOCATION} --ingress=internal
Agora, se você tentar chamar o URL do serviço na sua máquina local, vai receber um erro "404 Page not found".
👉💻 Use curl para enviar uma solicitação ao endpoint do serviço:
URL=$(gcloud run services describe zookeeper-agent --region=${LOCATION} --format='value(status.url)')
curl -X POST -d '{}' "${URL}/zookeeper"
Você verá um resultado semelhante a este:
<html><head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> <title>404 Page not found</title> </head> <body text=#000000 bgcolor=#ffffff> <h1>Error: Page not found</h1> <h2>The requested URL was not found on this server.</h2> <h2></h2> </body></html>
Depois dessa mudança, não será mais possível invocar o ZooKeeper diretamente chamando o endpoint do serviço do Cloud Run, a menos que você faça a chamada da VPC no mesmo projeto, da rede VPC compartilhada para onde sua revisão está configurada para enviar tráfego ou de um host que faça parte do perímetro do VPC Service Controls.
6. Resumo
Parabéns! Você configurou um ambiente para invocar de forma assíncrona seu aplicativo de IA generativa acionado por eventos recebidos.
Limpar
Manter os recursos provisionados pode gerar cobranças na sua conta de faturamento. Se você não planeja usar esse ambiente para mais experimentos e quer evitar cobranças futuras, recomendamos que exclua os recursos criados durante este codelab.
Há dois métodos para fazer isso:
Método 1: encerrar o projeto
Ao encerrar (excluir) o projeto, todos os recursos e dados dele são liberados, e a conta de faturamento é desvinculada. Usar esse método evita cobranças adicionais por recursos ou dados usados neste codelab. Use o seguinte comando para encerrar o projeto:
gcloud projects delete $(gcloud config get-value project) --quiet
Método 2: excluir recursos no projeto
A exclusão do serviço do Cloud Run protege contra cobranças adicionais pelo uso da plataforma sem servidor. Esse método não remove completamente todos os dados gerados durante o codelab, como registros do Cloud Build e do aplicativo, imagens de contêiner etc. Execute o comando a seguir para excluir o serviço:
gcloud run services delete zookeeper-agent --region=${LOCATION}
A definição de gatilho do Eventarc e os tópicos do Pub/Sub não impõem custos de gerenciamento. Consulte Preços do Eventarc e Preços do Pub/Sub para mais detalhes.
Saiba mais sobre como encerrar o projeto.
A seguir
- Saiba mais sobre o código revisando a demonstração no GitHub.
- Revise a arquitetura que orquestra o acesso a sistemas empresariais distintos.
- Saiba como acionar o Cloud Run usando gatilhos do Eventarc.
- Saiba mais sobre o ADK.