Implementa un agente

Para implementar un agente en Vertex AI Agent Engine, elige entre dos métodos principales:

  • Implementación desde un objeto de agente: Es ideal para el desarrollo interactivo en entornos como Colab, ya que permite la implementación de objetos local_agent en la memoria. Este método funciona mejor para los agentes con estructuras que no contienen componentes complejos no serializables.
  • Implementación desde archivos fuente: Este método es adecuado para flujos de trabajo automatizados, como las canalizaciones de CI/CD y las herramientas de infraestructura como código, como Terraform, lo que permite implementaciones completamente declarativas y automatizadas. Implementa tu agente directamente desde el código fuente local y no requiere un bucket de Cloud Storage.

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

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:

Crea una instancia de AgentEngine

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

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

  • Implementación desde archivos fuente para flujos de trabajo automatizados basados en archivos

Desde un objeto de agente

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.
        "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.
    },
)

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:

  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.

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

Desde archivos fuente

Para realizar la implementación desde archivos fuente en Vertex AI, usa client.agent_engines.create proporcionando 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 pasar un objeto de agente ni un bucket 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 para la implementación de la fuente intercalada son los siguientes:

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

  • class_methods (obligatorio, list[dict]): Es una 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 List supported operations 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): Es la ruta de acceso a un archivo de requisitos de pip dentro de las rutas de acceso especificadas en source_packages. El valor predeterminado es requirements.txt en el directorio raíz de la fuente empaquetada.

Deployment 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 de acceso especificadas en source_packages.
  2. Este archivo se codifica y se envía directamente a la API de Vertex AI.
  3. El servicio de Vertex AI Agent Engine recibe el archivo, lo extrae, instala las dependencias de requirements_file (si se proporciona) y, luego, inicia la aplicación del agente con los parámetros entrypoint_module y entrypoint_object especificados.

La latencia de Deployment depende del tiempo total que lleva instalar los paquetes requeridos. Una vez implementado, remote_agent corresponde a una instancia de la aplicación del agente que se ejecuta en Vertex AI y que se puede consultar o borrar.

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

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

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) 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 verse como 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:

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?