Implementa un agente

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

  1. Define los requisitos del paquete (opcional)
  2. Define los archivos fuente (opcional)
  3. (Opcional) Organiza el directorio de Cloud Storage
  4. Define los metadatos del recurso (opcional)
  5. Crea una instancia de AgentEngine

Antes de comenzar

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

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

Paso 1: Define los requisitos del paquete

Proporciona el conjunto de paquetes que requiere el agente para que se implemente. Puede ser una lista de elementos que pip instalará o la ruta de acceso a un archivo que siga el Formato de archivo de requisitos.

Si el agente no tiene ninguna dependencia, puedes establecerlo en Ninguno:

requirements = None

Si el agente usa una plantilla específica del framework, debes especificar la versión del SDK que se importa (p.ej., 1.77.0) cuando desarrolles el agente.

LangChain 

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

LangGraph 

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

Restricciones de versión (opcional)

Si quieres o necesitas establecer un límite superior o fijar la versión de un paquete determinado (p.ej., google-cloud-aiplatform), haz lo siguiente:

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

Puedes agregar paquetes y restricciones adicionales a la lista:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]==1.75.0",
    "cloudpickle==3.0", # new
]

[Opcional] Rama de desarrollo

Puedes indicar la versión de un paquete que se encuentra en una rama de GitHub o en una solicitud de extracción, por ejemplo:

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    "cloudpickle==3.0",
]

[Opcional] Formato del archivo de requisitos

Puedes mantener la lista de requisitos en un archivo (p.ej., 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,langchain]
cloudpickle==3.0

Paso 2: Paquetes adicionales

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

Si el agente no requiere ningún paquete adicional, puedes configurarlo en None:

extra_packages = None

[Opcional] Archivos y directorios

Para incluir un solo archivo (p.ej., agents/agent.py), puedes agregarlo a la lista:

extra_packages = ["agents/agent.py"]

Para incluir el conjunto de archivos de un directorio completo (p.ej., agents/), puedes especificar el directorio de la siguiente manera:

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

Objetos binarios de ruedas [opcional]

Puedes incluir objetos binarios de rueda de Python (p.ej., path/to/python_package.whl) y especificarlos en los requisitos del paquete:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]",
    "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

Paso 3: Directorio de Cloud Storage

Los artefactos de la etapa de pruebas se reemplazarán si corresponden a un bucket secundario existente (una carpeta en un bucket de Cloud Storage). Si es necesario, puedes especificar el subbucket para los artefactos de la etapa de pruebas. Este paso es opcional y puedes configurarlo en None si no te importa sobrescribir los archivos del subbucket predeterminado:

gcs_dir_name = None

Para evitar reemplazar los archivos (p.ej., para diferentes entornos, como dev, etapa de pruebas y producción), puedes configurar los subbuckets correspondientes y especificar el subbucket en el que se debe implementar el artefacto, como:

gcs_dir_name = "dev" # or "staging" or "prod"

Si quieres o necesitas evitar colisiones, puedes generar un UUID aleatorio, por ejemplo:

import uuid
gcs_dir_name = str(uuid.uuid4())

Paso 4: Metadatos de recursos

Puedes establecer metadatos en el recurso ReasoningEngine que se crea en Vertex AI, por ejemplo:

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 los parámetros, consulta la referencia de la API.

Paso 5: Crea una instancia de AgentEngine

Para implementar la aplicación en Vertex AI, usa agent_engines.create y pasa el objeto como parámetro:

remote_agent = agent_engines.create(
    local_agent,                    # Required.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # Optional.
)

La implementación tarda unos minutos en ejecutarse. Cuando implementes el agente,

  1. Se genera un paquete de artefactos de forma local, que incluye lo siguiente:
    • *.pkl es un archivo pickle que corresponde a local_agent.
    • requirements.txt es 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 el subbucket correspondiente) para preparar los artefactos.
  3. Los URIs de Cloud Storage de los artefactos correspondientes se especifican en PackageSpec.
  4. El servicio de Agent Engine recibe la solicitud, compila contenedores y activa los servidores HTTP en el backend.

La latencia de la implementación depende del tiempo total que se tarda en instalar los paquetes necesarios. Una vez que se implementa, remote_agent corresponde a una instancia de local_agent que se ejecuta en Vertex AI y se puede consultar o borrar. Es independiente de las instancias locales 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

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 google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai y pydantic.
  2. Minimiza la cantidad de dependencias en tu aplicación. Esto reduce la cantidad de cambios drásticos cuando actualizas tus dependencias y facilita la actualización de tu aplicación con el tiempo para obtener funciones más nuevas.

Implementa en producción con el paquete de inicio del agente

El Agent Starter Pack es una colección de plantillas de agentes de IA generativa listas para la producción compiladas para Vertex AI Agent Engine. Acelera la implementación, ya que proporciona lo siguiente:

  • Plantillas de agentes prediseñadas: ReAct, RAG, multiagente y mucho más.
  • Zona de pruebas interactiva: Prueba y, luego, interactúa con tu agente.
  • Infraestructura automatizada: Usa Terraform para optimizar la administración de recursos.
  • Canalizaciones de CI/CD: Flujos de trabajo de implementación automatizados que aprovechan Cloud Build
  • Observabilidad: Incluye compatibilidad integrada con Cloud Trace y Cloud Logging.

Cómo comenzar: Guía de inicio rápido

¿Qué sigue?