✋ Nota: Este artículo se publicó originalmente en mi blog Wiki Cloud.

Introducción

El desarrollo de agentes de inteligencia artificial está transformando la manera en que las organizaciones acceden a la información, automatizan tareas y optimizan sus procesos de negocio. Sin embargo, construir un agente es solo el primer paso. Para aprovechar realmente su potencial, es necesario llevarlo a un entorno que permita ejecutarlo de manera continua, facilitar su acceso a diferentes usuarios y administrar aspectos como la seguridad, la escalabilidad y la supervisión.

En este contexto, desplegar agentes de IA en la nube permite evolucionar desde una solución desarrollada en un entorno local hacia una aplicación empresarial preparada para responder a las necesidades de la organización.

En el artículo anterior construimos un Asistente de Políticas Corporativas utilizando Google ADK, Gemini, Google Drive y Streamlit. Aprendimos a consultar documentos corporativos mediante un sistema RAG léxico en memoria y a generar respuestas en lenguaje natural acompañadas de referencias a sus fuentes originales.

Ahora daremos el siguiente paso: desplegar nuestro agente en Google Cloud Agent Runtime, un servicio administrado que nos permitirá ejecutarlo en la nube sin depender de nuestro equipo local, y posteriormente integrarlo con Gemini Enterprise para que los usuarios puedan acceder al asistente desde una plataforma empresarial.

No volveremos a desarrollar la aplicación ni las herramientas que implementamos anteriormente; en esta ocasión nos centraremos en preparar el agente para su despliegue, validar su funcionamiento en la nube y publicarlo en Gemini Enterprise.

Para este laboratorio continuaremos utilizando Windows, PowerShell, Python 3.12 y el mismo repositorio del proyecto. El proyecto cuenta con versiones en español e inglés, disponibles en el mismo repositorio.

Objetivo y arquitectura de la solución

El objetivo de este ejercicio es dar continuidad al desarrollo de nuestro Asistente de Políticas Corporativas, reutilizando el agente construido con Google ADK para desplegarlo en Google Cloud Agent Runtime y posteriormente integrarlo con Gemini Enterprise.

Para ello, prepararemos el agente como un paquete instalable de Python que permita trasladar su lógica y dependencias a un entorno administrado en la nube, manteniendo Google Drive como repositorio documental y Gemini, a través de Vertex AI, como modelo encargado de interpretar las consultas y generar las respuestas.

Arquitectura objetivo del asistente de políticas corporativas
Figura 1 – Arquitectura objetivo del asistente de políticas corporativas.

En el artículo anterior comprobamos el funcionamiento del asistente desde nuestro entorno local utilizando tres alternativas: Streamlit, mediante una interfaz web personalizada; ADK Web, que nos permitió interactuar con el agente y observar la ejecución de sus herramientas; y ADK CLI, desde donde realizamos consultas directamente a través de la consola de comandos.

Estas pruebas nos permitieron validar la integración entre los diferentes componentes y comprobar que el agente podía recuperar información de las políticas corporativas mediante el sistema RAG, generar respuestas en lenguaje natural y proporcionar referencias a los documentos consultados.

En esta segunda parte evolucionaremos la arquitectura sin modificar su funcionalidad principal. La diferencia estará en que Google Cloud Agent Runtime asumirá la ejecución del agente, proporcionando un entorno administrado que facilita su disponibilidad, escalabilidad y supervisión. Por su parte, Gemini Enterprise incorporará una nueva capa de acceso para los usuarios empresariales, desde la cual podrán interactuar con el asistente sin necesidad de utilizar directamente las herramientas de desarrollo.

De esta manera, conservaremos la solución implementada anteriormente y ampliaremos sus posibilidades de utilización dentro de una organización.

La arquitectura propuesta mantiene a Google ADK como componente encargado de coordinar la conversación y ejecutar la herramienta de búsqueda de políticas, mientras que el sistema RAG continúa recuperando información de los documentos almacenados en Google Drive. Gemini utilizará estos contenidos como contexto para generar respuestas fundamentadas. Con esta integración, podremos pasar de un agente validado en nuestro equipo a una solución accesible desde Gemini Enterprise.

Nota de arquitectura: La conexión de Streamlit con el agente remoto se presenta como una posibilidad de evolución. La integración de Streamlit desarrollada en el artículo anterior ejecutaba el agente localmente.

