Desplegar un agente

Para desplegar un agente en Vertex AI Agent Engine, puedes elegir entre dos métodos principales:

  • Implementar desde un objeto de agente: es ideal para el desarrollo interactivo en entornos como Colab, ya que permite implementar objetos local_agent en memoria. Este método es el más adecuado para los agentes con estructuras que no contienen componentes complejos no serializables.
  • Despliegue desde archivos de origen: este método es adecuado para flujos de trabajo automatizados, como flujos de procesamiento de CI/CD y herramientas de infraestructura como código, como Terraform, lo que permite realizar despliegues totalmente declarativos y automatizados. Despliega tu agente directamente desde el código fuente local y no requiere un segmento de Cloud Storage.

Para empezar, 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.

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:

Crear una instancia de AgentEngine

En esta sección se describe cómo crear una instancia de AgentEngine para implementar un agente.

Para desplegar un agente en Vertex AI Agent Engine, puedes elegir entre los siguientes métodos:

  • Implementación desde un objeto de agente para el desarrollo interactivo.

  • Despliegue desde archivos de origen para flujos de trabajo automatizados basados en archivos.

Desde un objeto de agente

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.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # 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:

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

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.

A partir de archivos de origen

Para implementar desde archivos de origen en Vertex AI, usa client.agent_engines.create. Para ello, proporciona source_packages, entrypoint_module, entrypoint_object y class_methods en el diccionario de configuración, junto con otras configuraciones opcionales. Con este método, no es necesario que transfiera un objeto de agente ni un segmento de Cloud Storage.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

Los parámetros de la implementación de fuentes entre líneas son los siguientes:

  • source_packages (obligatorio, list[str]): lista de rutas de archivos o directorios locales que se incluirán en la implementación. El tamaño total de los archivos y directorios de source_packages no debe superar los 8 MB.
  • entrypoint_module (obligatorio, str): nombre de módulo de Python completo que contiene el punto de entrada del agente (por ejemplo, agent_dir.agent).
  • entrypoint_object (obligatorio, str): nombre del objeto invocable dentro de entrypoint_module que representa la aplicación del agente (por ejemplo, root_agent).

  • class_methods (obligatorio, list[dict]): lista de diccionarios que definen los métodos expuestos del agente. Cada diccionario incluye un campo name (obligatorio), un campo api_mode (obligatorio) y un campo parameters. Consulta Lista de operaciones admitidas para obtener más información sobre los métodos de un agente personalizado.

    Por ejemplo:

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (Opcional, str): ruta a un archivo de requisitos de pip dentro de las rutas especificadas en source_packages. El valor predeterminado es requirements.txt en el directorio raíz del origen empaquetado.

El despliegue tarda unos minutos, durante los cuales se realizan los siguientes pasos en segundo plano:

  1. El SDK de Vertex AI crea un archivo tar.gz de las rutas especificadas en source_packages.
  2. Este archivo se codifica y se envía directamente a la API de Vertex AI.
  3. El servicio Vertex AI Agent Engine recibe el archivo, lo extrae, instala las dependencias de requirements_file (si se proporciona) e inicia la aplicación del agente con los entrypoint_module y entrypoint_object especificados.

La latencia de implementación depende del tiempo total que se tarde en instalar los paquetes necesarios. Una vez desplegado, remote_agent corresponde a una instancia de la aplicación del agente que se ejecuta en Vertex AI y se puede consultar o eliminar.

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.

A continuación, se muestra un ejemplo de cómo implementar un agente a partir de archivos de origen:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

(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:

(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