Implementa un agente

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

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

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

Antes de comenzar

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

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

Configura tu agente para la implementación

Puedes realizar las siguientes configuraciones opcionales:

Define los requisitos del paquete

Proporciona el conjunto de paquetes que requiere el agente para la implementación. El conjunto de paquetes puede ser una lista de elementos que pip instalará o la ruta de acceso a un archivo que sigue el formato de archivo de requisitos. Sigue las siguientes prácticas recomendadas:

  1. Fija las versiones de tus paquetes para compilaciones reproducibles. Entre los paquetes comunes de los que debes hacer un seguimiento, se incluyen los siguientes: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai y pydantic.

  2. Minimiza la cantidad de dependencias en tu agente. Esto reduce la cantidad de cambios drásticos cuando actualizas tus dependencias y tu agente.

Si el agente no tiene dependencias, puedes establecer requirements en None:

requirements = None

Si el agente usa una plantilla específica del framework, debes especificar la versión del SDK que se importa (como 1.77.0) cuando desarrolles 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:

  • Para establecer un límite superior o fijar la versión de un paquete determinado (como google-cloud-aiplatform), haz lo siguiente:

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

  • Agrega 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 (como 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

Define paquetes adicionales

Puedes incluir archivos o directorios locales que contengan archivos fuente de Python locales requeridos. En comparación con los requisitos de paquetes, esto te permite usar utilidades privadas que desarrollaste y que no están disponibles en PyPI o GitHub.

Si el agente no requiere ningún paquete adicional, puedes establecer extra_packages en 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 en un directorio completo (por ejemplo, agents/):

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

  • Especifica binarios de Python wheel (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

Define las 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 configurarlo como None:

env_vars = None

Para especificar las variables de entorno, tienes 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 en Secret Manager y que esté disponible como una 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 antes de especificar 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"],
#   }

Cómo definir controles de recursos personalizados

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

  • min_instances: Es la cantidad mínima de instancias de la aplicación que se deben mantener en ejecución en todo momento, con un rango de [0, 10]. El valor predeterminado es 1.

  • max_instances: Es la cantidad máxima de instancias de la aplicación que se pueden iniciar para controlar el aumento del tráfico, con un rango de [1, 1000]. El valor predeterminado es 100. Si se habilitan VPC-SC o PSC-I, el rango aceptable es [1, 100].

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

  • container_concurrency: Es la simultaneidad para cada servidor de contenedores y agentes. 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,
)

Cómo definir opciones de compilación

Puedes especificar opciones de compilación para el agente, como secuencias de comandos de instalación que se ejecutan cuando se compila la imagen de contenedor del agente. Esto es útil para instalar dependencias del sistema (por ejemplo, gcloud cli, npx) o cualquier otra configuración personalizada. Las secuencias de comandos se ejecutan con permisos de administrador.

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

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

A continuación, especifica el directorio installation_scripts en extra_packages y las rutas de acceso a la secuencia 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 comunes:

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

Define una carpeta de Cloud Storage

Los artefactos de la etapa de pruebas se reemplazan si corresponden a una carpeta existente en un bucket de Cloud Storage. Si es necesario, puedes especificar la carpeta de Cloud Storage para los artefactos de etapa de pruebas. Puedes establecer gcs_dir_name en None si no te importa sobrescribir los archivos de la carpeta predeterminada:

gcs_dir_name = None

Para evitar sobrescribir los archivos (por ejemplo, para diferentes entornos, como desarrollo, etapa de pruebas y producción), puedes configurar la carpeta correspondiente y especificar la carpeta en la que se 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())

Configura los metadatos de recursos

Puedes configurar 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 obtener un conjunto completo de parámetros, consulta la referencia de la API.

Configura una cuenta de servicio personalizada

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

Para ello, especifica el correo electrónico de tu cuenta de servicio personalizada como service_account cuando crees o actualices 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",
  ...
)

Configura la interfaz de Private Service Connect

Si tienes configurada la interfaz de Private Service Connect y el intercambio de tráfico de DNS, puedes especificar tu adjunto de red y el intercambio de tráfico de DNS privado cuando implementes 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 de acceso completa de tu adjunto de red.
  • DOMAIN_SUFFIX es el nombre de DNS de la zona privada de Cloud DNS que creaste cuando configuraste el peering 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 solo adjunto de red compartido o adjuntos de red únicos y dedicados. Para usar un adjunto de red compartido, proporciona el mismo adjunto de red en psc_interface_config para cada agente que crees.

Configura claves de encriptación administradas por el cliente

Puedes usar una clave personalizada para encriptar los datos en reposo de tu agente. Consulta Claves de encriptación administradas por el cliente (CMEK) de Agent Engine para obtener más detalles.

Para configurar la clave personalizada (CMEK) de tu agente, debes proporcionar el nombre del recurso de la clave al parámetro encryption_spec cuando crees 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},
)

Crea una instancia de AgentEngine

Para implementar el agente en Vertex AI, usa agent_engines.create para pasar 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.
)

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

  1. Se genera localmente un paquete de los siguientes artefactos:

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

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

  4. El servicio de Vertex AI Agent Engine recibe la solicitud, compila contenedores y, luego, inicia servidores HTTP en el backend.

La latencia de Deployment depende del tiempo total que lleva instalar los paquetes requeridos. Una vez implementado, remote_agent corresponde a una instancia de local_agent que se ejecuta en Vertex AI y que se puede consultar o borrar. Es independiente de las instancias locales del agente.

Otorga permisos al agente implementado

Si el agente implementado necesita permisos adicionales, sigue las instrucciones que se indican en Cómo configurar la identidad y los permisos de tu agente.

Si definiste secretos como variables de entorno, debes otorgar el siguiente permiso:

  • Usuario con acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor)

Obtén el ID del 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 ser similar a la siguiente cadena:

"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 implementado.

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

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

¿Qué sigue?