Desplegar una aplicación de IA basada en agentes en GKE con Agent Development Kit (ADK) y Vertex AI

En esta guía se muestra cómo desplegar y gestionar aplicaciones de IA/ML con agentes en contenedores mediante Google Kubernetes Engine (GKE). Si combinas el kit de desarrollo de agentes de Google (ADK) con Vertex AI como proveedor de modelos de lenguaje extenso (LLM), puedes poner en marcha agentes de IA de forma eficiente y a gran escala. En esta guía se describe todo el proceso para llevar un agente basado en FastAPI y con la tecnología de Gemini 2.0 Flash desde el desarrollo hasta el despliegue en producción en GKE.

Esta guía está dirigida a ingenieros de aprendizaje automático, desarrolladores y arquitectos de Cloud interesados en usar las funciones de orquestación de contenedores de Kubernetes para servir aplicaciones de IA o aprendizaje automático basadas en agentes. Para obtener más información sobre los roles habituales y las tareas de ejemplo en el contenido de Google Cloud , consulta Roles y tareas de usuario habituales de GKE.

Antes de empezar, asegúrate de que conoces lo siguiente:

Fondo

En esta guía se combinan varias tecnologías de Google para crear una plataforma escalable para la IA basada en agentes. GKE proporciona la orquestación de contenedores para el agente, que se crea con el ADK. Al usar la API Vertex AI para la inferencia de LLMs, el clúster de GKE no requiere hardware de GPU especializado, ya que la inferencia se gestiona mediante la infraestructura gestionada de Google.

Google Agent Development Kit (ADK)

Agent Development Kit (ADK) es un framework flexible y modular para desarrollar e implementar agentes de IA. Aunque está optimizado para Gemini y el ecosistema de Google, el ADK es independiente del modelo y de la implementación, y se ha diseñado para que sea compatible con otros frameworks.

Para obtener más información, consulta la documentación del ADK.

Servicio de Kubernetes gestionado de GKE

GKE es un servicio de Kubernetes gestionado que permite desplegar, escalar y gestionar aplicaciones en contenedores. GKE proporciona la infraestructura necesaria, incluidos recursos escalables, computación distribuida y redes eficientes, para gestionar las demandas computacionales de los LLMs.

Para obtener más información sobre los conceptos clave de Kubernetes, consulta Empezar a aprender sobre Kubernetes. Para obtener más información sobre GKE y cómo te ayuda a escalar, automatizar y gestionar Kubernetes, consulta la descripción general de GKE.

Vertex AI

Vertex AI es la plataforma de aprendizaje automático unificada de Google Cloud, que permite a los desarrolladores crear, desplegar y escalar modelos de IA y aprendizaje automático. Para las aplicaciones de IA basadas en agentes en GKE, Vertex AI proporciona herramientas y servicios esenciales, como acceso a LLMs como Gemini 2.0 Flash, infraestructura gestionada para el entrenamiento y la inferencia, y funciones de MLOps para una gestión eficiente del ciclo de vida.

Cuando se consumen LLMs a través de la API de Vertex AI, la inferencia de modelos se produce en la infraestructura gestionada de Google, lo que reduce la necesidad de cuotas específicas de GPU o TPU en tu clúster de GKE.

Para obtener más información sobre Vertex AI para aplicaciones de IA basadas en agentes, consulta la documentación de Vertex AI.

Gemini 2.0 Flash

Gemini 2.0 Flash ofrece funciones de última generación y capacidades mejoradas diseñadas para cargas de trabajo de agentes, como mayor velocidad, uso de herramientas integrado, generación multimodal y una ventana de contexto de 1 millón de tokens. Gemini 2.0 Flash mejora el modelo Flash anterior y ofrece una calidad superior a velocidades similares.

Para obtener información técnica sobre Gemini 2.0 Flash (como los puntos de referencia de rendimiento, información sobre nuestros conjuntos de datos de entrenamiento, esfuerzos en materia de sostenibilidad, uso previsto y limitaciones, y nuestro enfoque de la ética y la seguridad), consulta la tarjeta de modelo de Gemini 2.0 Flash.

Preparar el entorno

En este tutorial se usa Cloud Shell para gestionar los recursos alojados en Google Cloud. Cloud Shell viene preinstalado con el software que necesitas para este tutorial, como kubectl, terraform y Google Cloud CLI.

Para configurar tu entorno con Cloud Shell, sigue estos pasos:

  1. En la Google Cloud consolaIcono de activación de Cloud Shell, inicia una sesión de Cloud Shell y haz clic en Activar Cloud Shell. Esta acción inicia una sesión en el panel inferior de la consola Google Cloud .

  2. Define las variables de entorno predeterminadas:

    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")

    Sustituye los siguientes valores:

    • PROJECT_ID: tu Google Cloud ID de proyecto.
    • REGION: la Google Cloud región (por ejemplo, us-central1) en la que se aprovisionarán el clúster de GKE, Artifact Registry y otros recursos regionales.