Fases de implementación

Para desplegar nuestro Asistente de Políticas Corporativas en Google Cloud y posteriormente integrarlo con Gemini Enterprise, seguiremos un proceso dividido en siete etapas. Como se muestra en la siguiente figura, comenzaremos preparando el entorno y empaquetando el agente, para después desplegarlo en Agent Runtime, validar su funcionamiento mediante pruebas remotas y finalmente publicarlo en Gemini Enterprise, donde estará disponible para los usuarios autorizados de la organización.

Fases de implementación y despliegue del agente

Figura 2 – Fases de implementación y despliegue del agente.

Requisitos previos

Antes de continuar, asumiremos que la aplicación local ya responde correctamente, que los documentos de políticas se encuentran en una carpeta autorizada de Google Drive y que el entorno virtual del proyecto tiene instaladas las dependencias incluidas en requirements.txt.

Para realizar el despliegue necesitaremos un proyecto de Google Cloud con facturación habilitada, Google Cloud CLI, permisos para crear recursos de Agent Runtime, una cuenta de servicio de ejecución y un bucket de Cloud Storage para los artefactos temporales. El usuario que realiza el despliegue también necesita permisos para utilizar la cuenta de servicio.

Configuración de variables

Antes de continuar con la configuración de los recursos en Google Cloud, definiremos algunas variables en PowerShell que utilizaremos durante el despliegue de nuestro agente. Estas variables nos permitirán identificar el proyecto, la región, el bucket de almacenamiento, la cuenta de servicio y el usuario con el que trabajaremos. De esta manera, podremos ejecutar los siguientes comandos de forma más sencilla, sin necesidad de escribir repetidamente los mismos valores.

Solo tendremos que reemplazar los datos de ejemplo por los correspondientes a nuestro entorno de Google Cloud.

# Proyecto de Google Cloud $PROJECT_ID = "YOUR_PROJECT_ID" # Región de despliegue $REGION = "europe-west1" # Bucket de Cloud Storage $BUCKET_NAME = "YOUR_STAGING_BUCKET_NAME" # Cuenta de servicio del agente $SA_NAME = "YOUR_SERVICE_ACCOUNT_NAME" $SA_EMAIL = "$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com" # Ruta del bucket para staging $STAGING_BUCKET = "gs://$BUCKET_NAME" # Usuario de Google Cloud $USER_EMAIL = "YOUR_USER@YOUR_DOMAIN.com" 

Seleccionar el proyecto en GCP y configurar ADC

Antes de comenzar con el despliegue de nuestro agente, debemos configurar el acceso al proyecto de Google Cloud que utilizaremos. Para ello, abrimos una terminal de PowerShell en Visual Studio Code y ejecutamos los siguientes comandos para verificar la instalación de Google Cloud CLI, iniciar sesión y establecer el proyecto de trabajo.

gcloud --version gcloud auth login gcloud config set project $PROJECT_ID gcloud auth application-default login gcloud auth application-default set-quota-project $PROJECT_ID 

Durante este proceso utilizaremos Application Default Credentials (ADC), un mecanismo de autenticación de Google Cloud que permite a las aplicaciones y bibliotecas de Python obtener credenciales automáticamente para acceder a sus servicios.

Es importante distinguir los dos inicios de sesión: gcloud auth login autentica Google Cloud CLI, mientras que gcloud auth application-default login configura las credenciales ADC que utilizará nuestro script de despliegue. Finalmente, establecer el proyecto de cuota permite asociar el consumo de las APIs al proyecto seleccionado y evitar advertencias relacionadas con credenciales de usuario sin un proyecto de cuota, siempre que dispongamos de los permisos necesarios.

Habilitar APIs

Una vez configurado el acceso a nuestro proyecto de Google Cloud, el siguiente paso será habilitar las APIs necesarias para desplegar y ejecutar el agente en Agent Runtime, así como para integrarlo posteriormente con Gemini Enterprise. Estas APIs permitirán utilizar los servicios de inteligencia artificial, almacenamiento, autenticación y acceso a los recursos empresariales que forman parte de nuestra solución.

Desde PowerShell ejecutamos:

