Implementa un agente

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

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

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

Nota: La implementación de Vertex AI Agent Engine solo admite Python.

Requisitos previos

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

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

(Opcional) Configura tu agente para la implementación

Puedes realizar las siguientes configuraciones opcionales para tu agente:

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 debe 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.112.0) cuando desarrolles 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 las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa 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:

• Fija o establece un límite superior para la versión de un paquete determinado (como 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",
    ]
    

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

Advertencia: No debes establecer 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, 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.

Nota: Solo puedes hacer referencia a los secretos (y sus versiones) que se administran 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 de Secret Manager. Si necesitas especificar secretos administrados, 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 que se indican en Configura la identidad y los permisos de tu agente para otorgarle a tu agente el permiso de Secret Manager Secret Accessor (roles/secretmanager.secretAccessor).

Cómo definir controles de recursos personalizados

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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.

  Nota: Mientras esta función esté en versión preliminar, incluso si configuras una mayor cantidad de instancias mínimas, no se te facturará el tiempo en que un agente esté inactivo. Este comportamiento de facturación está sujeto a cambios en el futuro.

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

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

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

  • Para conocer la CPU requerida en diferentes valores de memoria, consulta Cómo configurar límites de memoria.

• 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 = 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
    }
)

Define 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 raíz.

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 configurar gcs_dir_name como 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())

Define el nombre visible

Puedes establecer el nombre visible para el recurso ReasoningEngine de la siguiente manera:

display_name = "Currency Exchange Rate Agent (Staging)"

Define la descripción

Puedes establecer la descripción del recurso ReasoningEngine:

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

Define las etiquetas

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

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

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
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 electrónico de la cuenta de servicio, no el URI completo del recurso, como projects/{project_id}/serviceAccounts/{service_account_email}.

Configura la interfaz de Private Service Connect

Si tienes configurado el intercambio de tráfico de DNS y la interfaz de Private Service Connect, puedes especificar tu adjunto de red y el intercambio de tráfico de DNS privado cuando implementes 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 de acceso completa de tu adjunto de red. Si la vinculación de red se crea en un proyecto (como el proyecto host de VPC compartida) diferente de aquel en el que usas Agent Engine, debes pasar la ruta de acceso completa de la vinculación 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. Puede ser diferente del proyecto de Network Attachment.
• 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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Crea una instancia de AgentEngine

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

Deployment 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 contiene los requisitos del paquete
   • dependencies.tar.gz un archivo tar que contiene paquetes adicionales.

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

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

4. El servicio Vertex AI Agent Engine recibe la solicitud, crea contenedores y activa 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.

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 devolver la lista de operaciones que admite el agente. Consulta Cómo enumerar las operaciones admitidas para obtener más detalles.
• 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) Obtén el ID del 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 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.

(Opcional) Enumera las operaciones admitidas

Cada agente implementado tiene una lista de operaciones admitidas. Puedes ejecutar el siguiente comando para obtener la lista de operaciones que admite 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 para el agente al que puedes llamar. El conjunto de operaciones admitidas depende del framework que usaste para desarrollar tu agente:

• Kit de desarrollo de agentes
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Personalizado

Otorga permisos al agente implementado (opcional)

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.

¿Qué sigue?

• Usa el agente.
• Administra los agentes implementados.
• Soluciona problemas de implementación de un agente.
• Obtén asistencia.