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 en 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

Vertex AI Agent Engine admite la interfaz de Private Service Connect y el intercambio de tráfico de DNS para el tráfico de salida privado y seguro.

¿Por qué usar una interfaz de Private Service Connect?

Tu agente se implementa en una red segura administrada por Google sin acceso a tu red de nube privada virtual (VPC). Una interfaz de PSC crea un puente privado y seguro hacia tu red, lo que la convierte en la solución recomendada para interactuar con servicios alojados de forma privada en tus entornos de VPC, locales y de varias nubes.

Además de proporcionar acceso privado, esta conexión también es necesaria para habilitar el acceso a Internet cuando se usan los Controles del servicio de VPC. Consulta Acceso a Internet pública.

Cómo funciona

Cuando configuras una interfaz de PSC, Agent Engine aprovisiona una interfaz en un proyecto de usuario propiedad de Google en el que se ejecuta tu agente. Esta interfaz se conecta directamente a un adjunto de red en tu proyecto. Todo el tráfico entre tu agente y tu VPC viaja de forma segura dentro de la red de Google y nunca atraviesa la Internet pública.

Acceso a Internet público

La capacidad del agente para acceder a Internet pública depende de la configuración de seguridad de tu proyecto, específicamente si usas los Controles del servicio de VPC.

Comportamiento predeterminado (sin Controles del servicio de VPC)
  • Cuando configuras tu agente solo con una interfaz de PSC, este conserva su acceso predeterminado a Internet. Este tráfico saliente sale directamente del entorno seguro administrado por Google en el que se ejecuta tu agente.
Con Controles del servicio de VPC
  • Cuando tu proyecto forma parte de un perímetro de Controles del servicio de VPC, el perímetro bloquea el acceso predeterminado a Internet del agente para evitar el robo de datos. Para permitir que el agente acceda a Internet pública en esta situación, debes configurar de forma explícita una ruta de salida segura que enrute el tráfico a través de tu VPC. La forma recomendada de lograr esto es configurar un servidor proxy dentro de tu perímetro de VPC y crear una puerta de enlace de Cloud NAT para permitir que la VM proxy acceda a Internet.

Antes de comenzar

Para habilitar la conectividad privada de tu agente implementado con la interfaz de Private Service Connect, debes configurar una red de VPC, una subred y un adjunto de red en tu proyecto de usuario.

Requisitos del rango de IP de la subred

Agent Engine recomienda una subred /28.

La subred de la vinculación de red admite direcciones RFC 1918 y que no son RFC 1918, con la excepción de las subredes 100.64.0.0/10 y 240.0.0.0/4. Agent Engine solo puede conectarse a rangos de direcciones IP RFC 1918 que se puedan enrutar desde la red especificada. Agent Engine no puede acceder a una dirección IP pública de uso privado ni a estos rangos que no son RFC 1918:

  • 100.64.0.0/10
  • 192.0.0.0/24
  • 192.0.2.0/24
  • 198.18.0.0/15
  • 198.51.100.0/24
  • 203.0.113.0/24
  • 240.0.0.0/4

Consulta Configura una interfaz de Private Service Connect para obtener más detalles sobre la configuración.

Uso con la VPC compartida

Puedes usar la interfaz de Private Service Connect con una arquitectura de VPC compartida, que te permite crear tu Agent Engine en un proyecto de servicio mientras usas una red de un proyecto host central.

Cuando configures PSC-I en un entorno de VPC compartida, crea la subred en el proyecto host y, luego, crea la conexión de red en el proyecto de servicio.

Para que el proyecto de servicio use la red del proyecto host, debes otorgar el permiso de IAM adecuado. El agente de servicio de Vertex AI de tu proyecto de servicio necesita el rol de usuario de la red de Compute (roles/compute.networkUser) en el proyecto host.

Implementa agentes con la interfaz de Private Service Connect

Una vez que se configura la conexión de red, puedes especificarla cuando crees la instancia de AgentEngine.

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
    },
)

donde

  • NETWORK_ATTACHMENT es el nombre o la ruta de acceso completa del adjunto de red que creaste.

Usa adjuntos de red con varios agentes

Tienes la flexibilidad de decidir cómo tus agentes comparten los recursos de red. 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.

Intercambio de tráfico de DNS

Si bien la interfaz de Private Service Connect proporciona la ruta de red segura, el intercambio de tráfico de DNS proporciona el mecanismo de detección de servicios. Con PSC-I, aún necesitarías conocer la dirección IP específica del servicio en la red de VPC. Si bien puedes conectarte a los servicios con sus direcciones IP internas, no se recomienda hacerlo en sistemas de producción en los que las IPs pueden cambiar. Con el peering de DNS, el agente implementado puede conectarse a los servicios de tu red de VPC con nombres de DNS estables y legibles en lugar de direcciones IP. El intercambio de tráfico de DNS permite que los agentes implementados resuelvan nombres de DNS con los registros de una zona privada de Cloud DNS en tu VPC. Consulta Configura un intercambio de tráfico de DNS privado.

Una vez que se configura el peering de DNS privado, puedes especificarlo cuando crees la instancia de AgentEngine.

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 del adjunto de red que creaste.
  • 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.

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?