Clonar el proyecto de ejemplo

  1. En el terminal de Cloud Shell, clona el repositorio de código de ejemplo del tutorial:

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

  2. Ve al directorio del tutorial:

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

Crear y configurar Google Cloud recursos

Para implementar tu agente en GKE, aprovisiona los recursos deGoogle Cloud necesarios. Puedes desplegar el agente mediante la CLI de gcloud para ejecutar comandos directamente o Terraform para usar la infraestructura como código.

gcloud

En esta sección se proporcionan comandos de la CLI de gcloud para configurar el clúster de GKE, Artifact Registry y Workload Identity Federation for GKE para que se integren perfectamente con Vertex AI. Asegúrate de haber definido las variables de entorno tal como se describe en Preparar el entorno.

  1. Crea un clúster de GKE: puedes desplegar tu aplicación basada en agentes en contenedores en un clúster Autopilot o Estándar de GKE. Usa un clúster de Autopilot para disfrutar de una experiencia de Kubernetes totalmente gestionada. Para elegir el modo de funcionamiento de GKE que mejor se adapte a tus cargas de trabajo, consulta Elegir un modo de funcionamiento de GKE.

    Autopilot

    En Cloud Shell, ejecuta el siguiente comando:

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

    Sustituye CLUSTER_NAME por el nombre de tu clúster de Autopilot de GKE.

    Estándar

    En Cloud Shell, ejecuta el siguiente 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

    Sustituye CLUSTER_NAME por el nombre de tu clúster estándar.

  2. Crea un repositorio de Artifact Registry para tu contenedor Docker: crea un repositorio de Artifact Registry para almacenar y gestionar de forma segura la imagen de contenedor Docker de tu agente. Este registro privado ayuda a que tu aplicación esté disponible para desplegarse en GKE y se integra con Cloud Build.

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

  3. Obtener la URL del repositorio: ejecuta este comando para verificar la ruta completa a tu repositorio. Usarás este formato de ruta para etiquetar tu imagen de Docker en el siguiente paso.

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

  4. Concede a la cuenta de servicio predeterminada de Compute Engine los roles de gestión de identidades y accesos necesarios: de forma predeterminada, la cuenta de servicio predeterminada de Compute Engine no tiene permisos para enviar imágenes a Artifact Registry ni para ver objetos en Cloud Storage o registros. Concede los roles necesarios para estas operaciones.

    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. Crea y envía la imagen del contenedor del agente: ejecuta este comando para crear tu imagen de Docker y enviarla a Artifact Registry. Asegúrate de que el archivo Dockerfile y el código de la aplicación estén en el directorio /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. Verifica que la imagen se haya enviado:

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

Terraform

En esta sección se describe cómo usar Terraform para aprovisionar tus recursos de Google Cloud. El repositorio de ejemplo que has clonado incluye los archivos de configuración de Terraform necesarios.

  1. Inicializa Terraform: ve al directorio terraform e inicializa Terraform.

    terraform init

  2. Revisa el plan de ejecución: este comando muestra los cambios que Terraform hará en la infraestructura.

    terraform plan -var-file=default_env.tfvars

  3. Aplica la configuración: ejecuta el plan de Terraform para crear los recursos en tu Google Cloud proyecto. Confirma la acción con yes cuando se te solicite.

    terraform apply -var-file=default_env.tfvars

    Después de ejecutar estos comandos, Terraform aprovisiona tu clúster de GKE y tu repositorio de Artifact Registry, y configura los roles de gestión de identidades y accesos y las cuentas de servicio necesarios, incluida la federación de identidades de carga de trabajo para GKE.

Para obtener más información sobre el uso de Terraform, consulta Compatibilidad de Terraform con GKE.

Configurar kubectl para que se comunique con tu clúster

Si no has configurado kubectl para que se comunique con tu clúster, ejecuta el siguiente comando:

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

Sustituye CLUSTER_NAME por el nombre de tu clúster de GKE.

Configurar Workload Identity Federation para acceder a GKE

Puedes saltarte este paso si usas Terraform. Este proceso vincula una cuenta de servicio de Kubernetes (KSA) a una cuenta de servicio de gestión de identidades y accesos (IAM) para conceder de forma segura a tu agente acceso a los servicios de Google Cloud .

  1. Crea una cuenta de servicio para acceder a Vertex AI:

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

  2. Asigna el rol aiplatform.user a la cuenta de servicio. De esta forma, la cuenta de servicio puede interactuar con Vertex AI.

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

  3. Crea un KSA en tu clúster. Antes de ejecutar este comando, asegúrate de seguir las instrucciones que se indican en Configurar kubectl para que se comunique con tu clúster.

    kubectl create serviceaccount vertex-sa

  4. Anota el KSA para vincularlo a tu cuenta de servicio:

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

  5. Concede permisos a tu cuenta de servicio para que actúe como usuario de Workload Identity Federation para GKE de la 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]"

Desplegar y configurar la aplicación del agente

