Implemente uma aplicação de IA baseada em agentes no GKE com o Agent Development Kit (ADK) e o 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) (MDI/CE), 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 Google Cloud conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE.

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.

Kit de desenvolvimento de agentes (ADK) da Google

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 o Vertex AI para aplicações de IA autónomas, consulte a documentação do 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.

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 agente a partir do exterior do cluster, crie um serviço do 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, indicando 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.