Implantar um aplicativo de IA com agentes no GKE usando o Agent Development Kit (ADK) e a Vertex AI

Standard

---

Este guia demonstra como implantar e gerenciar aplicativos de IA/ML com agentes conteinerizados usando o Google Kubernetes Engine (GKE). Ao combinar o Kit de Desenvolvimento de Agentes (ADK) do Google com a Vertex AI como provedora de modelos de linguagem grandes (LLMs), é possível operacionalizar agentes de IA de maneira eficiente e em grande escala. Este guia orienta você em todo o processo de levar um agente baseado em FastAPI com tecnologia do Gemini 2.0 Flash do desenvolvimento à implantação de produção no GKE.

Este guia é destinado a engenheiros de machine learning (ML), desenvolvedores e arquitetos de nuvem interessados em usar os recursos de orquestração de contêineres do Kubernetes para veiculação de aplicativos de IA/ML com agentes. Para saber mais sobre papéis comuns e tarefas de exemplo no conteúdo do Google Cloud , consulte Tarefas e papéis de usuário comuns do GKE Enterprise.

Antes de começar, confira se você tem familiaridade com o seguinte:

• GKE
• Conteinerização com o Docker
• Vertex AI

Contexto

Este guia combina várias tecnologias do Google para criar uma plataforma escalonável para IA generativa. O GKE fornece a orquestração de contêineres para o agente, que é criado usando o ADK. Ao usar a API Vertex AI para inferência de LLM, o cluster do GKE não exige hardware de GPU especializado, porque a inferência é processada pela infraestrutura gerenciada do Google.

Kit de Desenvolvimento de Agente (ADK) do Google

O Agent Development Kit (ADK) é um framework flexível e modular para desenvolver e implantar agentes de IA. Embora seja otimizado para o Gemini e o ecossistema do Google, o ADK é independente de modelo e implantação e foi criado para ser compatível com outros frameworks.

Para mais informações, consulte a documentação do ADK.

Serviço gerenciado do Kubernetes do GKE

O GKE é um serviço gerenciado do Kubernetes para implantar, escalonar e gerenciar aplicativos conteinerizados. O GKE fornece a infraestrutura necessária, incluindo recursos escalonáveis, computação distribuída e rede eficiente, para lidar com as demandas computacionais dos LLMs.

Para mais informações sobre os principais conceitos do Kubernetes, consulte Começar a aprender sobre o Kubernetes. Para mais informações sobre o GKE e como ele ajuda você a escalonar, automatizar e gerenciar o Kubernetes, consulte a visão geral do GKE.

Vertex AI

A Vertex AI é a plataforma unificada de ML do Google Cloud, que permite aos desenvolvedores criar, implantar e escalonar modelos de IA/ML. Para aplicativos de IA autônoma no GKE, a Vertex AI oferece ferramentas e serviços essenciais, incluindo acesso a LLMs como o Gemini 2.0 Flash, infraestrutura gerenciada para treinamento e inferência e recursos de MLOps para gerenciamento eficiente do ciclo de vida.

Ao consumir LLMs pela API Vertex AI, a inferência de modelo ocorre na infraestrutura gerenciada do Google, reduzindo a necessidade de cotas específicas de GPU ou TPU no cluster do GKE.

Para mais informações sobre a Vertex AI para aplicativos de IA autônoma, consulte a documentação da Vertex AI.

Gemini 2.0 Flash

O Gemini 2.0 Flash oferece recursos de última geração e capacidades aprimoradas projetadas para cargas de trabalho de agentes, incluindo maior velocidade, uso de ferramentas integradas, geração multimodal e uma janela de contexto de 1 milhão de tokens. O Gemini 2.0 Flash melhora o modelo Flash anterior e oferece qualidade aprimorada em velocidades semelhantes.

Para informações técnicas sobre o Gemini 2.0 Flash (como comparativos de performance, informações sobre nossos conjuntos de dados de treinamento, esforços em sustentabilidade, uso e limitações pretendidos e nossa abordagem de ética e segurança), consulte a ficha do modelo do Gemini 2.0 Flash.

Objetivos

Neste guia, você aprende as seguintes ações com relação à verificação de tempo de atividade:

• Configure seu ambiente Google Cloud .
• Crie uma imagem de contêiner para seu agente.
• Implante o agente em um cluster do GKE.
• Teste o agente implantado.

Custos

Neste guia, usamos os seguintes componentes faturáveis do Google Cloud:

• GKE
• Artifact Registry
• Cloud Build
• Vertex AI

Analise os preços de cada serviço para entender os possíveis custos.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin

  Check for the roles

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

  Grant the roles

  1. In the Google Cloud console, go to the IAM page.

     Acessar o IAM
  2. Selecione o projeto.
  3. Clique em Conceder acesso.

  4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

  5. Na lista Selecionar papel, escolha um.
  6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
  7. Clique em Salvar.

  Prepare o ambiente

  Neste tutorial, usamos o Cloud Shell para gerenciar recursos hospedados no Google Cloud. O Cloud Shell vem pré-instalado com o software necessário para este tutorial, incluindo kubectl, terraform e Google Cloud CLI.

  Para configurar o ambiente com o Cloud Shell, siga estas etapas:

  1. No console do Google Cloud , inicie uma sessão do Cloud Shell e clique em Ativar o Cloud Shell. Essa ação inicia uma sessão no painel inferior do console Google Cloud .

  2. Defina as variáveis de ambiente padrão:

     gcloud config set project PROJECT_ID
     export GOOGLE_CLOUD_LOCATION=REGION
     export PROJECT_ID=PROJECT_ID
     export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
     export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog
     export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")
     

     Substitua os seguintes valores:

     • PROJECT_ID: o Google Cloud ID do projeto.
     • REGION: a Google Cloud região (por exemplo, us-central1) para provisionar o cluster do GKE, o Artifact Registry e outros recursos regionais.

  Clonar o projeto de exemplo

  1. No terminal do Cloud Shell, clone o repositório de exemplo de código do tutorial:

     git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
     

  2. Navegue até o diretório do tutorial:

     cd kubernetes-engine-samples/ai-ml/adk-vertex
     

  Criar e configurar recursos Google Cloud

  Para implantar o agente no GKE, provisione os recursosGoogle Cloud necessários. É possível implantar o agente usando a gcloud CLI para execução direta na linha de comando ou o Terraform para infraestrutura como código.

  gcloud

  Esta seção fornece comandos da CLI gcloud para configurar o cluster do GKE, o Artifact Registry e a federação de identidade da carga de trabalho para GKE para uma integração perfeita com a Vertex AI. Verifique se você definiu as variáveis de ambiente conforme descrito em Preparar o ambiente.

  1. Crie um cluster do GKE: é possível implantar seu aplicativo de agente em contêineres em um cluster do GKE Autopilot ou Standard. Use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Escolher um modo de operação do GKE.

     Piloto automático

     No Cloud Shell, execute este comando:

     gcloud container clusters create-auto CLUSTER_NAME \
             --location=$GOOGLE_CLOUD_LOCATION \
             --project=$PROJECT_ID
     

     Substitua CLUSTER_NAME pelo nome do cluster do GKE Autopilot.

     Padrão

     No Cloud Shell, execute este comando:

     gcloud container clusters create CLUSTER_NAME \
         --location=$GOOGLE_CLOUD_LOCATION \
         --project=$PROJECT_ID \
         --release-channel=stable \
         --num-nodes=1 \
         --machine-type=e2-medium \
         --workload-pool=$PROJECT_ID.svc.id.goog
     

     Substitua CLUSTER_NAME pelo nome do cluster padrão.

  2. Crie um repositório do Artifact Registry para seu contêiner Docker: crie um repositório do Artifact Registry para armazenar e gerenciar com segurança a imagem do contêiner Docker do seu agente. Esse registro particular ajuda a garantir que seu aplicativo esteja disponível para implantação no GKE e se integra ao Cloud Build.

     gcloud artifacts repositories create adk-repo \
         --repository-format=docker \
         --location=$GOOGLE_CLOUD_LOCATION \
         --project=$PROJECT_ID
     

  3. Receber o URL do repositório: execute este comando para verificar o caminho completo do repositório. Você vai usar esse formato de caminho para adicionar tags à sua imagem do Docker na próxima etapa.

     gcloud artifacts repositories describe adk-repo \
         --location $GOOGLE_CLOUD_LOCATION \
         --project=$PROJECT_ID
     

  4. Conceda à conta de serviço padrão do Compute Engine os papéis necessários do IAM: por padrão, a conta de serviço padrão do Compute Engine não tem permissões para enviar imagens ao Artifact Registry nem para visualizar objetos no Cloud Storage ou registros. Conceda os papéis necessários para essas operações.

     ROLES_TO_ASSIGN=(
         "roles/artifactregistry.writer"
         "roles/storage.objectViewer"
         "roles/logging.viewer"
     )
     
     for ROLE in "${ROLES_TO_ASSIGN[@]}"; do
         gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
             --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
             --role="${ROLE}"
     done
     

  5. Crie e envie a imagem do contêiner do agente: execute este comando para criar sua imagem do Docker e enviá-la ao Artifact Registry. Verifique se o Dockerfile e o código do aplicativo estão no diretório /app.

     export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest"
     
     gcloud builds submit \
         --tag "$IMAGE_URL" \
         --project="$PROJECT_ID" \
         app
     

  6. Verifique se a imagem foi enviada por push:

     gcloud artifacts docker images list \
         $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \
         --project=$PROJECT_ID
     

  Terraform

  Nesta seção, descrevemos como usar o Terraform para provisionar seus recursos do Google Cloud. O repositório de exemplo clonado inclui os arquivos de configuração do Terraform necessários.

  Observação: se você usar o Terraform, especifique o valor REGION no arquivo default_env.tfvars.

  1. Inicialize o Terraform: navegue até o diretório terraform e inicialize o Terraform.

     terraform init
     

  2. Analise o plano de execução: esse comando mostra as mudanças na infraestrutura que o Terraform vai fazer.

     terraform plan -var-file=default_env.tfvars
     

  3. Aplique a configuração: execute o plano do Terraform para criar os recursos no projeto Google Cloud . Confirme com yes quando solicitado.

     terraform apply -var-file=default_env.tfvars
     

     Depois de executar esses comandos, o Terraform provisiona o cluster do GKE e o repositório do Artifact Registry, além de configurar as contas de serviço e os papéis do IAM necessários, incluindo a Federação de Identidade da Carga de Trabalho para GKE.

  Para saber mais sobre como usar o Terraform, consulte Suporte do Terraform para GKE.

  Configure kubectl para se comunicar com o cluster

  Se você não tiver configurado o kubectl para se comunicar com o cluster, execute o seguinte comando:

  gcloud container clusters get-credentials CLUSTER_NAME \
      --location=${GOOGLE_CLOUD_LOCATION}
  

  Substitua CLUSTER_NAME pelo nome do cluster do GKE.

  Configurar o acesso à federação de identidade da carga de trabalho para o GKE

  Pule esta etapa se estiver usando o Terraform. Esse processo vincula uma conta de serviço do Kubernetes (KSA) a uma conta de serviço do IAM para conceder acesso seguro do agente aos serviços do Google Cloud .

  1. Crie uma conta de serviço para acesso à Vertex AI:

     gcloud iam service-accounts create vertex-sa \
         --project=$PROJECT_ID
     

  2. Conceda à conta de serviço o papel aiplatform.user. Isso permite que a conta de serviço interaja com a Vertex AI.

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

  3. Crie uma KSA no cluster. Siga as instruções em Configurar kubectl para se comunicar com o cluster antes de executar esse comando.

     kubectl create serviceaccount vertex-sa
     

  4. Anote a KSA para vinculá-la à sua conta de serviço:

     kubectl annotate serviceaccount vertex-sa \
         iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
     

  5. Conceda à sua conta de serviço permissões para atuar como um usuário da Federação de Identidade da Carga de Trabalho para GKE para a KSA:

     gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \
         --role roles/iam.workloadIdentityUser \
         --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"
     

  Implantar e configurar o aplicativo do agente

  Depois de configurar os recursos Google Cloud , prepare o aplicativo do agente para implantação e configure o tempo de execução dele no GKE. Isso envolve definir o código do agente, criar um Dockerfile para conteinerizar e escrever um manifesto do Kubernetes para implantar no cluster.

  1. Entenda a estrutura do aplicativo do agente: o diretório /app contém os arquivos principais do aplicativo do agente:
     • main.py: o ponto de entrada do aplicativo FastAPI, responsável por expor a API do agente.
     • agent.py: contém a lógica do agente do ADK, definindo como ele usa a Vertex AI e processa solicitações.
     • __init__.py: inicializa o pacote Python.
     • requirements.txt: lista todas as dependências do Python para seu agente.
     • Dockerfile: define como o aplicativo é empacotado em uma imagem do Docker.

  2. Crie o manifesto de implantação do agente: no diretório tutorials-and-examples/adk/vertex, crie o seguinte manifesto como um arquivo chamado agent-deployment.yaml:

     apiVersion: apps/v1
     kind: Deployment
     metadata:
       name: adk-agent-deployment
       labels:
         app: adk-agent
     spec:
       replicas: 1
       selector:
         matchLabels:
           app: adk-agent
       template:
         metadata:
           labels:
             app: adk-agent
         spec:
           serviceAccountName: vertex-sa
           containers:
           - name: adk-agent
             image: IMAGE_URL
             ports:
             - containerPort: 8000
             env:
             - name: GOOGLE_CLOUD_PROJECT_ID
               value: PROJECT_ID
             - name: GOOGLE_CLOUD_LOCATION
               value: REGION
             - name: GOOGLE_GENAI_USE_VERTEXAI
               value: "1"
             - name: PORT
               value: "8000"
             resources:
               requests:
                 memory: "512Mi"
                 cpu: "500m"
               limits:
                 memory: "1Gi"
                 cpu: "1"
     

     Substitua os seguintes valores:

     • IMAGE_URL: o URL completo da imagem do Docker que você enviou por push para o Artifact Registry (por exemplo, us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest). É possível extrair esse valor da saída do comando gcloud artifacts docker images list na seção anterior. Como alternativa, execute um comando como este: sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml.
     • PROJECT_ID: o ID do projeto Google Cloud .
     • REGION: a Google Cloud região em que o cluster do GKE é provisionado.

  3. Aplique o manifesto de implantação:

     kubectl apply -f agent-deployment.yaml
     

     Esse comando cria a implantação e os pods associados para o aplicativo do agente no cluster do GKE.

  4. Expor o agente: use esses métodos para expor o agente ao acesso.

     • Para acessar o agente de fora do cluster, crie um serviço do Kubernetes. Para uma API da Web, um serviço do tipo LoadBalancer é comum.

     • Para desenvolvimento e testes locais, use o comando kubectl port-forward para acessar seu agente diretamente.

     LoadBalancer

     1. Crie o seguinte manifesto como um arquivo chamado agent-service.yaml:

        apiVersion: v1
        kind: Service
        metadata:
          name: adk-agent-service
        spec:
          selector:
            app: adk-agent
          type: LoadBalancer # Creates an external IP address for access
          ports:
          -   protocol: TCP
            port: 80
            targetPort: 8000 # Matches the containerPort exposed in the Deployment
        

     2. Aplique o manifesto:

        kubectl apply -f agent-service.yaml
        

        O provisionamento do endereço IP externo pode levar alguns minutos.

     3. Verifique se o endereço IP foi provisionado:

        kubectl get service adk-agent-service
        

        Procure o valor EXTERNAL-IP na saída. Depois que o valor estiver disponível, use esse endereço IP para interagir com o agente implantado.

     port-forward

     Se você usa principalmente port-forward, considere usar um tipo de serviço ClusterIP em vez de LoadBalancer, já que o serviço ClusterIP é interno e consome menos recursos.

     POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
     kubectl port-forward $POD_NAME 8000:8000
     

     Esse comando bloqueia o terminal, mas encaminha o tráfego de localhost:8000 na sua máquina para o agente em execução no cluster do GKE.

  Testar o agente implantado

  Agora que o aplicativo do agente foi implantado e exposto, teste a funcionalidade dele.

  Esta seção descreve como identificar o endpoint do seu agente e testar a API dele.

  1. Identifique o endpoint do agente: dependendo de como você escolheu expor o agente na seção anterior, identifique o endpoint acessível:

     LoadBalancer

     1. Recupere o endereço IP externo:

        kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
        

     2. Armazene o endereço IP externo em uma variável de ambiente para facilitar o uso:

        export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
        

        O URL base do seu agente é http://${AGENT_IP}.

     port-forward

     Verifique se o comando kubectl port-forward está sendo executado em um terminal separado. O URL base do seu agente é http://localhost:8000.

  2. Teste a API do agente: faça uma solicitação curl para o endpoint /run. O agente espera um payload JSON com um campo de mensagem. Substitua AGENT_BASE_URL por http://${AGENT_IP} (para LoadBalancer) ou http://localhost:8000 (para encaminhamento de porta).

     1. Criar uma nova sessão. Isso prepara o agente para uma nova conversa.

        # The user ID and session ID are arbitrary.
        # The appName must match the agent's Python package directory name (in this case, "capital-agent").
        curl -X POST AGENT_BASE_URL/apps/capital-agent/users/user-123/sessions/session-123
        

        É possível listar os apps disponíveis com o seguinte comando:

        curl -X GET AGENT_BASE_URL/list-apps
        

     2. Envie uma consulta ao agente usando os detalhes da sessão da etapa anterior.

        curl -X POST AGENT_BASE_URL/run \
        -H "Content-Type: application/json" \
        -d '{
          "appName": "capital-agent",
          "userId": "user-123",
          "sessionId": "session-123",
          "newMessage": {
            "role": "user",
            "parts": [{
              "text": "Hello, agent! What can you do for me?"
            }]
          }
        }'
        

        Você vai receber uma resposta JSON do seu agente, indicando que ele processa solicitações e interage com o modelo Gemini pela Vertex AI. A resposta contém a resposta gerada do agente com base na sua mensagem.

  3. Acesse a interface da Web do agente (se aplicável): se o agente incluir uma interface de usuário baseada na Web, acesse-a navegando até AGENT_BASE_URL em um navegador da Web. Normalmente, o ADK inclui uma interface da Web básica para interação e depuração. Por exemplo, se você expôs o agente por um LoadBalancer e o EXTERNAL-IP dele é 34.123.45.67, acesse http://34.123.45.67 no navegador.

  Limpar

  Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

  Excluir os recursos implantados

  Para evitar cobranças na sua conta do Google Cloud pelos recursos criados neste guia, execute os seguintes comandos:

  gcloud

  gcloud container clusters delete CLUSTER_NAME \
      --location=${GOOGLE_CLOUD_LOCATION} \
      --project=$PROJECT_ID
  
  gcloud projects remove-iam-policy-binding $PROJECT_ID \
      --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \
      --role "roles/aiplatform.user"
  
  gcloud iam service-accounts delete vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
  
  gcloud artifacts repositories delete adk-repo \
      --location=$GOOGLE_CLOUD_LOCATION \
      --project=$PROJECT_ID
  

  Substitua CLUSTER_NAME pelo nome do cluster do GKE.

  Terraform

  1. No terminal do Cloud Shell, navegue até o diretório tutorials-and-examples/adk/vertex/:

     cd tutorials-and-examples/adk/vertex/
     

  2. Execute este comando para remover todos os recursos definidos nos arquivos de configuração do Terraform.

     cd terraform
     terraform destroy
     

  A seguir

  • Saiba como configurar o escalonador automático horizontal de pods (HPA) para ajustar automaticamente os recursos do seu agente sob demanda.
  • Saiba como configurar o Identity-Aware Proxy (IAP) para seus aplicativos da Web em execução noGoogle Cloud, oferecendo autorização centralizada para acesso à interface do agente.
  • Saiba como usar o Cloud Logging e o Cloud Monitoring para ter insights sobre o desempenho e a integridade do seu agente no cluster do GKE.
  • Confira exemplos experimentais nos Laboratórios de IA do GKE que podem ajudar você a usar o GKE para acelerar suas iniciativas de IA com agentes.