gcloud services enable ` aiplatform.googleapis.com ` storage.googleapis.com ` cloudresourcemanager.googleapis.com ` iam.googleapis.com ` iamcredentials.googleapis.com ` drive.googleapis.com ` discoveryengine.googleapis.com ` logging.googleapis.com ` --project=$PROJECT_ID 

Con este comando habilitamos los servicios necesarios para utilizar Vertex AI y Agent Runtime, gestionar los artefactos de despliegue en Cloud Storage, administrar las identidades y permisos mediante IAM, consultar documentos de Google Drive e integrar nuestro agente con Gemini Enterprise. También habilitamos Cloud Logging para facilitar la revisión de los registros de ejecución.

Es importante tener en cuenta que habilitar estas APIs no concede automáticamente permisos de acceso. Estos deberán configurarse posteriormente mediante los roles IAM correspondientes.

Crear el bucket de staging en Cloud Storage

El siguiente paso será crear un bucket en Google Cloud Storage, que utilizaremos como espacio de almacenamiento temporal durante el despliegue de nuestro agente en Agent Runtime. Este recurso permitirá almacenar los paquetes de Python y los artefactos necesarios para preparar y desplegar nuestro agente en Google Cloud.

gcloud storage buckets create $STAGING_BUCKET ` --project=$PROJECT_ID ` --location=$REGION ` --uniform-bucket-level-access 

En este ejemplo utilizaremos la región europe-west1 y habilitaremos el acceso uniforme al bucket, que permite administrar los permisos de acceso mediante IAM. Debemos reemplazar el nombre de ejemplo del bucket por un nombre único y el identificador del proyecto por el real.

Si el bucket ya existe, no será necesario crearlo nuevamente. Únicamente debemos comprobar que tenemos los permisos necesarios para utilizarlo durante el despliegue.

Crear y configurar la cuenta de servicio

Una vez preparado el almacenamiento, crearemos una cuenta de servicio (Service Account) que utilizará nuestro Asistente de Políticas Corporativas cuando se ejecute en Google Cloud Agent Runtime. Esta cuenta proporcionará una identidad propia al agente para acceder a los servicios autorizados de Google Cloud, sin depender de las credenciales personales del desarrollador.

Crear la cuenta de servicio

Desde PowerShell, ejecutamos el siguiente comando utilizando las variables que configuramos anteriormente:

gcloud iam service-accounts create $SA_NAME ` --display-name="Corporate Policies Agent Runtime" ` --project=$PROJECT_ID 

Este comando creará la cuenta de servicio que utilizaremos durante la ejecución del agente. Su dirección de correo electrónico tendrá el siguiente formato: YOUR_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com.

Una vez creada la cuenta de servicio, asignaremos el rol roles/aiplatform.user, que permitirá al agente utilizar los servicios de Vertex AI necesarios para interactuar con Gemini.

gcloud projects add-iam-policy-binding $PROJECT_ID ` --member="serviceAccount:$SA_EMAIL" ` --role="roles/aiplatform.user" 

Este rol se utiliza en nuestra demostración para facilitar la ejecución del agente. En entornos productivos conviene evaluar permisos más específicos, siguiendo el principio de mínimo privilegio.

Configurar el acceso a Google Drive

Además de interactuar con Gemini, nuestro agente necesita consultar los documentos almacenados en Google Drive. Para ello, debemos compartir la carpeta que contiene las políticas corporativas con el correo electrónico de la cuenta de servicio y asignarle el permiso de Lector (Viewer), siempre que las políticas de Google Workspace permitan este tipo de acceso.

Debemos recordar que los permisos de Google Drive se administran de forma independiente de los roles IAM de Google Cloud. Por tanto, asignar roles/aiplatform.user no concede automáticamente acceso a los documentos.

En el artículo anterior utilizamos un archivo JSON de credenciales para ejecutar el agente localmente. En esta nueva implementación aprovecharemos la identidad asociada a Agent Runtime y Application Default Credentials (ADC), evitando incluir claves privadas dentro del paquete de despliegue.

De esta manera, nuestro agente contará con una identidad dedicada para acceder a los servicios autorizados y ejecutarse de forma más segura en Google Cloud.

Configurar los permisos IAM del usuario de Google Cloud

