Implementa un agente

Para implementar un agente en Vertex AI Agent Engine, elige entre tres 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 canalizaciones de CI/CD y 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.
  • Implementar desde Developer Connect: Se recomienda para los proyectos que se administran en un repositorio de Git vinculado a través de Developer Connect. Este método optimiza la implementación de agentes directamente desde tu código fuente y admite de forma nativa el control de versión, la colaboración en equipo y las canalizaciones de CI/CD. Antes de usar este método, configura el vínculo a tu repositorio de Git siguiendo las instrucciones que se indican en Cómo configurar el vínculo al repositorio de Git de Developer Connect.

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 Developer Connect para flujos de trabajo basados en Git

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

Desde Developer Connect

Para realizar la implementación desde Developer Connect en Vertex AI, usa client.agent_engines.create proporcionando developer_connect_source, entrypoint_module y entrypoint_object en el diccionario de configuración, junto con otras configuraciones opcionales. Este método te permite implementar código directamente desde un repositorio de Git conectado.

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Los parámetros para la implementación de Developer Connect son los siguientes:

  • developer_connect_source (obligatorio, dict): Es la configuración para recuperar el código fuente. Consulta cómo configurar el vínculo al repositorio de Git de Developer Connect para obtener más detalles.
    • git_repository_link (obligatorio, str): Es el nombre del recurso del vínculo del repositorio de Git de Developer Connect.
    • revision (obligatorio, str): Es la revisión que se recuperará (rama, etiqueta o SHA de confirmación).
    • dir (obligatorio, str): Es el directorio raíz del código del agente dentro del repositorio.
  • entrypoint_module (obligatorio, str): Es el nombre del módulo de Python que contiene el punto de entrada del agente, en relación con el directorio especificado en developer_connect_source.dir.
  • 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).
  • requirements_file (opcional, str): Es la ruta de acceso a un archivo de requisitos de pip en relación con la raíz de la fuente. La configuración predeterminada es requirements.txt.

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

  1. El servicio de Vertex AI Agent Engine recupera el código fuente de la revisión del repositorio de Git especificada.
  2. El servicio instala dependencias de requirements_file (si se proporciona).
  3. El servicio inicia la aplicación del agente con los parámetros entrypoint_module y entrypoint_object especificados.

Desde archivos de origen

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

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

La latencia de la 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 lo siguiente:

(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 usar AgentEngine.operation_schemas 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 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?