Implemente uma aplicação de IA baseada em agentes no GKE com o Agent Development Kit (ADK) e a Vertex AI


Este guia demonstra como implementar e gerir aplicações de IA/ML baseadas em agentes em contentores usando o Google Kubernetes Engine (GKE). Ao combinar o Google Agent Development Kit (ADK) com o Vertex AI como fornecedor de modelos de linguagem (conteúdo extenso) (MDIs/CEs), pode operacionalizar agentes de IA de forma eficiente e em grande escala. Este guia explica o processo completo de implementação de um agente baseado no FastAPI com tecnologia do Gemini 2.0 Flash, desde o desenvolvimento à implementação em produção no GKE.

Este guia destina-se a engenheiros de aprendizagem automática (AA), programadores e arquitetos da nuvem interessados em usar capacidades de orquestração de contentores do Kubernetes para publicar aplicações de IA/AA baseadas em agentes. Para saber mais sobre as funções comuns e exemplos de tarefas no conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE Enterprise. Google Cloud

Antes de começar, certifique-se de que conhece o seguinte:

Contexto

Este guia combina várias tecnologias Google para criar uma plataforma escalável para IA autónoma. O GKE fornece a orquestração de contentores para o agente, que é criado através do ADK. Ao usar a API Vertex AI para inferência de MDIs, o cluster do GKE não requer hardware de GPU especializado, porque a inferência é processada pela infraestrutura gerida da Google.

Google Agent Development Kit (ADK)

O Agent Development Kit (ADK) é uma estrutura flexível e modular para desenvolver e implementar agentes de IA. Embora esteja otimizado para o Gemini e o ecossistema Google, o ADK é independente do modelo, da implementação e foi criado para compatibilidade com outros frameworks.

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

Serviço Kubernetes gerido do GKE

O GKE é um serviço Kubernetes gerido para implementar, dimensionar e gerir aplicações contentorizadas. O GKE fornece a infraestrutura necessária, incluindo recursos escaláveis, computação distribuída e redes eficientes, para processar as exigências computacionais dos MDIs.

Para mais informações sobre os principais conceitos do Kubernetes, consulte o artigo Comece a saber mais sobre o Kubernetes. Para mais informações sobre o GKE e como este ajuda a dimensionar, automatizar e gerir o Kubernetes, consulte a vista geral do GKE.

Vertex AI

O Vertex AI é a plataforma de ML unificada da Google Cloud, que permite aos programadores criar, implementar e dimensionar modelos de IA/ML. Google CloudPara aplicações de IA autónomas no GKE, a Vertex AI oferece ferramentas e serviços essenciais, incluindo acesso a MDIs como o Gemini 2.0 Flash, infraestrutura gerida para preparação e inferência, e capacidades de MLOps para uma gestão eficiente do ciclo de vida.

Quando consome MDIs através da API Vertex AI, a inferência de modelos ocorre na infraestrutura gerida pela Google, o que reduz a necessidade de quotas específicas de GPU ou TPU no seu cluster do GKE.

Para mais informações sobre a Vertex AI para aplicações de IA autónomas, consulte a documentação da Vertex AI.

Gemini 2.0 Flash

O Gemini 2.0 Flash oferece funcionalidades de próxima geração e capacidades melhoradas concebidas para cargas de trabalho de agentes, incluindo maior velocidade, utilização de ferramentas incorporadas, geração multimodal e uma capacidade de resposta de 1 milhão de tokens. O Gemini 2.0 Flash melhora o modelo Flash anterior e oferece uma qualidade melhorada a velocidades semelhantes.

Para informações técnicas sobre o Gemini 2.0 Flash (como referências de desempenho, informações sobre os nossos conjuntos de dados de preparação, esforços em termos de sustentabilidade, utilização pretendida e limitações, e a nossa abordagem à ética e segurança), consulte o cartão do modelo do Gemini 2.0 Flash.

Objetivos

Este guia mostra-lhe como fazer o seguinte:

  • Configure o seu Google Cloud ambiente.
  • Crie uma imagem de contentor para o seu agente.
  • Implemente o agente num cluster do GKE.
  • Teste o agente implementado.

Custos

Este guia usa os seguintes componentes faturáveis do Google Cloud:

Reveja os preços de cada serviço para compreender os potenciais 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.

    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.

    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.

      Aceder ao IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.
    4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.

    5. Na lista Selecionar uma função, selecione uma função.
    6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
    7. Clique em Guardar.
    8. Prepare o ambiente

      Este tutorial usa a Cloud Shell para gerir recursos alojados no Google Cloud. O Cloud Shell vem pré-instalado com o software de que precisa para este tutorial, incluindo kubectl, terraform e o Google Cloud CLI.

      Para configurar o seu ambiente com o Cloud Shell, siga estes passos:

      1. Na Google Cloud consola, inicie uma sessão do Cloud Shell e clique em Ícone de ativação do Cloud Shell Ativar Cloud Shell. Esta ação inicia uma sessão no painel inferior da consola do Google Cloud .
      2. Defina as variáveis de ambiente predefinidas:

        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 seu Google Cloud ID do projeto.
        • REGION: a Google Cloud região (por exemplo, us-central1) para aprovisionar o cluster do GKE, o Artifact Registry e outros recursos regionais.

      Clone o projeto de exemplo

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

        git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
        
      2. Navegue para o diretório de tutoriais:

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

      Crie e configure Google Cloud recursos

      Para implementar o seu agente no GKE, aprovisione osGoogle Cloud recursos necessários. Pode implementar o agente através da CLI gcloud para execução direta na linha de comandos ou do Terraform para infraestrutura como código.

      gcloud

      Esta secção fornece comandos da CLI gcloud para configurar o cluster do GKE, o Artifact Registry e a Workload Identity Federation para o GKE para uma integração perfeita com o Vertex AI. Certifique-se de que definiu as variáveis de ambiente conforme descrito em Prepare o ambiente.

      1. Crie um cluster do GKE: pode implementar a sua aplicação baseada em agente em contentores num cluster do GKE Autopilot ou Standard. Use um cluster do Autopilot para uma experiência do Kubernetes totalmente gerida. Para escolher o modo de funcionamento do GKE mais adequado às suas cargas de trabalho, consulte o artigo Escolha um modo de funcionamento do GKE.

        Piloto automático

        No Cloud Shell, execute o seguinte 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.

        Standard

        No Cloud Shell, execute o seguinte 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 seu cluster padrão.

      2. Crie um repositório do Artifact Registry para o seu contentor Docker: crie um repositório do Artifact Registry para armazenar e gerir em segurança a imagem do contentor Docker do seu agente. Este registo privado ajuda a garantir que a sua aplicação está prontamente disponível para implementação no GKE e integra-se com o Cloud Build.

        gcloud artifacts repositories create adk-repo \
            --repository-format=docker \
            --location=$GOOGLE_CLOUD_LOCATION \
            --project=$PROJECT_ID
        
      3. Obtenha o URL do repositório: execute este comando para validar o caminho completo para o seu repositório. Vai usar este formato de caminho para etiquetar a sua imagem do Docker no passo seguinte.

        gcloud artifacts repositories describe adk-repo \
            --location $GOOGLE_CLOUD_LOCATION \
            --project=$PROJECT_ID
        
      4. Conceda à conta de serviço predefinida do Compute Engine as funções IAM necessárias: Por predefinição, a conta de serviço predefinida do Compute Engine não tem autorizações para enviar imagens para o Artifact Registry nem para ver objetos no Cloud Storage ou registos. Conceda as funções necessárias para estas 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}-compute@developer.gserviceaccount.com" \
                --role="${ROLE}"
        done
        
      5. Crie e envie a imagem do contentor do agente: execute este comando para criar a imagem do Docker e enviá-la para o Artifact Registry. Certifique-se de que o Dockerfile e o código da aplicação 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:

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

      Terraform

      Esta secção descreve como usar o Terraform para aprovisionar os seus Google Cloud recursos. O repositório de exemplo que clonou inclui os ficheiros de configuração do Terraform necessários.

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

        terraform init
        
      2. Reveja o plano de execução: este comando mostra as alterações à 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 seu projeto do Google Cloud. Google Cloud Confirme com yes quando lhe for pedido.

        terraform apply -var-file=default_env.tfvars
        

        Depois de executar estes comandos, o Terraform aprovisiona o cluster do GKE e o repositório do Artifact Registry, e configura as funções do IAM e as contas de serviço necessárias, incluindo a Workload Identity Federation para o GKE.

      Para saber mais sobre a utilização do Terraform, consulte o apoio técnico do Terraform para o GKE.

      Configure o kubectl para comunicar com o seu cluster

      Se não configurou o kubectl para 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 seu cluster do GKE.

      Configure a Workload Identity Federation para acesso ao GKE

      Pode ignorar este passo se estiver a usar o Terraform. Este processo associa uma conta de serviço do Kubernetes (KSA) a uma conta de serviço do IAM para conceder ao seu agente acesso seguro aos serviços 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 a função aiplatform.user. Isto permite que a conta de serviço interaja com o 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 um KSA no seu cluster. Certifique-se de que segue as instruções em Configurar kubectl para comunicar com o cluster antes de executar este comando.

        kubectl create serviceaccount vertex-sa
        
      4. Anote o KSA para o associar à 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 autorizações à sua conta de serviço para atuar como uma federação de identidades da carga de trabalho para o utilizador do GKE para o 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]"
        

      Implemente e configure a aplicação do agente

      Depois de configurar os Google Cloud recursos, prepare a aplicação do agente para a implementação e configure o respetivo tempo de execução no GKE. Isto envolve definir o código do seu agente, criar um Dockerfile para o colocar num contentor e escrever um manifesto do Kubernetes para o implementar no seu cluster.

      1. Compreenda a estrutura da aplicação do agente: o diretório /app contém os ficheiros principais da sua aplicação do agente:
        • main.py: o ponto de entrada da aplicação FastAPI, responsável por expor a API do agente.
        • agent.py: contém a lógica do agente ADK, definindo como usa o Vertex AI e processa os pedidos.
        • __init__.py: inicializa o pacote Python.
        • requirements.txt: lista todas as dependências do Python para o seu agente.
        • Dockerfile: define como a sua aplicação é incluída num pacote numa imagem do Docker.
      2. Crie o manifesto de implementação do agente: no diretório tutorials-and-examples/adk/vertex, crie o seguinte manifesto como um ficheiro denominado 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 Docker que enviou para o Artifact Registry (por exemplo, us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest). Pode obter este valor a partir do resultado do comando gcloud artifacts docker images list na secção anterior. Em alternativa, execute um comando como o seguinte: sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml.
        • PROJECT_ID: o ID do seu Google Cloud projeto.
        • REGION: a Google Cloud região onde o cluster do GKE é aprovisionado.
      3. Aplique o manifesto de implementação:

        kubectl apply -f agent-deployment.yaml
        

        Este comando cria a implementação e os pods associados para a sua aplicação de agente no cluster do GKE.

      4. Exponha o agente: pode usar estes métodos para expor o seu agente para acesso.

        • Para aceder ao seu agente a partir do exterior do cluster, crie um serviço Kubernetes. Para uma API Web, um serviço do tipo LoadBalancer é comum.
        • Para o desenvolvimento e os testes locais, use o comando kubectl port-forward para aceder diretamente ao seu agente.

        LoadBalancer

        1. Crie o seguinte manifesto como um ficheiro denominado 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 aprovisionamento do endereço IP externo pode demorar alguns minutos.

        3. Verifique se o endereço IP está aprovisionado:

          kubectl get service adk-agent-service
          

          Procure o valor EXTERNAL-IP no resultado. Depois de o valor estar disponível, use este endereço IP para interagir com o agente implementado.

        port-forward

        Se usar principalmente port-forward, considere usar um ClusterIP tipo de serviço em vez de LoadBalancer, uma vez que o ClusterIP serviço é 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
        

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

      Teste o agente implementado

      Agora que a sua aplicação de agente está implementada e exposta, teste a respetiva funcionalidade.

      Esta secção descreve como identificar o ponto final do seu agente e testar a API do agente.

      1. Identifique o ponto final do agente: consoante a forma como optou por expor o seu agente na secção anterior, identifique o respetivo ponto final 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 numa variável de ambiente para facilitar a utilização:

          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

        Certifique-se de que o comando kubectl port-forward é executado num terminal separado. O URL base do seu agente é http://localhost:8000.

      2. Teste a API do agente: teste a API do agente fazendo um pedido curl ao respetivo ponto final /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 portas).

        1. Crie uma nova sessão. Esta ação 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
          

          Pode apresentar uma lista das apps disponíveis com o seguinte comando:

          curl -X GET AGENT_BASE_URL/list-apps
          
        2. Envie uma consulta ao agente através dos detalhes da sessão do passo 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?"
              }]
            }
          }'
          

          Deve receber uma resposta JSON do seu agente, a indicar que processa pedidos com êxito e interage com o modelo Gemini através do Vertex AI. A resposta contém a resposta gerada do agente com base na sua mensagem.

      3. Aceda à IU Web do agente (se aplicável): se o seu agente incluir uma interface do utilizador baseada na Web, aceda à mesma navegando para o seu AGENT_BASE_URL num navegador de Internet. Normalmente, o ADK inclui uma IU Web básica para interação e depuração. Por exemplo, se expôs o seu agente através de um LoadBalancer e o respetivo EXTERNAL-IP for 34.123.45.67, navegue para http://34.123.45.67 no seu navegador.

      Limpar

      Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

      Elimine os recursos implementados

      Para evitar incorrer em custos na sua Google Cloud conta pelos recursos que criou 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 seu cluster do GKE.

      Terraform

      1. No terminal do Cloud Shell, navegue para 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 seus ficheiros de configuração do Terraform.

        cd terraform
        terraform destroy
        

      O que se segue?

      • Saiba como configurar o Horizontal Pod Autoscaler (HPA) para ajustar automaticamente os recursos do seu agente a pedido.
      • Saiba como configurar o Identity-Aware Proxy (IAP) para as suas aplicações Web em execução noGoogle Cloud, fornecendo autorização centralizada para o acesso à IU do seu agente.
      • Saiba como usar o Cloud Logging e o Cloud Monitoring para obter estatísticas sobre o desempenho e o estado do seu agente no cluster do GKE.
      • Explore exemplos experimentais no GKE AI Labs que podem ajudar a usar o GKE para acelerar as suas iniciativas de IA baseadas em agentes.