Después de configurar la cuenta de servicio, debemos verificar que nuestro usuario de Google Cloud tenga los permisos necesarios para desplegar el agente y realizar las pruebas desde PowerShell.

Es importante diferenciar ambas identidades: mientras la cuenta de servicio se utilizará durante la ejecución del agente, nuestro usuario será el encargado de preparar el despliegue, crear el recurso en Agent Runtime y comprobar su funcionamiento.

Para este laboratorio utilizaremos los siguientes roles:

Rol IAM Descripción
roles/aiplatform.user Permite al usuario acceder a los servicios de Vertex AI y Agent Runtime, interactuar con los modelos Gemini y realizar consultas a los agentes desplegados.
roles/aiplatform.sessionUser Permite al usuario crear y administrar sesiones de conversación con los agentes desplegados en Agent Runtime.

Desde PowerShell, ejecutamos:

gcloud projects add-iam-policy-binding $PROJECT_ID ` --member="user:$USER_EMAIL" ` --role="roles/aiplatform.user" 
gcloud projects add-iam-policy-binding $PROJECT_ID ` --member="user:$USER_EMAIL" ` --role="roles/aiplatform.sessionUser" 

Estructura del proyecto y archivos específicos del despliegue

Antes de continuar con el despliegue en Google Cloud Agent Runtime, revisaremos brevemente la estructura de nuestro proyecto para identificar los archivos que utilizaremos en esta nueva etapa. Como el agente y sus componentes principales ya fueron desarrollados en el artículo anterior, no será necesario modificar su arquitectura ni volver a implementar sus funcionalidades.

Nos centraremos en los archivos responsables de preparar el paquete de Python, desplegar el agente y comprobar su funcionamiento una vez que esté ejecutándose en la nube.

Para facilitar la comprensión del proceso, a continuación mostramos una versión simplificada de la estructura del repositorio, destacando los archivos relacionados con el despliegue y las pruebas.

google-adk-gemini-corporate-policies-agent/ ├── requirements.txt ├── sources_en/ │ ├── .env │ ├── corporate_agent/ # Código del agente ya desarrollado │ ├── pyproject.toml # Metadatos del paquete wheel │ ├── deployment/ │ │ ├── deploy_agent.py │ │ └── runtime_resource.txt # Se crea después del despliegue │ └── test/ │ └── test_runtime.py └── sources_es/ # Versión equivalente en español 
Archivo Descripción
sources_en/pyproject.toml Define el paquete instalable corporate-policies-agent y declara que debe incluir corporate_agent.
sources_en/deployment/deploy_agent.py Valida el entorno, crea el wheel, despliega AdkApp y guarda la ruta del recurso remoto.
sources_en/deployment/runtime_resource.txt Archivo de salida con la ruta completa del recurso creado.
sources_es/test/test_runtime.py Obtiene la referencia remota, se conecta a Agent Runtime y envía consultas de comprobación.
requirements.txt Conjunto de dependencias del proyecto; el script también establece las necesarias para el runtime.

Variables de entorno específicas de esta etapa

Una vez preparado nuestro proyecto, el siguiente paso será revisar las variables de entorno que utilizaremos para desplegar el agente en Google Cloud Agent Runtime y comprobar su funcionamiento. Estas configuraciones nos permitirán indicar en qué proyecto y región se ejecutará el agente, qué recursos utilizará y cómo se autenticará para acceder a los servicios de Google Cloud.

Como en el artículo anterior ya configuramos las variables necesarias para el desarrollo local, en esta ocasión nos centraremos únicamente en aquellas relacionadas con el despliegue y las pruebas en la nube.

