Desplegar un agente

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

1. Cumple los requisitos previos.
2. (Opcional) Configura tu agente para la implementación.
3. Crea una instancia de AgentEngine.
4. (Opcional) Obtén el ID de recurso del agente.
5. (Opcional) Consulta la lista de operaciones admitidas.
6. (Opcional) Concede permisos al agente implementado.

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

Nota: El despliegue de Vertex AI Agent Engine solo admite Python.

Requisitos previos

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

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

(Opcional) Configurar el agente para el despliegue

Puedes hacer las siguientes configuraciones opcionales para tu agente:

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 incompatibles 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.112.0) al desarrollar el agente.

ADK

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

A2A

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "a2a-sdk>=0.3.4"
    # 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

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

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.112.0",
    ]
    

• Añade paquetes y restricciones adicionales:

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]==1.112.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
    ]
    

• 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, esto te permite usar utilidades privadas que hayas desarrollado y que no estén disponibles en PyPI o GitHub.

Si el agente no necesita ningún paquete adicional, puedes definir extra_packages como 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 asignarle el valor None:

env_vars = None

Advertencia: No debes definir las siguientes variables de entorno: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION y GOOGLE_APPLICATION_CREDENTIALS. Además, debes evitar el prefijo GOOGLE_CLOUD_AGENT_ENGINE para evitar conflictos de nombres con las variables de entorno de Vertex AI Agent Engine.

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

Nota: Solo puedes hacer referencia a secretos (y sus versiones) que se gestionen en el mismo proyecto que el agente implementado.

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

Nota: Esta opción no admite la integración con Secret Manager. Si necesitas especificar secretos gestionados, debes especificar las variables de entorno como un diccionario.

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"],
#   }

También debes seguir las instrucciones de Configurar la identidad y los permisos de tu agente para concederle a tu agente el permiso Secret Accessor de Secret Manager (roles/secretmanager.secretAccessor).

Definir controles de recursos personalizados

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

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.

  Nota: Mientras esta función esté en versión preliminar, aunque configures un número mínimo de instancias superior, no se te cobrará por el tiempo que un agente esté inactivo. Este comportamiento de facturación está sujeto a cambios en el futuro.

• 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 agentes. El valor recomendado es 2 * cpu + 1. El valor predeterminado es 9.

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

Definir las opciones de compilación

Puedes especificar opciones de compilación para el agente, como secuencias de comandos de instalación que se ejecuten al compilar la imagen del contenedor del agente. Esto es ú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 almacenamiento provisional. Puedes definir gcs_dir_name como None si no te importa que se sobrescriban 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())

Define el nombre visible

Puedes definir el nombre visible del recurso ReasoningEngine de la siguiente manera:

display_name = "Currency Exchange Rate Agent (Staging)"

Define la descripción

Puedes definir la descripción del recurso ReasoningEngine de la siguiente manera:

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

Definir las etiquetas

Puedes definir las etiquetas del recurso ReasoningEngine como un diccionario de pares de cadenas clave-valor. A continuación, se muestra un ejemplo:

labels = {"author": "username", "version": "latest"}

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
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

Nota: Especifica solo el correo de la cuenta de servicio, no el URI completo del recurso, como projects/{project_id}/serviceAccounts/{service_account_email}.

Configurar una interfaz de Private Service Connect

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

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "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 adjunto de red. Si la vinculación de red se crea en un proyecto (como el proyecto host de la VPC compartida) diferente de aquel en el que usas Agent Engine, debes indicar la ruta completa de la vinculación de red.
• DOMAIN_SUFFIX es el nombre de 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. Puede ser diferente del proyecto de adjunto de red.
• TARGET_NETWORK es el nombre de la red de VPC.

Puedes configurar varios agentes para que usen una sola conexión de red compartida o conexiones de red únicas y específicas. Para usar un archivo adjunto de red compartida, proporcione el mismo archivo adjunto de red en el campo 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 el artículo Claves de encriptado gestionadas por el cliente (CMEK) de 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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Crear una instancia de AgentEngine

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

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # 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:

   • *.pkl un archivo pickle correspondiente a local_agent.
   • requirements.txt un archivo de texto que contenga los requisitos del paquete.
   • dependencies.tar.gz un archivo tar que contenga los paquetes adicionales.

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.

El objeto remote_agent corresponde a una clase AgentEngine que contiene los siguientes atributos:

• Un remote_agent.api_resource con información sobre el agente implementado. También puedes llamar a agent.operation_schemas() para que se devuelva la lista de operaciones que admite el agente. Consulta Lista de operaciones admitidas para obtener más información.
• un remote_agent.api_client que permite interacciones de servicio síncronas.
• un remote_agent.async_api_client que permite interacciones de servicio asíncronas.

(Opcional) Obtener el ID de recurso del agente

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

remote_agent.api_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.

(Opcional) Mostrar las operaciones admitidas

Cada agente implementado tiene una lista de operaciones admitidas. Puedes ejecutar el siguiente comando para obtener la lista de operaciones admitidas por el agente implementado:

remote_agent.operation_schemas()

El esquema de cada operación es un diccionario que documenta la información de un método del agente al que puedes llamar. El conjunto de operaciones admitidas depende del framework que hayas usado para desarrollar tu agente:

• Agent Development Kit
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Personalizado

(Opcional) 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.

Siguientes pasos

• Usa el agente.
• Gestionar agentes implementados.
• Solucionar problemas al implementar un agente
• Obtener asistencia