Desplegar un agente

Para desplegar un agente en Vertex AI Agent Engine, sigue estos pasos:

  1. Configura tu agente para el despliegue.
  2. Crea una instancia de AgentEngine.
  3. Concede permisos al agente implementado.
  4. Obtén el ID de recurso del agente.

También puedes usar las plantillas del paquete de inicio de agentes para la implementación.

Antes de empezar

Antes de implementar un agente, asegúrate de haber completado las siguientes tareas:

  1. Configura tu entorno.
  2. Desarrolla un agente.

Configurar el agente para la implementación

Puedes hacer las siguientes configuraciones opcionales:

Definir los requisitos del paquete

Proporciona el conjunto de paquetes que necesita el agente para la implementación. El conjunto de paquetes puede ser una lista de elementos que pip debe instalar o la ruta a un archivo que siga el formato de archivo de requisitos. Sigue estas prácticas recomendadas:

  1. Fija las versiones de tus paquetes para que las compilaciones sean reproducibles. Algunos paquetes habituales que se deben monitorizar son los siguientes: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai y pydantic.

  2. Minimiza el número de dependencias de tu agente. De esta forma, se reduce el número de cambios que provocan errores al actualizar las dependencias y el agente.

Si el agente no tiene ninguna dependencia, puedes definir requirements como None:

requirements = None

Si el agente usa una plantilla específica de un framework, debes especificar la versión del SDK que se importa (por ejemplo, 1.77.0) al desarrollar el agente.

ADK 

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

LangChain 

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph 

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

AG2 

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

LlamaIndex

Las siguientes instrucciones son para la canalización de consultas de LlamaIndex:

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

También puedes hacer lo siguiente con el paquete requirements:

  • Limita o fija la versión de un paquete determinado (por ejemplo, google-cloud-aiplatform):

    requirements = [
    # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
    "google-cloud-aiplatform[agent_engines,adk]==1.88.0",
]

  • Añade paquetes y restricciones adicionales:

    requirements = [
    "google-cloud-aiplatform[agent_engines,adk]==1.88.0",
    "cloudpickle==3.0", # new
]

  • Apunta a la versión de un paquete en una rama o solicitud de extracción de GitHub:

    requirements = [
    "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    "cloudpickle==3.0",
]

  • Mantén la lista de requisitos en un archivo (por ejemplo, path/to/requirements.txt):

    requirements = "path/to/requirements.txt"

    donde path/to/requirements.txt es un archivo de texto que sigue el formato de archivo de requisitos. Por ejemplo:

    google-cloud-aiplatform[agent_engines,adk]
cloudpickle==3.0

Definir paquetes adicionales

Puedes incluir archivos o directorios locales que contengan archivos de origen de Python locales obligatorios. En comparación con los requisitos de los paquetes, esta opción te permite usar utilidades privadas que hayas desarrollado y que no estén disponibles en PyPI o GitHub.

Si el agente no requiere ningún paquete adicional, puedes asignar el valor extra_packages a None:

extra_packages = None

También puedes hacer lo siguiente con extra_packages:

  • Incluye un solo archivo (como agents/agent.py):

    extra_packages = ["agents/agent.py"]

  • Incluye el conjunto de archivos de un directorio completo (por ejemplo, agents/):

    extra_packages = ["agents"] # directory that includes agents/agent.py

  • Especifica binarios de ruedas de Python (por ejemplo, path/to/python_package.whl):

    requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    "cloudpickle==3.0",
    "python_package.whl",  # install from the whl file that was uploaded
]
extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading

Definir variables de entorno

Si hay variables de entorno de las que depende tu agente, puedes especificarlas en el argumento env_vars=. Si el agente no depende de ninguna variable de entorno, puedes definirlo como None:

env_vars = None

Para especificar las variables de entorno, hay varias opciones disponibles:

Diccionario 

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

Para hacer referencia a un secreto de Secret Manager y que esté disponible como variable de entorno (por ejemplo, CLOUD_SQL_CREDENTIALS_SECRET), primero sigue las instrucciones para crear un secreto para CLOUD_SQL_CREDENTIALS_SECRET en tu proyecto. Después, especifica las variables de entorno de la siguiente manera:

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": "SECRET_ID", "version": "SECRET_VERSION_ID"},
}