Variable Descripción
GOOGLE_CLOUD_PROJECT Identifica el proyecto de Google Cloud donde desplegaremos nuestro agente.
AGENT_RUNTIME_LOCATION Define la región de Google Cloud donde se ejecutará el agente. Para esta demostración utilizaremos europe-west1.
AGENT_RUNTIME_STAGING_BUCKET Indica el bucket de Cloud Storage que utilizaremos para almacenar temporalmente los archivos necesarios durante el despliegue. Su formato es gs://YOUR_STAGING_BUCKET.
AGENT_RUNTIME_SERVICE_ACCOUNT Contiene el correo electrónico de la cuenta de servicio que utilizará nuestro agente para acceder a los recursos autorizados de Google Cloud.
GOOGLE_GENAI_USE_VERTEXAI Permite indicar que nuestro agente utilizará Vertex AI para conectarse con Gemini. Durante la ejecución en Agent Runtime estableceremos su valor en TRUE.
GEMINI_MODEL Define el modelo Gemini que utilizará nuestro agente para procesar las consultas y generar respuestas. En nuestro proyecto se configura gemini-3.5-flash-lite como valor predeterminado, siempre que esté disponible para el proyecto.
GEMINI_VERTEX_LOCATION Especifica la ubicación desde la que se realizarán las consultas al modelo Gemini. En nuestro ejemplo utilizaremos global, que puede ser diferente de la región donde está desplegado Agent Runtime.
DRIVE_AUTH_MODE Define cómo se autenticará el agente para consultar Google Drive. Utilizaremos adc para aprovechar la identidad del entorno de ejecución, sin necesidad de incorporar un archivo JSON de credenciales.
AGENT_RUNTIME_RESOURCE Permite indicar el identificador del agente desplegado para realizar las pruebas remotas. Es opcional, ya que test_runtime.py también puede obtenerlo desde deployment/runtime_resource.txt.

Por otra parte, mantendremos las variables GOOGLE_DRIVE_FOLDER_ID y RAG_REFRESH_INTERVAL_SECONDS, que ya configuramos en el artículo anterior. La primera identifica la carpeta de Google Drive donde se encuentran nuestras políticas corporativas, mientras que la segunda establece el intervalo de actualización del índice RAG utilizado por el agente.

Empaquetado del agente mediante pyproject.toml

Antes de desplegar nuestro Asistente de Políticas Corporativas en Google Cloud Agent Runtime, necesitamos preparar su código para que pueda instalarse y ejecutarse correctamente en la nube. Para ello, utilizaremos un paquete Wheel (.whl), un formato de distribución de Python que permite agrupar el código de una aplicación y sus metadatos en un archivo instalable.

Los paquetes Wheel facilitan la distribución e instalación de aplicaciones Python, ya que contienen los archivos necesarios para que el entorno de destino pueda reconocer y utilizar sus módulos. En nuestro proyecto, este mecanismo nos permitirá trasladar el código de corporate_agent a Agent Runtime y asegurar que sus componentes puedan importarse correctamente durante la ejecución del agente.

Para generar el paquete Wheel utilizaremos el archivo pyproject.toml, ubicado en las carpetas sources_en/ y sources_es/, que contiene la configuración necesaria para construir y distribuir nuestro agente como un paquete de Python.

Este archivo define setuptools como herramienta de construcción, establece el nombre del paquete corporate-policies-agent e indica que debe incluirse el módulo corporate_agent, donde se encuentran los archivos principales de nuestra solución, como __init__.py, agent.py y drive_rag.py.

De esta manera, Python podrá reconocer e instalar nuestro agente en el entorno remoto sin necesidad de copiar manualmente sus archivos ni modificar las importaciones que implementamos anteriormente.

Preparar las herramientas de empaquetado

Antes de iniciar el despliegue, comprobaremos que nuestro entorno virtual dispone de las herramientas necesarias para construir el paquete Wheel.

Desde la terminal PowerShell de Visual Studio Code, ejecutamos:

cd C:\Projects\google-adk-gemini-corporate-policies-agent .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade setuptools wheel python -m pip check 

Con estos comandos activamos nuestro entorno virtual, instalamos o actualizamos las herramientas de empaquetado y verificamos que no existan conflictos entre las dependencias instaladas.

Generación del paquete Wheel durante el despliegue

En nuestro proyecto no será necesario generar manualmente el archivo Wheel, ya que esta tarea está incorporada en deployment/deploy_agent.py, que explicaremos en el siguiente apartado.

Durante su ejecución, el script construye temporalmente el paquete .whl, comprueba que incluya los archivos principales del agente y lo incorpora a las dependencias que se instalarán en Agent Runtime.

Este procedimiento también facilita la compatibilidad entre nuestro entorno de desarrollo en Windows y el entorno Linux utilizado por Agent Runtime, evitando depender de rutas absolutas locales que no existirán en la nube.

