Implementa un agente

Implementar un agente en Agent Runtime lo hace disponible de forma remota para controlar solicitudes. En este documento, se explican las formas de implementar un agente según tu flujo de trabajo de desarrollo: desde un objeto de ejecución, archivos fuente locales, un Dockerfile, una imagen de contenedor alojada en Artifact Registry o directamente a través de un repositorio de Git conectado.

Para implementar un agente en Agent Runtime, elige uno de los siguientes métodos:

Developer Connect

Se recomienda para los proyectos administrados en un repositorio de Git que se vinculan 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.

Solo puedes usar este método de implementación con Python.

Archivos fuente

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

Solo puedes usar este método de implementación con Python.

Dockerfile

Es similar a la implementación desde archivos fuente. Implementas tu agente directamente desde el código fuente local sin necesidad de un bucket de Cloud Storage. Este método es adecuado si necesitas definir y controlar el servidor de API que se implementa. El contenedor implementado debe cumplir con el contrato de tiempo de ejecución.

Puedes usar este método de implementación con cualquier lenguaje. En los ejemplos de esta página, se usa Python.

Imagen de contenedor

Es similar a la implementación desde Dockerfile. Implementarás una imagen de contenedor alojada en Artifact Registry. Usa este método si necesitas controlar el proceso de compilación de la imagen del contenedor y reducir la latencia de implementación. La imagen de contenedor debe cumplir con el contrato de tiempo de ejecución.

Puedes usar este método de implementación con cualquier lenguaje. En los ejemplos de esta página, se usa Python.

SDK de Agent Platform

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.

Para comenzar, sigue estos pasos:

  1. Completar los requisitos previos
  2. Opcional: Configura tu agente para la implementación
  3. Crea una instancia de Agent Platform
  4. Opcional: Obtén el ID del recurso del agente
  5. Opcional: Enumera las operaciones admitidas
  6. Opcional: Otorga permisos al agente implementado

Requisitos previos

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

  1. Configura tu entorno
  2. Crea un agente

Opcional: Configura tu agente para la implementación

Puedes realizar configuraciones opcionales para tu agente. En los ejemplos de esta sección, se usa Python.

Crea una instancia de Agent Platform

En esta sección, se describe cómo crear una instancia de Agent Platform para implementar un agente. Puedes elegir entre los siguientes métodos:

Developer Connect

Para realizar la implementación desde Developer Connect en Agent Platform, 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.

Solo puedes usar este método de implementación con Python. 

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 (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 (str): Es el nombre del recurso del vínculo al repositorio de Git de Developer Connect.
    • revision (str): Es la revisión que se recuperará (rama, etiqueta o SHA de confirmación).
    • dir (str): Es el directorio raíz del código del agente dentro del repositorio.
  • entrypoint_module (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 (str): Es el nombre del objeto invocable dentro de entrypoint_module que representa la aplicación del agente (por ejemplo, root_agent).
  • requirements_file (str): Opcional: Es la ruta 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 Agent Runtime recupera el código fuente de la revisión del repositorio de Git especificada.
  2. El servicio instala dependencias desde requirements_file (si se proporciona).
  3. El servicio inicia la aplicación del agente con los parámetros entrypoint_module y entrypoint_object especificados.

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 Agent Platform y se puede consultar o borrar.

El objeto remote_agent corresponde a una clase AgentEngine que contiene lo siguiente:

Archivos fuente

Para realizar la implementación desde archivos fuente en Agent Platform, 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 necesitas pasar un objeto de agente ni un bucket de Cloud Storage.

Solo puedes usar este método de implementación con Python. 

# 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={
        "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 (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 (str): Es el nombre del módulo de Python completamente calificado que contiene el punto de entrada del agente (por ejemplo, agent_dir.agent).
  • entrypoint_object (str): Es el nombre del objeto invocable dentro de entrypoint_module que representa la aplicación del agente (por ejemplo, root_agent).
  • class_methods (list[dict]): Es una lista de diccionarios que definen los métodos expuestos del agente. Cada diccionario incluye un campo name, api_mode y un campo parameters opcional. 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": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str): Opcional: 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 Agent Platform 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 Agent Platform.
  3. El servicio de Agent Runtime 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 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 Agent Platform y se puede consultar o borrar.

El objeto remote_agent corresponde a una clase AgentEngine que contiene lo siguiente:

Dockerfile

La implementación desde Dockerfile en la Agent Platform sigue un enfoque similar al de la implementación desde archivos fuente, excepto que usas image_spec en la configuración en lugar de entrypoint_module, entrypoint_object y requirements_file. El contenedor compilado a partir del Dockerfile debe cumplir con el contrato de tiempo de ejecución.

Puedes usar este método de implementación con cualquier lenguaje. En el ejemplo de esta sección, se usa Python.

A continuación, se muestra un ejemplo de implementación de un agente con un Dockerfile:

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

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 Agent Platform y se puede consultar o borrar.

El objeto remote_agent corresponde a una clase AgentEngine que contiene lo siguiente:

Imagen de contenedor

Para realizar la implementación desde una imagen de contenedor, primero sigue las instrucciones de configuración de Trae tu propio contenedor y asegúrate de instalar una versión de google-cloud-aiplatform que satisfaga >=1.144. La imagen de contenedor debe cumplir con el contrato de tiempo de ejecución.

Puedes usar este método de implementación con cualquier lenguaje. En el ejemplo de esta sección, se usa Python.

A continuación, se muestra un ejemplo de implementación de un agente con una imagen de contenedor:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

Aquí, CONTAINER_IMAGE_URI corresponde al URI de la imagen de contenedor en Artifact Registry (como us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

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 Agent Platform y se puede consultar o borrar.

El objeto remote_agent corresponde a una clase AgentEngine que contiene lo siguiente:

SDK de Agent Platform

Para implementar el agente en Agent Platform, 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 de Agent Runtime recibe la solicitud, crea contenedores y activa servidores HTTP en el backend.

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 Agent Platform y 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 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.

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

Opcional: Otorga permisos al agente implementado

Si el agente implementado necesita permisos adicionales, sigue las instrucciones que se indican en Configura la identidad y los permisos de tu agente.

Opcional: Implementa agentes con infraestructura empresarial

Para implementar tu agente con un entorno completo que incluya capas de seguridad y gobernanza, copia y personaliza las siguientes plantillas de App Design Center:

¿Qué sigue?

Guía

Aprende a administrar los agentes que se implementaron en el entorno de ejecución administrado de Agent Platform.

Guía

Usar un agente con el entorno de ejecución de Agent Platform