donde

  • SECRET_VERSION_ID es el ID de la versión del secreto.
  • SECRET_ID es el ID del secreto.

En el código del agente, puedes hacer referencia al secreto de la siguiente manera:

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON payloads.
  return json.loads(secret)

Lista 

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

Definir controles de recursos personalizados

Puedes especificar controles de recursos de tiempo de ejecución para el agente, como el número mínimo y máximo de instancias de la aplicación, los límites de recursos de cada contenedor y la simultaneidad de cada contenedor.

  • min_instances: número mínimo de instancias de la aplicación que se mantienen en ejecución en todo momento. El intervalo es de [0, 10]. El valor predeterminado es 1.

  • max_instances: número máximo de instancias de la aplicación que se pueden iniciar para gestionar el aumento del tráfico. El intervalo es de [1, 1000]. El valor predeterminado es 100. Si se habilita VPC-SC o PSC-I, el intervalo aceptable es [1, 100].

  • resource_limits: límites de recursos de cada contenedor. Solo se admiten las teclas cpu y memory. El valor predeterminado es {"cpu": "4", "memory": "4Gi"}.

    • Los únicos valores admitidos para cpu son "1", "2", "4", "6" y "8". Para obtener más información, consulta Configurar la asignación de CPU.

    • Los únicos valores admitidos para memory son "1Gi", "2Gi", ..., "32Gi".

    • Para ver la CPU necesaria en diferentes valores de memoria, consulta Configurar límites de memoria.

  • container_concurrency: simultaneidad de cada contenedor y servidor de agente. El valor recomendado es 2 * cpu + 1. El valor predeterminado es 9.

remote_agent = agent_engines.create(
    local_agent,
    # ... other configs
    min_instances=1,
    max_instances=10,
    resource_limits={"cpu": "4", "memory": "8Gi"},
    container_concurrency=9,
)

Definir las opciones de compilación

Puedes especificar opciones de compilación para el agente, como los scripts de instalación que se ejecutan al compilar la imagen del contenedor del agente. Esto resulta útil para instalar dependencias del sistema (por ejemplo, gcloud cli o npx) u otras configuraciones personalizadas. Las secuencias de comandos se ejecutan con permisos de superusuario.

Para usar secuencias de comandos de instalación, crea un directorio llamado installation_scripts y coloca tus secuencias de comandos shell en él:

.
├── ...
└── installation_scripts/
    └── install.sh

A continuación, especifica el directorio installation_scripts en extra_packages y las rutas de las secuencias de comandos en build_options:

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

Puedes usar una de las siguientes secuencias de comandos de instalación habituales:

install_npx.sh 

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

install_uvx.sh 

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

install_gcloud_cli.sh 

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

Definir una carpeta de Cloud Storage

Los artefactos de almacenamiento provisional se sobrescriben si corresponden a una carpeta de un segmento de Cloud Storage. Si es necesario, puedes especificar la carpeta de Cloud Storage para los artefactos de staging. Puedes definir gcs_dir_name como None si no te importa sobrescribir los archivos de la carpeta predeterminada:

gcs_dir_name = None

Para evitar que se sobrescriban los archivos (por ejemplo, en diferentes entornos, como desarrollo, staging y producción), puedes configurar la carpeta correspondiente y especificar la carpeta en la que se va a almacenar el artefacto:

gcs_dir_name = "dev" # or "staging" or "prod"

Si quieres o necesitas evitar colisiones, puedes generar un uuid aleatorio:

import uuid
gcs_dir_name = str(uuid.uuid4())

Configurar metadatos de recursos

Puedes definir metadatos en el recurso ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

Para ver el conjunto completo de parámetros, consulta la referencia de la API.

Configurar una cuenta de servicio personalizada

Puedes configurar una cuenta de servicio personalizada como identidad del agente implementado en lugar de la identidad predeterminada.

Para ello, especifica el correo de tu cuenta de servicio personalizada como service_account al crear o actualizar la instancia de Agent Engine. Por ejemplo:

# Create a new instance
agent_engines.create(
  local_agent=<my-agent>,
  service_account="my-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
  resource_name,
  service_account="my-new-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

Configurar una interfaz de Private Service Connect

Si has configurado la interfaz de Private Service Connect y el peering de DNS, puedes especificar tu vinculación de red y el peering de DNS privado al implementar tu agente:

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
      "dns_peering_configs": [
        {
          "domain": "DOMAIN_SUFFIX",
          "target_project": "TARGET_PROJECT",
          "target_network": "TARGET_NETWORK",
        }
      ],
    },
)

donde

  • NETWORK_ATTACHMENT es el nombre o la ruta completa de tu archivo de red.
  • DOMAIN_SUFFIX es el nombre DNS de la zona de Cloud DNS privada que has creado al configurar el emparejamiento de DNS privado.
  • TARGET_PROJECT es el proyecto que aloja la red de VPC.
  • TARGET_NETWORK es el nombre de la red de VPC.

Puedes configurar varios agentes para que usen un único adjunto de red compartido o adjuntos de red únicos y específicos. Para usar un archivo de red compartido, proporcione el mismo archivo de red en el psc_interface_config de cada agente que cree.

Configurar claves de cifrado gestionadas por el cliente

Puedes usar una clave personalizada para cifrar los datos de tu agente en reposo. Consulta Claves de encriptado gestionadas por el cliente (CMEK) en Agent Engine para obtener más información.

Para configurar la clave personalizada (CMEK) de tu agente, debes proporcionar el nombre del recurso de la clave al parámetro encryption_spec al crear la instancia de Agent Engine.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = agent_engines.create(
    local_agent,
    # ... other parameters
    encryption_spec={"kms_key_name": kms_key_name},
)

Crear una instancia de AgentEngine

Para desplegar el agente en Vertex AI, usa agent_engines.create para transferir el objeto local_agent junto con cualquier configuración opcional:

remote_agent = agent_engines.create(
    local_agent,                     # Optional.
    requirements=requirements,       # Optional.
    extra_packages=extra_packages,   # Optional.
    gcs_dir_name=gcs_dir_name,       # Optional.
    display_name=display_name,       # Optional.
    description=description,         # Optional.
    env_vars=env_vars,               # Optional.
    build_options=build_options,     # Optional.
    service_account=service_account, # Optional.
    min_instances=min_instances,     # Optional.
    max_instances=max_instances,     # Optional.
    resource_limits=resource_limits, # Optional.
    container_concurrency=container_concurrency, # Optional
    encryption_spec=encryption_spec, # Optional.
)

El despliegue tarda unos minutos, durante los cuales se realizan los siguientes pasos en segundo plano:

  1. Se genera un paquete de los siguientes artefactos de forma local:

  2. El paquete se sube a Cloud Storage (en la carpeta correspondiente) para organizar los artefactos.

  3. Los URIs de Cloud Storage de los artefactos correspondientes se especifican en PackageSpec.

  4. El servicio Vertex AI Agent Engine recibe la solicitud, crea contenedores e inicia servidores HTTP en el backend.

La latencia de implementación depende del tiempo total que se tarda en instalar los paquetes necesarios. Una vez desplegado, remote_agent corresponde a una instancia de local_agent que se ejecuta en Vertex AI y se puede consultar o eliminar. Es independiente de las instancias locales del agente.

Concede permisos al agente implementado

Si el agente implementado necesita permisos adicionales, sigue las instrucciones de Configurar la identidad y los permisos de tu agente.

Si has definido secretos como variables de entorno, debes conceder el siguiente permiso:

  • Lector de recursos de Secret Manager (roles/secretmanager.secretAccessor)

Obtener el ID de recurso del agente

Cada agente implementado tiene un identificador único. Puedes ejecutar el siguiente comando para obtener el identificador resource_name de tu agente implementado:

remote_agent.resource_name

La respuesta debería tener el siguiente aspecto:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

donde

  • PROJECT_ID es el Google Cloud ID del proyecto en el que se ejecuta el agente desplegado.

  • LOCATION es la región en la que se ejecuta el agente desplegado.

  • RESOURCE_ID es el ID del agente implementado como recurso reasoningEngine.

Siguientes pasos