Con este mecanismo tendremos el código de nuestro agente preparado para instalarse en Agent Runtime, manteniendo su estructura original y facilitando su despliegue sin necesidad de desarrollar nuevamente los componentes que ya implementamos en el artículo anterior.

Desplegar en Google Cloud Agent Runtime

Una vez preparados los recursos de Google Cloud y configurado el empaquetado de nuestro agente, estamos listos para desplegarlo en Agent Runtime. Para ello, utilizaremos el archivo deploy_agent.py, que se encargará de realizar las verificaciones necesarias, preparar el código y sus dependencias, y crear el agente en el entorno administrado de Google Cloud.

Estructura y funcionamiento de deploy_agent.py

Este archivo se encuentra en sources_en/deployment/deploy_agent.py (versión en inglés) o sources_es/deployment/deploy_agent.py (versión en español) y está organizado en nueve bloques principales que explicaremos a continuación.

Bloque Descripción
1. Importaciones y variables de entorno del proyecto Se importan las bibliotecas necesarias para realizar el despliegue y se cargan las variables de configuración desde el archivo .env. También se identifican las variables reservadas que Agent Runtime administra automáticamente y que no debemos enviar como parte de la configuración del agente remoto.
2. Lectura y validación de la configuración Comprueba que disponemos de la información necesaria para el despliegue, como el identificador del proyecto, el bucket de staging, la cuenta de servicio y la carpeta de Google Drive. Estas validaciones permiten detectar configuraciones incompletas antes de crear recursos en la nube.
3. Preparación del entorno de autenticación Mediante prepare_deployment_environment(), configuramos el uso de Vertex AI y preparamos el entorno para autenticarnos mediante ADC. También evitamos que se utilice accidentalmente una API Key o credenciales JSON locales.
4. Verificación de credenciales y acceso a Cloud Storage verify_deployment_credentials() comprueba que contamos con credenciales ADC válidas y verifica el acceso al bucket de staging.
5. Configuración de las variables del agente remoto build_runtime_env() prepara los parámetros del modelo Gemini, la autenticación mediante ADC, la ubicación de los documentos de Drive y el intervalo de actualización del índice RAG.
6. Generación del paquete Wheel build_agent_wheel() construye el paquete instalable del agente, verifica que incluya los archivos principales y prepara sus rutas para el entorno remoto.
7. Creación del agente en Agent Runtime Mediante AdkApp preparamos el agente ADK y con client.agent_engines.create() creamos el recurso administrado con dependencias, wheel, bucket, cuenta de servicio y variables de entorno.
8. Registro del identificador del agente desplegado El script obtiene el identificador completo y lo guarda en deployment/runtime_resource.txt, necesario para las pruebas y el registro posterior en Gemini Enterprise.
9. Punto de entrada del despliegue Ejecuta main() cuando iniciamos el archivo como módulo de Python y coordina las fases anteriores.

Ejecutar el despliegue del agente

Una vez comprendido el funcionamiento de deploy_agent.py, podemos comenzar el despliegue. Para ello, abrimos la terminal PowerShell de Visual Studio Code, nos ubicamos en la carpeta raíz del proyecto y comprobamos que el entorno virtual esté activo.

Para la versión en inglés:

$env:PYTHONPATH = "$PWD\sources_en" python -m sources_en.deployment.deploy_agent 

Para la versión en español, utilizamos el paquete correspondiente:

$env:PYTHONPATH = "$PWD\sources_es" python -m sources_es.deployment.deploy_agent 

Este comando inicia el proceso de despliegue utilizando la configuración preparada anteriormente. Durante su ejecución, el script verificará las credenciales, comprobará el acceso al bucket de Cloud Storage, generará el paquete Wheel y enviará los componentes necesarios a Google Cloud Agent Runtime.

Si todo funciona correctamente, obtendremos un mensaje que confirma la creación del agente y muestra su identificador con un formato similar al siguiente:

Recurso creado: projects/YOUR_PROJECT_NUMBER/locations/europe-west1/reasoningEngines/RESOURCE_ID 

Este identificador corresponde al recurso creado en Agent Runtime y quedará almacenado en deployment/runtime_resource.txt, por lo que no tendremos que copiarlo manualmente para realizar las pruebas posteriores.

