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

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 Funções e tarefas comuns do usuário do GKE.

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

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 com agentes, 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.

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 Ícone de ativação do Cloud Shell 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 CLI gcloud 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}-compute@developer.gserviceaccount.com" \
        --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.

  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 UI 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 UI 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.