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:

• Requisitos del paquete
• Paquetes adicionales
• Variables de entorno
• Opciones de compilación
• Carpeta de Cloud Storage
• Metadatos del recurso

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.

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

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

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

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

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:

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

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

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)

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

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

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.

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

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:

   • *.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 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 Configura los permisos de tu agente de servicio.

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?

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