Es importante tener en cuenta que el despliegue puede generar costos en Google Cloud y que su finalización no garantiza por sí sola que el agente pueda responder correctamente. Por esta razón, antes de integrarlo con Gemini Enterprise, comprobaremos su funcionamiento mediante consultas remotas.

Despliegue del agente en Agent Runtime
Figura 3 – Despliegue del agente en Agent Runtime.

Validar el funcionamiento del agente con test_runtime.py

Después de desplegar nuestro Asistente de Políticas Corporativas, necesitamos comprobar que puede ejecutarse correctamente en Google Cloud y continuar consultando los documentos almacenados en Google Drive.

Para realizar estas verificaciones utilizaremos el archivo sources_en/test/test_runtime.py (versión en inglés) o sources_es/test/test_runtime.py (versión en español), que permite conectarnos al agente desplegado y enviarle diferentes preguntas desde la terminal de PowerShell.

A diferencia de las pruebas realizadas en el artículo anterior, ahora las consultas no se ejecutarán directamente sobre el agente local, sino sobre el recurso que hemos creado en Google Cloud Agent Runtime.

Ejecutar las pruebas del agente remoto

Desde la carpeta raíz del proyecto, con el entorno virtual activado, ejecutamos para la versión en inglés:

python -m sources_en.test.test_runtime 

Para la versión en español:

python -m sources_es.test.test_runtime 

El script recuperará automáticamente el identificador del agente desplegado y establecerá la conexión con Agent Runtime. Si la conexión se realiza correctamente, veremos una salida similar a la siguiente:

Proyecto: YOUR_PROJECT_ID Región: europe-west1 Agente: projects/YOUR_PROJECT_NUMBER/locations/europe-west1/reasoningEngines/RESOURCE_ID Conexión con Agent Runtime establecida. 

Posteriormente, el script enviará varias consultas de prueba, como:

  • Hola, ¿puedes presentarte y explicar qué haces?
  • ¿Cuál es la política corporativa de vacaciones?
  • ¿Cuántos días de vacaciones tienen los empleados?
  • ¿Cuál es la política corporativa de trabajo remoto?
  • ¿Qué políticas corporativas puedes consultar?

Durante estas pruebas debemos comprobar que el agente responde correctamente, utiliza la herramienta search_corporate_policies cuando necesita consultar información y genera respuestas basadas en los documentos disponibles en Google Drive.

También es importante revisar los eventos devueltos por Agent Runtime, ya que una conexión establecida no significa necesariamente que la consulta al modelo Gemini se haya completado correctamente.

Una vez completadas las pruebas y confirmado que nuestro agente funciona correctamente en la nube, tendremos preparada la integración con Gemini Enterprise, donde podremos registrarlo y ponerlo a disposición de los usuarios autorizados de la organización.

Registrar el agente en Gemini Enterprise

Una vez desplegado nuestro Asistente de Políticas Corporativas y comprobado su funcionamiento en Google Cloud Agent Runtime, el siguiente paso será integrarlo con Gemini Enterprise. Esta plataforma permitirá que los usuarios de la organización interactúen con nuestro agente mediante una interfaz conversacional, sin necesidad de utilizar herramientas de desarrollo como Streamlit, ADK Web o la consola de comandos.

Para ello, crearemos una aplicación en Gemini Enterprise y registraremos el agente que hemos desplegado previamente en Google Cloud, aprovechando su lógica, herramientas y conexión con los documentos almacenados en Google Drive.

Crear una aplicación en Gemini Enterprise

Para comenzar, crearemos una nueva aplicación en Gemini Enterprise que funcionará como punto de acceso a nuestro Asistente de Políticas Corporativas.

Desde Google Cloud Console, realizamos los siguientes pasos:

  1. Accedemos a Gemini Enterprise y seleccionamos nuestro proyecto de Google Cloud.
  2. En el menú de navegación, nos dirigimos a Apps (Aplicaciones).
  3. Hacemos clic en Create app (Crear aplicación) para iniciar la configuración.
  4. Introducimos el nombre de nuestra aplicación, por ejemplo, Corporate Policies Assistant, y completamos los campos solicitados.
  5. Seleccionamos la ubicación de la aplicación y las opciones disponibles según la edición de Gemini Enterprise que estemos utilizando. En este caso seleccionamos global.
  6. Revisamos la configuración y finalizamos seleccionando Create (Crear).