Después de configurar tus Google Cloud recursos, prepara tu aplicación de agente para la implementación y configura su tiempo de ejecución en GKE. Esto implica definir el código de tu agente, crear un Dockerfile para empaquetarlo en un contenedor y escribir un manifiesto de Kubernetes para desplegarlo en tu clúster.

  1. Estructura de la aplicación del agente: el directorio /app contiene los archivos principales de la aplicación del agente:
    • main.py: punto de entrada de la aplicación FastAPI, responsable de exponer la API del agente.
    • agent.py: contiene la lógica del agente del ADK, que define cómo usa Vertex AI y gestiona las solicitudes.
    • __init__.py: inicializa el paquete de Python.
    • requirements.txt: muestra todas las dependencias de Python de tu agente.
    • Dockerfile: define cómo se empaqueta tu aplicación en una imagen de Docker.

  2. Crea el manifiesto de implementación del agente: en el directorio tutorials-and-examples/adk/vertex, crea el siguiente manifiesto como un archivo llamado 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"

    Sustituye los siguientes valores:

    • IMAGE_URL: la URL completa de la imagen de Docker que has subido a Artifact Registry (por ejemplo, us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest). Puedes obtener este valor del resultado del comando gcloud artifacts docker images list de la sección anterior. También puedes ejecutar un comando como el siguiente: sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml.
    • PROJECT_ID: tu ID de proyecto Google Cloud .
    • REGION: la Google Cloud región en la que se aprovisiona el clúster de GKE.

  3. Aplica el manifiesto de implementación:

    kubectl apply -f agent-deployment.yaml

    Este comando crea el Deployment y los pods asociados de tu aplicación de agente en el clúster de GKE.

  4. Exponer el agente: puedes usar estos métodos para exponer tu agente y permitir el acceso.

    • Para acceder a tu agente desde fuera del clúster, crea un servicio de Kubernetes. En el caso de las APIs web, es habitual usar un servicio de tipo LoadBalancer.

    • Para el desarrollo y las pruebas locales, usa el comando kubectl port-forward para acceder directamente a tu agente.

    LoadBalancer

    1. Crea el siguiente manifiesto como un archivo llamado 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. Aplica el archivo de manifiesto:

      kubectl apply -f agent-service.yaml

      La dirección IP externa puede tardar unos minutos en aprovisionarse.

    3. Verifica que la dirección IP esté aprovisionada:

      kubectl get service adk-agent-service

      Busca el valor EXTERNAL-IP en el resultado. Una vez que el valor esté disponible, usa esta dirección IP para interactuar con el agente implementado.

    port-forward

    Si usas principalmente port-forward, considera la posibilidad de usar un tipo de servicio ClusterIP en lugar de LoadBalancer, ya que el servicio ClusterIP es interno y consume 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 bloquea tu terminal, pero reenvía el tráfico de localhost:8000 en tu máquina al agente que se ejecuta en el clúster de GKE.

Probar el agente desplegado

Ahora que tu aplicación de agente se ha implementado y expuesto, prueba su funcionalidad.

En esta sección se describe cómo identificar el endpoint de tu agente y probar la API del agente.

  1. Identifica el endpoint del agente: en función de cómo hayas decidido exponer tu agente en la sección anterior, identifica su endpoint accesible:

    LoadBalancer

    1. Recupera la dirección IP externa:

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

    2. Almacena la dirección IP externa en una variable de entorno para que sea más fácil de usar:

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

      La URL base de tu agente es http://${AGENT_IP}.

    port-forward

    Asegúrate de que el comando kubectl port-forward se ejecuta en un terminal independiente. La URL base de tu agente es http://localhost:8000.

  2. Prueba la API del agente: prueba la API del agente haciendo una solicitud curl a su endpoint /run. El agente espera una carga útil JSON con un campo de mensaje. Sustituye AGENT_BASE_URL por http://${AGENT_IP} (para LoadBalancer) o http://localhost:8000 (para reenvío de puertos).

    1. Crea una sesión. De esta forma, el agente se prepara para una nueva conversación.

      # 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

      Puedes consultar las aplicaciones disponibles con el siguiente comando:

      curl -X GET AGENT_BASE_URL/list-apps

    2. Envía una consulta al agente usando los detalles de la sesión del paso 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?"
    }]
  }
}'

      Deberías recibir una respuesta JSON de tu agente que indique que procesa las solicitudes correctamente e interactúa con el modelo de Gemini a través de Vertex AI. La respuesta contiene la réplica generada por el agente basada en tu mensaje.

  3. Accede a la interfaz web del agente (si procede): si tu agente incluye una interfaz de usuario basada en la Web, accede a ella desplazándote hasta tu AGENT_BASE_URL en un navegador web. El ADK suele incluir una interfaz de usuario web básica para la interacción y la depuración. Por ejemplo, si has expuesto tu agente a través de un LoadBalancer y su EXTERNAL-IP es 34.123.45.67, ve a http://34.123.45.67 en tu navegador.