Durante la creación es importante verificar que nuestro proyecto dispone de los permisos y las licencias necesarias para utilizar Gemini Enterprise. También debemos tener en cuenta que la ubicación de esta aplicación puede ser diferente de la región donde desplegamos el agente en Agent Runtime, siempre que ambas configuraciones sean compatibles.

Creación de una aplicación en Gemini Enterprise
Figura 4 – Creación de una aplicación en Gemini Enterprise.

Una vez creada, tendremos disponible nuestra aplicación empresarial, en la que podremos incorporar el agente que desarrollamos con Google ADK.

Registrar el agente personalizado

Con nuestra aplicación creada, el siguiente paso será registrar el Asistente de Políticas Corporativas que desplegamos anteriormente en Google Cloud Agent Runtime.

Para ello, accedemos a la configuración de nuestra aplicación (Corporate Policies Assistant) en Gemini Enterprise y seguimos estos pasos:

  1. Abrimos la sección Agents (Agentes).
  2. Seleccionamos Custom agent via Agent Runtime para registrar nuestro agente personalizado.
  3. En el primer paso, correspondiente a las autorizaciones, mantenemos la configuración predeterminada para nuestra demostración.
  4. En el apartado de configuración, completamos los datos del agente.
  5. Introducimos el nombre, la descripción y el identificador del recurso desplegado, utilizando los siguientes valores como referencia:
Campo Valor de ejemplo
Nombre Corporate Policies Assistant
Descripción An agent that consults internal policies—covering Human Resources, Finance, Legal, Security, and other areas—based on authorized documents stored in Google Drive.
Ruta del recurso projects/PROJECT_NUMBER/locations/europe-west1/reasoningEngines/RESOURCE_ID
  1. Revisamos la configuración y confirmamos el registro del agente.

La descripción permite identificar la finalidad del agente y el tipo de consultas que puede atender. Por su parte, la ruta del recurso establece la conexión con el agente desplegado en Agent Runtime. Este identificador es el mismo que obtuvimos durante el despliegue y que quedó almacenado en deployment/runtime_resource.txt.

Agente registrado en Gemini Enterprise
Figura 5 – Registro del agente en Gemini Enterprise.

Una vez registrado, configuraremos su disponibilidad para que los usuarios o grupos autorizados puedan utilizarlo desde Gemini Enterprise.

Es importante comprobar que la aplicación cuenta con los permisos necesarios para invocar el agente. Si Gemini Enterprise y Agent Runtime se encuentran en proyectos diferentes de Google Cloud, también tendremos que configurar los permisos de acceso entre ambos proyectos.

Validar el funcionamiento del agente en Gemini Enterprise

Una vez completado el registro, podremos acceder a nuestra aplicación de Gemini Enterprise y comenzar a interactuar con el Asistente de Políticas Corporativas desde su interfaz conversacional.

Para comprobar que la integración funciona correctamente, realizaremos algunas de las preguntas que utilizamos anteriormente durante las pruebas desde PowerShell, como consultar los días de vacaciones, las condiciones de trabajo remoto o los procedimientos de reembolso.

Durante estas pruebas debemos verificar que el agente responde de manera coherente, recupera información de los documentos almacenados en Google Drive y proporciona referencias a las fuentes consultadas cuando estas se encuentran disponibles.

También es importante comprobar que los usuarios autorizados pueden acceder al agente y que la información proporcionada corresponde a las políticas corporativas disponibles.

Debemos tener en cuenta que, en nuestra implementación, el agente consulta Google Drive utilizando una cuenta de servicio. Por tanto, los permisos individuales de los empleados sobre los documentos no se aplican automáticamente. Si posteriormente queremos utilizar información confidencial o restringida por áreas, será necesario incorporar mecanismos adicionales de autorización y control de acceso.

Con estas validaciones habremos completado la integración de nuestro Asistente de Políticas Corporativas con Gemini Enterprise, permitiendo que el agente desarrollado con Google ADK pueda utilizarse desde una plataforma empresarial, mientras continúa ejecutándose de forma administrada en Google Cloud Agent Runtime.

Source:https://dev.to/johnbulla/como-desplegar-un-agente-de-ia-con-google-adk-en-agent-runtime-y-registrarlo-en-gemini-enterprise-1j9m