Cómo construir un agente de IA con Google ADK

John BullaFollow

💼 Sr. Cloud Solutions Architect - Cloud, Data & AI | Pre-Sales Architect | Cloud Evangelist 🏆 Google Developer Expert | AWS Community Builder | Alibaba Cloud MVP | Ex-Microsoft MVP

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

Introducción

La inteligencia artificial está atravesando una nueva etapa de evolución. Durante los últimos años, los modelos de inteligencia artificial generativa han transformado nuestra forma de crear contenido, desarrollar software y acceder a la información. Sin embargo, las necesidades de las organizaciones van más allá de obtener respuestas a partir de un prompt: también requieren aplicaciones capaces de consultar sistemas empresariales, utilizar herramientas y ejecutar pasos orientados a resolver una necesidad concreta. Este avance impulsa la inteligencia artificial agéntica, en la que un modelo de lenguaje se integra con instrucciones, herramientas y fuentes de información para actuar dentro de un flujo de trabajo.

En este contexto, Google desarrolló Google Agent Development Kit (Google ADK) que es un framework de código abierto, orientado al desarrollo de agentes de IA mediante código. Ofrece componentes para definir agentes y sus instrucciones, integrar modelos como Gemini, incorporar herramientas y funciones, gestionar sesiones y coordinar flujos que pueden evolucionar desde un agente individual hasta sistemas multiagente. Su valor no reside únicamente en generar respuestas, sino en proporcionar una estructura para construir soluciones extensibles, observables y comprobables.

En artículos anteriores realicé una introducción al desarrollo de agentes de IA donde comenté la evolución desde la IA generativa hacia la IA agéntica, qué caracteriza a un agente y por qué Google ADK resulta útil para su desarrollo. Por otra parte, también se introdujo a la arquitectura y componentes de Google ADK que sirve como lectura complementaria para profundizar en el diseño y los elementos que conforman este tipo de soluciones.

En este nuevo artículo damos el siguiente paso: pasamos de los conceptos y la arquitectura a una implementación práctica de un agente de IA con Google ADK.

Objetivo de la solución

En esta guía vamos a desarrollar un agente de inteligencia artificial que funcionará como un Asistente de Políticas Corporativas, capaz de responder preguntas sobre documentos internos de Recursos Humanos, Finanzas, Tecnología, Seguridad, Legal, Compras, Operaciones y Sostenibilidad, entre otras áreas.

Imaginemos que un empleado necesita saber cuántos días de vacaciones le corresponden, cómo solicitar un reembolso o qué establece la política de reciclaje de su empresa. En lugar de buscar manualmente entre diferentes documentos, podrá realizar sus preguntas en lenguaje natural y obtener respuestas claras y contextualizadas. Para ello, nuestro agente consultará las políticas que se encuentran en documentos almacenados en Google Drive, recuperará la información relevante y generará respuestas respaldadas por sus fuentes originales.

Para implementar esta solución utilizaremos Google ADK, como framework para desarrollar y ejecutar el agente; Gemini, como modelo de lenguaje; Google Drive, como repositorio documental; y Streamlit, para construir una interfaz web tipo chatbot con Python. También incorporaremos una estrategia RAG basada en búsquedas léxicas, utilizando un índice en memoria y sin necesidad de una base de datos vectorial. Esto nos permitirá comprender de forma sencilla cómo interactúan los diferentes componentes y cómo el agente transforma una consulta en una respuesta fundamentada.

A lo largo del ejercicio prepararemos nuestro entorno de desarrollo con Python, PowerShell en Visual Studio Code, configuraremos el acceso a Google Drive, implementaremos las herramientas de búsqueda y definiremos nuestro agente con Google ADK. Finalmente, construiremos una aplicación web como frontend que contendrá un chatbot en Streamlit y realizaremos pruebas para validar las respuestas, sus fuentes y el consumo estimado de tokens.

Este artículo constituye la primera parte de una serie práctica. En la segunda, llevaremos el mismo agente a Google Cloud Agent Runtime y lo integraremos con Gemini Enterprise, mostrando cómo evolucionar desde una aplicación local hacia una solución accesible desde una plataforma empresarial.

Arquitectura de la Solución

A continuación, se detalla la arquitectura planteada para esta solución y cómo funciona el flujo de trabajo.

La arquitectura de nuestro Asistente de Políticas Corporativas combina Streamlit, Google ADK, Gemini y Google Drive, permitiendo que los usuarios consulten documentos empresariales mediante una interfaz de conversación y reciban respuestas basadas en información real.

El proceso comienza con los documentos de políticas corporativas almacenados en Google Drive. Cuando iniciamos la aplicación, esta se conecta al repositorio, identifica los archivos disponibles y extrae su contenido. Posteriormente, divide los textos en fragmentos más pequeños y construye un índice RAG en memoria, que facilitará la búsqueda de información relevante. Este índice se mantiene disponible durante la ejecución de la aplicación y puede actualizarse manualmente cuando se incorporan nuevos documentos.

Una vez preparada la base de conocimiento, el usuario puede realizar una pregunta desde la aplicación web que contiene un chatbot desarrollado con Streamlit. La consulta se envía al agente construido con Google ADK, que utiliza el modelo Gemini para interpretar lo que el usuario necesita y determinar si debe utilizar alguna de sus herramientas.

Cuando la pregunta está relacionada con las políticas corporativas, el agente ejecuta la herramienta search_corporate_policies, encargada de buscar en el índice RAG los fragmentos que mejor coincidan con la consulta. A diferencia de una búsqueda tradicional por documentos completos, este mecanismo permite recuperar únicamente las secciones que podrían contener la respuesta.

Los fragmentos recuperados se devuelven al agente como información de contexto. A partir de ellos, Gemini genera una respuesta en lenguaje natural, procurando utilizar únicamente la información encontrada y proporcionando referencias a los documentos originales de Google Drive. Si no encuentra información suficiente, el agente debe indicarlo en lugar de inventar una respuesta.

Finalmente, la respuesta se presenta en Streamlit, donde el usuario puede continuar la conversación, realizar nuevas preguntas y consultar las fuentes utilizadas. La aplicación web también permite visualizar métricas como el consumo estimado de tokens y actualizar manualmente el índice cuando se añaden o modifican políticas.

De esta manera, conseguimos una arquitectura sencilla que permite comprender el funcionamiento de un agente de IA: desde la preparación e indexación de los documentos hasta la interpretación de una pregunta, la ejecución de herramientas y la generación de respuestas fundamentadas. Todo ello sin necesidad de incorporar una base de datos vectorial en esta primera implementación.

Requisitos previos

Para esta demostración trabajaremos sobre Windows, utilizando PowerShell para ejecutar los comandos y Visual Studio Code como entorno de desarrollo. También necesitaremos tener instalado Python 3.12, que utilizaremos para implementar el agente con Google ADK y construir la aplicación web con Streamlit.

En cuanto a los servicios de Google, necesitaremos acceso a Google AI Studio para obtener una API Key de Gemini, con cuota o créditos de facturación disponibles para realizar las consultas al modelo. También será necesario disponer de un proyecto en Google Cloud con la API de Google Drive habilitada y una carpeta donde almacenaremos las políticas corporativas que consultará nuestro agente.

Para acceder a estos documentos utilizaremos una cuenta de servicio de Google Cloud, a la que concederemos permisos de lectura sobre la carpeta correspondiente en Google Drive. En entornos empresariales, es importante revisar previamente las políticas de seguridad de la organización, especialmente las relacionadas con la creación y descarga de claves JSON. Para este laboratorio utilizaremos este mecanismo de autenticación únicamente en un entorno de pruebas autorizado.

Verificación de las herramientas

Una vez instaladas las herramientas, podemos comprobar que estén disponibles ejecutando los siguientes comandos desde PowerShell:

• Verificar la versión de Python:

py -3.12 --version

#OUTPUT
Python 3.12.10

• Verificar la instalación de Visual Studio Code:

code --version

#OUTPUT
1.145.2
x64

• Verificar la instalación de Google Cloud CLI:

gcloud --version

#OUTPUT
Google Cloud SDK 592.0.0

El último comando requiere tener instalado Google Cloud CLI, que utilizaremos principalmente en la segunda parte de esta serie, cuando despleguemos nuestro agente en Google Cloud Agent Runtime y lo integremos con Gemini Enterprise.

Para esta primera implementación local con Google ADK y Streamlit, será suficiente disponer de la API Key de Gemini y de una cuenta de servicio autorizada para consultar los documentos de Google Drive.

Con estos requisitos preparados, podremos continuar con la creación del entorno virtual de Python y la instalación de las dependencias necesarias para desarrollar nuestro asistente.

Organización y estructura del código fuente de la solución

En nuestro ejemplo, organizaremos el código en carpetas independientes para la definición del agente, la integración con Google Drive, las políticas corporativas, las pruebas y los scripts de despliegue.

Antes de comenzar con la implementación de nuestro agente, vamos a conocer cómo está organizado el proyecto. Mantener una estructura clara nos permitirá separar las responsabilidades de cada componente, facilitar su mantenimiento y reutilizar el código cuando avancemos hacia el despliegue en Google Cloud.

Para esta demostración, hemos organizado el código fuente en un único repositorio que contiene dos versiones del Asistente de Políticas Corporativas: una en inglés (sources_en) y otra en español (sources_es). Ambas mantienen la misma arquitectura y funcionalidades, pero cuentan con sus propios archivos Python, instrucciones del agente, ejemplos de políticas corporativas y configuración de entorno. De esta manera, podremos ejecutar y probar cada versión de forma independiente.

Estructura del proyecto

Para simplificar la explicación, mostraremos únicamente la estructura interna de sources_en, ya que sources_es utiliza la misma organización, con los contenidos correspondientes al idioma español.

google-adk-gemini-corporate-policies-agent/
│
├── sources_es/ # Versión en español
│ └── ... # Misma estructura que sources_en
│
├── sources_en/ # Versión en inglés
│ ├── .streamlit/
│ │ └── config.toml
│ │
│ ├── corporate_agent/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ └── drive_rag.py
│ │
│ ├── corporate_policies/
│ │ └── *.txt
│ │
│ ├── credentials/
│ │ └── .gitkeep
│ │
│ ├── deployment/
│ │ ├── __init__.py
│ │ └── deploy_agent.py
│ │
│ ├── prompts/
│ │ └── *.txt
│ │
│ ├── test/
│ │ ├── __init__.py
│ │ ├── test_drive.py
│ │ ├── test_gemini.py
│ │ └── test_runtime.py
│ │
│ ├── __init__.py
│ ├── .env
│ ├── app.py
│ └── pyproject.toml
│
├── .gitignore
├── README.md
├── README_ES.md
└── requirements.txt

Descripción de los componentes

A continuación, describimos brevemente la función de las principales carpetas y archivos que componen ambas versiones de nuestra solución.

Esta separación nos permitirá trabajar inicialmente con Google ADK y Streamlit en nuestro entorno local, manteniendo los componentes necesarios para desplegar posteriormente el mismo agente en Google Cloud Agent Runtime e integrarlo con Gemini Enterprise, sin tener que desarrollar una solución completamente nueva.

Código fuente disponible en GitHub

El código fuente de ambas versiones se encuentra organizado en un único repositorio de GitHub, donde podrás consultar los archivos Python, descargar los ejemplos de políticas corporativas y seguir las instrucciones de instalación y ejecución.

Puedes descargar el proyecto desde la opción Code → Download ZIP de GitHub o clonarlo directamente mediante Git:

git clone https://github.com/johnbulla/google-adk-gemini-corporate-policies-agent.git

Una vez descargado, abre la carpeta del proyecto en Visual Studio Code y selecciona la versión que deseas ejecutar.

El repositorio incluye dos archivos de documentación: README.md, disponible en inglés de forma predeterminada, y README_ES.md, con las instrucciones en español.

Repositorio del proyecto: Corporate Policies Agent — GitHub

Crear entorno virtual en VS Code con PowerShell

Una vez que tenemos instaladas las herramientas necesarias y conocemos la estructura del proyecto, el siguiente paso será preparar nuestro entorno de desarrollo en Visual Studio Code (VS Code).

Para trabajar con Python utilizaremos un entorno virtual, que nos permitirá instalar y administrar las bibliotecas que necesita nuestra aplicación de forma independiente, sin afectar otras versiones de Python ni las dependencias de otros proyectos que tengamos en nuestro equipo.

En este ejercicio utilizaremos Python 3.12 y ejecutaremos los comandos desde la terminal integrada de VS Code, utilizando PowerShell.

Crear el entorno virtual de Python

Primero, abrimos la carpeta raíz de nuestro proyecto en Visual Studio Code y accedemos a la terminal desde el menú Terminal → New Terminal.

Desde esta ubicación ejecutamos:

python -m venv .venv

Este comando crea un entorno virtual llamado .venv dentro del proyecto. Allí se instalarán las bibliotecas necesarias para desarrollar nuestro agente, evitando conflictos con otros proyectos Python.

El nombre .venv es una convención habitual y permite que Visual Studio Code identifique fácilmente el entorno virtual.

Habilitar y activar el entorno virtual

En Windows, PowerShell puede restringir la ejecución de scripts por motivos de seguridad. Si encontramos esta restricción al intentar activar nuestro entorno, podemos habilitar temporalmente su ejecución mediante:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Este comando modifica la política de ejecución únicamente para la sesión actual de PowerShell, sin cambiar permanentemente la configuración del sistema. Debe utilizarse solo cuando sea necesario y esté permitido por las políticas de seguridad del equipo.

Posteriormente, activamos el entorno virtual:

.\.venv\Scripts\Activate.ps1

Cuando el entorno esté activo, veremos el prefijo (.venv) al inicio de la línea de comandos, indicando que las instalaciones y ejecuciones de Python utilizarán nuestro entorno virtual.

Por ejemplo:

(.venv) PS C:\Projects\Corporate Policies Agent\>

Actualizar las herramientas de instalación de Python

Antes de instalar las dependencias, es recomendable actualizar las herramientas que Python utiliza para administrar y construir paquetes.

Ejecutamos:

python -m pip install --upgrade pip setuptools wheel

Este comando actualiza tres herramientas:

• pip: administrador de paquetes utilizado para instalar las bibliotecas de Python.

• setuptools: herramienta que permite configurar y construir paquetes Python distribuibles.

• wheel: proporciona soporte para generar paquetes instalables en formato .whl, que utilizaremos posteriormente para desplegar nuestro agente en Google Cloud Agent Runtime.

Aunque pip es suficiente para instalar muchas de las bibliotecas del proyecto, setuptools y wheel serán especialmente útiles cuando preparemos el agente para su despliegue en la nube.

Instalar las dependencias del proyecto

Nuestro agente utilizará varias bibliotecas de Python para interactuar con Gemini, Google Drive, Google ADK y Streamlit. En lugar de instalarlas manualmente una por una, las agruparemos en un archivo llamado requirements.txt, ubicado en la raíz del proyecto.

Este archivo nos permite mantener una lista centralizada de dependencias y facilita que otras personas puedan reproducir el mismo entorno de desarrollo.

Para instalar todas las bibliotecas, ejecutamos:

python -m pip install -r requirements.txt

El comando lee el archivo requirements.txt e instala las dependencias declaradas junto con las bibliotecas adicionales que estas necesiten.

Contenido de requirements.txt

google-adk
google-genai
google-api-python-client
google-auth
google-auth-oauthlib
google-cloud-storage
python-dotenv
python-docx
pypdf
streamlit
pydantic
cloudpickle
# Dependencies for the environment running deployment scripts
google-cloud-aiplatform[agent_engines,adk]>=1.112.0

A continuación, explicamos brevemente para qué utilizaremos cada dependencia.

Como podemos observar, algunas dependencias están orientadas al desarrollo local de nuestro asistente, mientras que otras serán necesarias posteriormente para su despliegue en Google Cloud.

Aunque en este ejercicio utilizaremos un único archivo requirements.txt para simplificar la instalación, en proyectos empresariales es habitual separar las dependencias de desarrollo, pruebas y despliegue. También se recomienda fijar versiones específicas una vez validado el funcionamiento de la solución, para evitar cambios inesperados al actualizar bibliotecas.

Comprobar que las dependencias se instalaron correctamente

Una vez finalizada la instalación, podemos comprobar que no existan conflictos entre las dependencias mediante:

python -m pip check

Si todo está correcto, deberíamos obtener un mensaje similar a:

No broken requirements found.

También podemos verificar que Google ADK y Streamlit estén disponibles:

python -m pip show google-adk streamlit

Este comando mostrará información sobre las bibliotecas instaladas, como su versión y ubicación dentro del entorno virtual.

Finalmente, es recomendable seleccionar el intérprete del entorno virtual en Visual Studio Code. Para ello, utilizamos Ctrl + Shift + P, buscamos Python: Select Interpreter y seleccionamos el intérprete que se encuentra dentro de .venv.

Con esto tendremos preparado nuestro entorno de desarrollo para comenzar a implementar el Asistente de Políticas Corporativas con Google ADK, Gemini y Streamlit. En los siguientes apartados configuraremos las credenciales necesarias y estableceremos la conexión con Google Drive, que será nuestra fuente de conocimiento para las consultas del agente.

Configuración del entorno y variables de la aplicación

Una vez preparado nuestro entorno virtual e instaladas las dependencias de Python, el siguiente paso será configurar las variables que necesita la aplicación para conectarse a los diferentes servicios de Google y definir algunos parámetros de funcionamiento del agente.

Para ello utilizaremos un archivo llamado .env, ubicado en la raíz del proyecto. Este archivo nos permite centralizar información como las credenciales de acceso, el modelo Gemini que utilizaremos, la ubicación de los documentos en Google Drive y los parámetros de recuperación de información del agente.

Una de sus principales ventajas es que podemos modificar estas configuraciones sin necesidad de cambiar directamente el código Python. Además, nos permite mantener separados los datos sensibles de la lógica de la aplicación, facilitando su mantenimiento y configuración en diferentes entornos.

En nuestro proyecto utilizaremos la biblioteca python-dotenv, instalada previamente, para cargar estas variables desde Python.

Nota de seguridad: En esta demostración utilizaremos algunas credenciales, como la API Key de Gemini y el archivo JSON de una cuenta de servicio, configuradas localmente para simplificar el desarrollo y facilitar la comprensión del ejercicio. Sin embargo, no es una buena práctica incluir claves, contraseñas o secretos directamente en el código fuente (hardcoding), ni almacenarlos en repositorios públicos.

En un entorno empresarial o de producción, se recomienda utilizar soluciones especializadas de gestión de secretos, como Google Cloud Secret Manager o HashiCorp Vault, que permitan almacenar las credenciales de forma segura, controlar su acceso y gestionar su ciclo de vida, incluyendo la generación, rotación y revocación. Siempre que sea posible, también es preferible utilizar identidades administradas y credenciales temporales en lugar de claves estáticas.

La configuración presentada en este artículo tiene fines exclusivamente educativos y de demostración, por lo que debe adaptarse a las políticas y los requisitos de seguridad de cada organización antes de utilizarse en un entorno productivo.

Como podemos observar, hemos dividido el archivo en cuatro grupos para facilitar su comprensión y administración.

Configuración de Gemini

En este primer bloque definimos cómo se conectará nuestro agente con Gemini y qué modelo utilizaremos para procesar las consultas.

Configuración de Google Drive

En este bloque configuramos el acceso a Google Drive, donde estarán almacenados los documentos que utilizará nuestro agente como base de conocimiento.

Por ejemplo, si tenemos una carpeta de Google Drive con una dirección similar a:

https://drive.google.com/drive/folders/1ABCdefGhijKlmNopQRstUv

El identificador que debemos configurar corresponde a la última parte de la dirección:

GOOGLE_DRIVE_FOLDER_ID=XXXxxxXXXxxxXXXXxxx

También debemos asegurarnos de que la carpeta esté compartida con la cuenta de servicio utilizada por nuestra aplicación, con los permisos necesarios para consultar los documentos.

Configuración de Google Cloud Agent Runtime

Aunque inicialmente ejecutaremos el agente de forma local con Streamlit, dejaremos preparadas algunas variables que utilizaremos en la segunda parte de esta serie, cuando despleguemos el agente en Google Cloud Agent Runtime y lo integremos con Gemini Enterprise.

Estas variables no son necesarias para comenzar a utilizar Streamlit con Gemini API, pero nos permitirán reutilizar el mismo proyecto cuando avancemos hacia su publicación en Gemini Enterprise.

Configuración de RAG y límites de procesamiento

En este último bloque definimos algunos parámetros que controlan cómo se recupera la información de los documentos, la cantidad de contenido que se procesa y el tiempo máximo de ejecución de las consultas.

Estos valores son adecuados como punto de partida para nuestro laboratorio y pueden ajustarse según el tamaño de los documentos, la cantidad de políticas y el comportamiento esperado de la aplicación.

En el caso de Streamlit, mantendremos un botón para actualizar manualmente el índice de documentos. Para Agent Runtime, utilizaremos el intervalo de actualización configurado en RAG_REFRESH_INTERVAL_SECONDS, que se comprobará cuando el agente vuelva a consultar su herramienta de búsqueda.

Configuración de costes estimados de Gemini

Finalmente, incorporamos dos variables opcionales que utilizaremos para calcular una estimación del consumo económico de las consultas desde el dashboard de Streamlit.

Estos valores permiten mostrar una estimación del coste de las interacciones con el modelo, pero no representan la facturación real de Google. Las tarifas pueden cambiar dependiendo del modelo, la modalidad de servicio y las condiciones comerciales aplicables, por lo que conviene revisar los precios oficiales antes de utilizarlos.

Crear la API Key de Gemini

Para que nuestro agente pueda utilizar los modelos de Gemini, necesitaremos generar una API Key desde Google AI Studio. Para ello, accedemos a Google AI Studio e iniciamos sesión con nuestra cuenta de Google.

Una vez dentro, nos dirigimos a la sección API Keys, seleccionamos la opción para crear una nueva clave y elegimos el proyecto de Google Cloud al que queremos asociarla. Si todavía no contamos con un proyecto disponible, podremos crear uno o importar uno existente, según las opciones habilitadas en nuestra cuenta.

Una vez generada la clave, la copiamos y comprobamos que el proyecto disponga de la cuota o facturación necesaria para utilizar el modelo Gemini seleccionado.

Con nuestra API Key disponible, abrimos el archivo .env ubicado en la raíz del proyecto y reemplazamos el valor de ejemplo YOUR_GEMINI_API_KEY en la variable GOOGLE_API_KEY por la clave obtenida desde Google AI Studio.

Configuración de Google Drive y autenticación mediante una cuenta de servicio

Para que nuestro Asistente de Políticas Corporativas pueda consultar los documentos almacenados en Google Drive, necesitamos configurar un mecanismo de autenticación que permita a la aplicación acceder a los archivos de forma segura.

En este ejercicio utilizaremos una cuenta de servicio (Service Account) de Google Cloud, que representa una identidad utilizada por aplicaciones y servicios, en lugar de una cuenta de usuario convencional. De esta manera, nuestro agente podrá conectarse a Google Drive y recuperar las políticas corporativas sin que el usuario tenga que autenticarse manualmente cada vez que realice una consulta.

Para la demostración crearemos una cuenta de servicio específica, le concederemos acceso de lectura a la carpeta donde se encuentran los documentos y descargaremos un archivo JSON con sus credenciales, que utilizaremos desde nuestra aplicación Python.

Habilitar la API de Google Drive

Lo primero será habilitar la API que permitirá a nuestra aplicación consultar los documentos almacenados en Google Drive.

1. Accedemos a Google Cloud Console e iniciamos sesión.
2. Seleccionamos el proyecto de Google Cloud que utilizaremos para el ejercicio.
3. En el menú lateral, nos dirigimos a APIs y servicios → Biblioteca.
4. Buscamos Google Drive API.
5. Seleccionamos la API y hacemos clic en Habilitar (Enable).

También podemos habilitarla desde PowerShell, utilizando Google Cloud CLI:

gcloud services enable drive.googleapis.com --project=YOUR_PROJECT_ID

Debemos reemplazar YOUR_PROJECT_ID por el identificador real de nuestro proyecto de Google Cloud.

Crear la cuenta de servicio

Una vez habilitada la API, crearemos la identidad que utilizará nuestro agente para acceder a los documentos.

Desde Google Cloud Console, seguimos estos pasos:

1. Accedemos a IAM y administración → Cuentas de servicio (Service Accounts).
2. Hacemos clic en Crear cuenta de servicio (Create Service Account).
3. Introducimos los siguientes valores de ejemplo:

El correo electrónico de la cuenta tendrá una estructura similar a:

drive-agent-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com

1. Seleccionamos Crear y continuar (Create and Continue).
2. En la asignación de roles del proyecto, podemos continuar sin añadir permisos IAM generales.
3. Finalizamos seleccionando Listo (Done).

Para este caso, no necesitamos asignar roles como Editor o Owner, ya que nuestro agente únicamente necesita consultar los documentos de una carpeta específica de Google Drive. El acceso a esos archivos se gestionará directamente desde los permisos de uso compartido de Drive.

Google Cloud permite crear cuentas de servicio sin asignarles inicialmente roles IAM sobre el proyecto.

También podemos crear la cuenta mediante PowerShell:

gcloud iam service-accounts create drive-agent-reader `
--display-name="Corporate Policies Drive Reader" `
--description="Read corporate policy documents from Google Drive" `
--project=YOUR_PROJECT_ID

Configurar los permisos de acceso a Google Drive

Después de crear la cuenta de servicio, debemos autorizarla para que pueda consultar la carpeta donde almacenaremos las políticas corporativas.

En nuestro ejemplo, tendremos una carpeta principal de Google Drive con los documentos de Recursos Humanos, Finanzas, Tecnología, Seguridad, Legal, Compras, Operaciones y Sostenibilidad.

Para conceder acceso:

1. Abrimos Google Drive.
2. Localizamos la carpeta principal que contiene las políticas corporativas.
3. Hacemos clic derecho sobre ella y seleccionamos Compartir (Share).
4. Introducimos el correo electrónico de la cuenta de servicio creada anteriormente.
5. Seleccionamos el permiso Lector (Viewer).
6. Confirmamos la configuración de uso compartido.

Por ejemplo:

Cuenta:
drive-agent-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
Permiso:
Lector (Viewer)

Con este permiso, la cuenta podrá consultar los documentos disponibles dentro de la carpeta y sus subcarpetas, siempre que los permisos se hereden correctamente y no existan restricciones adicionales. No es necesario conceder permisos de edición, ya que nuestro agente únicamente leerá información para responder preguntas.

Google Workspace permite compartir directamente archivos y carpetas con una cuenta de servicio mediante su dirección de correo electrónico, sin necesidad de concederle privilegios administrativos.

Generar el archivo de credenciales service-account.json

Una vez creada y autorizada la cuenta de servicio, necesitaremos obtener las credenciales que utilizará nuestra aplicación Python para autenticarse desde el entorno local.

Para ello, regresamos a Google Cloud Console y seguimos estos pasos:

1. Accedemos a IAM y administración → Cuentas de servicio.
2. Seleccionamos la cuenta de servicio drive-agent-reader.
3. Abrimos la pestaña Claves (Keys).
4. Hacemos clic en Agregar clave → Crear clave nueva (Add Key → Create New Key).
5. Seleccionamos el formato JSON.
6. Hacemos clic en Crear (Create).

Google Cloud descargará automáticamente un archivo JSON con las credenciales de la cuenta de servicio. Renombraremos el archivo descargado como: service-account.json

Este archivo contiene información como el identificador del proyecto, el correo electrónico de la cuenta de servicio y una clave privada utilizada durante la autenticación. Por esta razón, debemos tratarlo como una credencial sensible.

Y lo guardaremos dentro de la carpeta credentials de nuestro proyecto:

Corporate Policies Agent/
├── corporate_agent/
├── corporate_policies/
├── credentials/
│ └── service-account.json
├── app.py
├── .env
└── requirements.txt

Configurar las credenciales en el archivo .env

Con el archivo JSON almacenado en la carpeta credentials, configuraremos las variables de entorno que utilizará nuestra aplicación para conectarse a Google Drive.

Abrimos el archivo .env y completamos el bloque correspondiente:

# ============================================================
# 2. LOCAL GOOGLE DRIVE AUTHENTICATION
# ============================================================
DRIVE_AUTH_MODE=service_account_file
DRIVE_SERVICE_ACCOUNT_FILE=credentials/service-account.json
GOOGLE_DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID

Verificar la conexión con Google Drive

Antes de continuar con la implementación del agente, es recomendable comprobar que las credenciales funcionan y que tenemos acceso a los documentos.

Nuestro proyecto incluye un archivo de pruebas llamado test_drive.py, ubicado en la carpeta test, que permite validar esta conexión.

Desde la terminal PowerShell de Visual Studio Code, con el entorno virtual activado, ejecutamos:

python -m sources_en.test.test_drive

Esta prueba nos permitirá comprobar que la aplicación puede autenticarse y acceder a Google Drive. El resultado exacto dependerá de las verificaciones implementadas en el script.

OUTPUT
Google Drive connection successful
📁 Root folder: Corporate Policies
🆔 ID: YOUR_DRIVE_FOLDER_ID
📚 Files found:
-----------------------------------------------------------------
-----------------------------------------------------------------
✅ Total files found: 0
(.venv) PS C:\Projects\Corporate Policies Agent> python -m test.test_drive
✅ Google Drive connection successful
📁 Root folder: Corporate Policies
🆔 ID: YOUR_DRIVE_FOLDER_ID
📚 Files found:
-----------------------------------------------------------------
📄 en_legal_policies.txt
📄 en_it_policies.txt
📄 en_human_resources_policies.txt
📄 en_finance_policies.txt
-----------------------------------------------------------------
✅ Total files found: 4

Si aparece un error 403 Forbidden, deberemos revisar los permisos de la cuenta de servicio sobre la carpeta, la configuración de la API o los permisos del proyecto. Si aparece un error 404 Not Found, comprobaremos que el identificador de la carpeta sea correcto y que la cuenta tenga acceso a ella.

Consideraciones de seguridad

Para esta demostración estamos utilizando un archivo JSON de cuenta de servicio porque facilita la configuración de nuestro entorno local y permite comprender cómo se realiza la autenticación entre Python y Google Drive. Sin embargo, las claves JSON son credenciales de larga duración y no se recomiendan como mecanismo habitual para aplicaciones empresariales o entornos de producción.

En una implementación productiva es preferible utilizar identidades administradas, credenciales temporales y mecanismos de autenticación que eviten almacenar claves privadas en archivos locales. Google Cloud recomienda limitar el uso de claves exportables de cuentas de servicio y aplicar controles adecuados sobre su ciclo de vida.

Con esta configuración tendremos preparada la conexión entre nuestra aplicación y Google Drive, que funcionará como repositorio de conocimiento para el Asistente de Políticas Corporativas.

En los siguientes apartados utilizaremos estas credenciales para implementar la lectura de documentos, su fragmentación e indexación y la herramienta de búsqueda que nuestro agente ejecutará mediante Google ADK.

Implementación del sistema RAG para la consulta de documentos

Ahora que tenemos configurado el acceso a Google Drive, vamos a implementar el componente encargado de recuperar la información que utilizará nuestro agente para responder las preguntas de los usuarios.

Para ello, utilizaremos una estrategia RAG (Retrieval-Augmented Generation), que permite complementar las respuestas de Gemini con información obtenida de nuestros documentos corporativos.

En esta primera implementación construiremos un RAG léxico en memoria, sin utilizar una base de datos vectorial. El proceso consiste en consultar los documentos de Google Drive, extraer su contenido, dividirlo en fragmentos y construir un índice que permita localizar la información más relevante para cada pregunta.

Toda esta lógica estará implementada en el archivo corporate_agent/drive_rag.py, que hemos organizado en seis bloques principales.

Configuración de Google Drive y tipos MIME

# ============================================================
# 1. CONFIGURACIÓN DE GOOGLE DRIVE Y TIPOS MIME
# ============================================================

En este primer bloque definimos las configuraciones generales para trabajar con Google Drive, incluyendo el permiso de lectura (drive.readonly) y los formatos de archivo que podrá procesar nuestra aplicación.

Se admiten documentos de Google Docs, archivos TXT, Markdown, PDF y Word (DOCX). También se define una lista de palabras frecuentes (stopwords) que se excluirán durante las búsquedas para mejorar la relevancia de los resultados.

Tokenización y segmentación de texto

# ============================================================
# 2. TOKENIZACIÓN Y SEGMENTACIÓN DE TEXTO
# ============================================================

Este bloque prepara el contenido de los documentos para su posterior indexación y búsqueda. Contiene dos funciones:

• words(): convierte el texto en palabras, normaliza su escritura y elimina términos frecuentes que aportan poco valor a la búsqueda.

• split_chunks(): divide los documentos en fragmentos más pequeños, manteniendo cierto solapamiento entre ellos para evitar perder información relevante al separar el contenido.

La fragmentación permite recuperar únicamente las secciones relacionadas con una pregunta, en lugar de enviar documentos completos al modelo Gemini.

Descarga y conexión con Google Drive

# ============================================================
# 3. DESCARGA Y CONEXIÓN CON DRIVE
# ============================================================

En este apartado implementamos la conexión con Google Drive y la descarga de los documentos:

• get_drive_service(): establece la conexión utilizando las credenciales configuradas en .env. Admite tanto el archivo JSON de la cuenta de servicio para el entorno local como la autenticación ADC que utilizaremos posteriormente en Agent Runtime.

• download_bytes(): descarga los archivos por partes y comprueba que no superen el tamaño máximo permitido.

De esta manera, centralizamos el acceso a Google Drive y controlamos la cantidad de información que puede descargar nuestra aplicación.

Recorrido de carpetas y paginación

# ============================================================
# 4. RECORRIDO DE CARPETAS Y PAGINACIÓN
# ============================================================

La función list_files() se encarga de localizar los documentos disponibles dentro de la carpeta de Google Drive configurada en nuestro proyecto.

También recorre sus subcarpetas, utiliza paginación para consultar los resultados y selecciona únicamente los formatos admitidos, respetando el límite de archivos establecido mediante MAX_DRIVE_FILES.

Extracción de texto por formato

# ============================================================
# 5. EXTRACCIÓN DE TEXTO POR FORMATO
# ============================================================

Una vez identificados los documentos, necesitamos obtener su contenido en un formato que podamos procesar.

La función extract_text() realiza esta tarea según el tipo de archivo: exporta Google Docs como texto, utiliza pypdf para los PDF, python-docx para documentos Word y decodifica directamente los archivos TXT y Markdown.

Es importante tener en cuenta que, en esta versión, los PDF escaneados que solo contienen imágenes no podrán procesarse correctamente, ya que necesitaríamos incorporar un mecanismo adicional de OCR.

Modelo de fragmentos e índice RAG

# ============================================================
# 6. MODELO DE FRAGMENTOS E ÍNDICE RAG
# ============================================================

Este último bloque contiene la lógica principal de indexación y recuperación de información.

La clase Chunk representa cada fragmento de texto y conserva información como el nombre del documento, su enlace en Google Drive y las palabras que contiene.

Por otra parte, la clase DriveKnowledgeBase administra nuestra base de conocimiento mediante tres métodos principales:

• __init__(): inicializa las estructuras donde se almacenarán los fragmentos, las estadísticas y las advertencias.

• refresh(): consulta los documentos de Google Drive, extrae su contenido y reconstruye el índice RAG en memoria.

• search(): recibe la pregunta del usuario, identifica los fragmentos más relevantes mediante una puntuación léxica basada en TF-IDF y devuelve los resultados junto con sus fuentes.

Los fragmentos recuperados serán utilizados posteriormente por el agente desarrollado con Google ADK, que los proporcionará a Gemini como contexto para generar una respuesta fundamentada.

Consideraciones importantes

Aunque esta implementación es suficiente para comprender el funcionamiento de RAG e integrarlo con nuestro agente, debemos tener presentes algunas características:

• Indexación en memoria: los documentos procesados no se almacenan en una base de datos persistente. Por tanto, será necesario reconstruir el índice cuando corresponda.

• Búsqueda léxica: la recuperación se basa en coincidencias de palabras y no en similitud semántica. Esto significa que algunas preguntas formuladas con sinónimos podrían no recuperar los fragmentos esperados.

• Límites de procesamiento: podemos controlar el número de documentos, su tamaño y la cantidad de fragmentos recuperados mediante las variables configuradas en .env.

• Seguridad documental: la aplicación puede consultar los documentos accesibles para su cuenta de servicio. Es importante utilizar una carpeta autorizada y evitar incluir información que no deba estar disponible para los usuarios del agente.

Para nuestro ejemplo, este enfoque nos permitirá comprender el proceso completo de recuperación de información sin añadir la complejidad de una base de datos vectorial o servicios adicionales.

Con el archivo drive_rag.py preparado, ya tendremos el componente encargado de consultar nuestra base de conocimiento. El siguiente paso será crear el agente con Google ADK e integrar esta funcionalidad mediante una herramienta que Gemini pueda utilizar durante la conversación.

Desarrollo y configuración del agente de IA con Google ADK

Una vez implementado nuestro sistema RAG, el siguiente paso será desarrollar el agente encargado de interpretar las preguntas de los usuarios, consultar las políticas corporativas y generar respuestas utilizando Gemini.

Para ello, utilizaremos Google Agent Development Kit (ADK), que nos permite definir el comportamiento del agente, integrar herramientas y gestionar la interacción con el modelo de lenguaje.

Toda esta lógica estará implementada en el archivo corporate_agent/agent.py, organizado en cinco bloques principales.

Configuración del proyecto

# ============================================================
# 1. CONFIGURACIÓN DEL PROYECTO
# ============================================================

En este primer bloque cargamos las variables de entorno definidas en .env y configuramos el modelo Gemini y los parámetros que utilizará nuestro agente.

La función create_agent_model() permite seleccionar el mecanismo de conexión con Gemini según el entorno de ejecución: mediante una API Key para nuestra aplicación local o utilizando Vertex AI cuando despleguemos el agente en Google Cloud.

También configuramos parámetros como RAG_TOP_K, que establece la cantidad máxima de fragmentos recuperados, y RAG_REFRESH_INTERVAL_SECONDS, que determina el intervalo de actualización del índice administrado por Agent Runtime.

Base de conocimiento

# ============================================================
# 2. BASE DE CONOCIMIENTO
# ============================================================

Este bloque administra el índice RAG que implementamos anteriormente en drive_rag.py, permitiendo reutilizar la información recuperada sin tener que consultar Google Drive continuamente.

Contiene tres funciones principales:

• set_knowledge_base(): permite que nuestra aplicación Streamlit proporcione al agente un índice RAG previamente cargado y administrado desde su propia interfaz.

• _cache_is_current(): comprueba si el índice almacenado en memoria sigue siendo válido o necesita actualizarse.

• get_knowledge_base(): obtiene el índice disponible y cuando corresponde, vuelve a consultar los documentos de Google Drive para reconstruirlo.

De esta manera, evitamos descargas innecesarias y mejoramos los tiempos de respuesta. En Streamlit la actualización se controla manualmente, mientras que en Agent Runtime puede realizarse automáticamente cuando llega una consulta y ha vencido el intervalo configurado.

Herramienta RAG para Google ADK

# ============================================================
# 3. HERRAMIENTA RAG PARA GOOGLE ADK
# ============================================================

En este apartado implementamos la función search_corporate_policies(), que será la herramienta que nuestro agente utilizará para consultar la información corporativa.

Cuando el usuario realiza una pregunta, esta función accede al índice RAG, recupera los fragmentos más relevantes y devuelve sus contenidos junto con el nombre y el enlace de los documentos originales.

También incorpora un mecanismo de manejo de errores para identificar problemas de conexión, permisos o acceso a Google Drive, evitando exponer información sensible durante la ejecución.

Control de consulta documental por turno

# ============================================================
# 4. CONTROL DE CONSULTA DOCUMENTAL POR TURNO
# ============================================================

Este bloque incorpora la función enforce_search_per_turn(), que utilizamos como un callback de Google ADK para controlar cuándo debe ejecutarse la herramienta de búsqueda. Su objetivo es asegurar que el agente realice una nueva consulta documental cada vez que el usuario envíe una pregunta, evitando responder únicamente con información recuperada en conversaciones anteriores.

Una vez ejecutada la función search_corporate_policies y obtenidos sus resultados, el agente puede continuar con la generación de la respuesta mediante Gemini.

Este comportamiento resulta especialmente útil cuando las políticas corporativas cambian y necesitamos consultar información actualizada.

Definición del agente con Google ADK

# ============================================================
# 5. DEFINICIÓN DEL AGENTE CON GOOGLE ADK
# ============================================================

Finalmente, definimos nuestro agente principal mediante root_agent = Agent(), que representa el componente central de la solución.

En esta configuración establecemos sus principales características:

• name: identifica al agente como corporate_policies_assistant.

• model: especifica el modelo Gemini que utilizará para interpretar las consultas y generar respuestas.

• description: describe brevemente su propósito dentro de la organización.

• instruction: contiene las instrucciones o prompt que determinan cómo debe comportarse el agente, incluyendo la consulta de documentos, la generación de respuestas fundamentadas y la incorporación de referencias.

• tools: registra la función search_corporate_policies como herramienta disponible para el agente.

• before_model_callback: incorpora el mecanismo que exige una nueva búsqueda documental al recibir una consulta del usuario.

Las instrucciones del agente son especialmente importantes, ya que establecen que las respuestas deben basarse en los documentos recuperados y que, cuando no exista información suficiente, el asistente debe indicarlo en lugar de inventar una respuesta. También limitan su comportamiento al ámbito de las políticas corporativas.

Consideraciones importantes

Con esta implementación, nuestro agente integra Google ADK, Gemini y el sistema RAG desarrollado anteriormente, permitiendo responder preguntas sobre las políticas almacenadas en Google Drive.

Es importante tener en cuenta que la calidad de las respuestas dependerá de la información disponible en los documentos y de los fragmentos recuperados durante la búsqueda. Por esta razón, se han incorporado instrucciones para utilizar las fuentes documentales y evitar respuestas sin respaldo.

Además, el diseño permite ejecutar el mismo agente tanto en nuestra aplicación local con Streamlit como posteriormente en Google Cloud Agent Runtime, cambiando principalmente el mecanismo de autenticación y la configuración del modelo.

Con nuestro agente definido, el siguiente paso será construir la interfaz web con Streamlit, desde donde los usuarios podrán realizar preguntas, consultar las respuestas y visualizar información sobre los documentos y el consumo de tokens.

Desarrollo de la interfaz web del agente con Streamlit

Una vez implementado nuestro agente con Google ADK y su integración con el sistema RAG, el siguiente paso será construir una interfaz web que permita a los usuarios interactuar con él de manera sencilla.

Para ello utilizaremos Streamlit, un framework de Python con el que podemos desarrollar aplicaciones web sin necesidad de trabajar directamente con HTML, JavaScript o frameworks frontend adicionales.

Toda la lógica de nuestra interfaz estará implementada en el archivo app.py que se encuentra en la raíz del proyecto y que se ha organizado en ocho bloques principales.

Variables de entorno y configuración del proyecto

# ============================================================
# 1. VARIABLES DE ENTORNO Y CONFIGURACIÓN DEL PROYECTO
# ============================================================

En este primer bloque cargamos las variables de entorno desde .env, importamos nuestro agente de Google ADK y configuramos los parámetros generales de Streamlit.

También definimos el tiempo máximo de respuesta del agente y los precios de referencia que utilizaremos para calcular el consumo estimado de tokens.

Estilos visuales del dashboard

# ============================================================
# 2. ESTILOS VISUALES DEL DASHBOARD (TEMA OSCURO)
# ============================================================

Este apartado define la apariencia visual de la aplicación, incluyendo colores, tipografía, tarjetas y componentes del dashboard.

La función render_dashboard_style() aplica los estilos personalizados mediante CSS, mientras que get_kb() carga y mantiene en memoria el índice RAG de los documentos disponibles en Google Drive.

Creación de sesiones y Runner de Google ADK

# ============================================================
# 3. CREACIÓN DE SESIONES Y RUNNER DE GOOGLE ADK
# ============================================================

Mediante la función init_runner(), inicializamos los componentes que permiten ejecutar nuestro agente y mantener el contexto de las conversaciones.

Para ello utilizamos Runner e InMemorySessionService de Google ADK, que se encargan de procesar las consultas y administrar las sesiones de conversación.

Medición de tokens, costes y ejecución del agente

# ============================================================
# 4. MEDICIÓN DE TOKENS, COSTES Y EJECUCIÓN DEL AGENTE
# ============================================================

Este bloque permite enviar las preguntas al agente, recibir sus respuestas y recopilar información sobre el consumo del modelo Gemini.

Sus principales funciones son:

• new_usage_metrics(): inicializa las métricas de consumo.

• collect_usage(): recopila la información de tokens disponible en los eventos de Google ADK.

• calculate_estimated_cost(): calcula el coste aproximado de las consultas.

• render_usage_metrics() y render_session_usage(): muestran las métricas de una consulta y de la sesión.

• ask_agent(): envía la pregunta al agente y recupera la respuesta generada.

También encontramos select_chat_page(), que facilita la navegación hacia el chatbot.

Pie de página y datos de versión

# ============================================================
# 5. PIE DE PÁGINA COMÚN Y DATOS DE VERSIÓN
# ============================================================

La función render_footer() incorpora un pie de página común que muestra información de la aplicación, los derechos de autor y su versión.

Página de introducción

# ============================================================
# 6. PÁGINA DE INTRODUCCIÓN (DISEÑO DASHBOARD)
# ============================================================

La función render_intro_page() construye la pantalla de bienvenida de nuestra aplicación.

En ella presentamos el objetivo del asistente, las tecnologías utilizadas y una breve explicación de cómo Google ADK, Gemini y Google Drive trabajan conjuntamente.

Página de chat, índice y herramientas de consulta

# ============================================================
# 7. PÁGINA DE CHAT, ÍNDICE Y HERRAMIENTAS DE CONSULTA
# ============================================================

Este bloque contiene la función render_chat_page(), encargada de construir la interfaz principal del chatbot.

Desde esta pantalla, los usuarios podrán realizar preguntas sobre las políticas corporativas, visualizar las respuestas y sus fuentes, consultar las métricas de consumo y actualizar manualmente los documentos indexados desde Google Drive.

Navegación principal y punto de entrada

# ============================================================
# 8. NAVEGACIÓN PRINCIPAL Y PUNTO DE ENTRADA
# ============================================================

Finalmente, la función main() controla la navegación entre las diferentes pantallas y coordina la ejecución de nuestra aplicación Streamlit. Este bloque también contiene el punto de entrada principal, desde donde se inicia la aplicación.

Configuración visual de Streamlit mediante config.toml

Además de los estilos personalizados definidos en app.py, utilizaremos el archivo .streamlit/config.toml para establecer la configuración general de nuestra aplicación Streamlit. Este archivo permite personalizar aspectos visuales como el tema, los colores principales, el fondo y la tipografía, manteniendo estas preferencias separadas del código Python. En nuestro proyecto utilizaremos una apariencia oscura (Dark Mode), que complementaremos con los estilos CSS definidos en la función render_dashboard_style(). De esta manera, podremos mantener una interfaz visual consistente y modificar su apariencia fácilmente sin afectar la lógica del agente ni su integración con Google ADK y Gemini.

Consideraciones finales

Con la implementación de app.py, completamos la integración de los principales componentes de nuestra solución: Streamlit como interfaz web*, Google ADK* para ejecutar el agente*, Gemini* para generar las respuestas y Google Drive como repositorio documental.

Además, incorporamos funcionalidades como la gestión de sesiones, la actualización manual del índice RAG y la visualización de métricas de consumo, que nos permitirán evaluar el comportamiento de nuestro asistente durante las pruebas.

Con esto, ya tendremos los componentes necesarios para ejecutar el Asistente de Políticas Corporativas en nuestro entorno local y comenzar a realizar las primeras consultas.

Ejecución y pruebas del agente en entorno local

Una vez desarrollados los componentes de nuestra solución, ya podemos poner en funcionamiento el Asistente de Políticas Corporativas y comprobar su comportamiento.

Para ello, realizaremos las pruebas de tres maneras: utilizando nuestra interfaz personalizada con Streamlit, desde la interfaz de desarrollo ADK Web y directamente desde la línea de comandos de Google ADK (CLI).

Ejecutar la aplicación con Streamlit

Streamlit será nuestra interfaz principal, ya que permite interactuar con el agente mediante un chatbot y visualizar información adicional, como los documentos indexados y las métricas de consumo.

Aunque ambas versiones se encuentran en el mismo repositorio, podemos ejecutarlas de forma independiente, utilizando el mismo entorno virtual de Python.

Para iniciar la versión en inglés, desde la raíz del proyecto ejecutamos:

python -m streamlit run .\sources_en\app.py

Para iniciar la versión en español:

python -m streamlit run .\sources_es\app.py

También podemos ejecutar ambas aplicaciones simultáneamente, utilizando los puertos 8501 y 8502, respectivamente. Cada versión utilizará su propia configuración .env, sus instrucciones y los documentos de Google Drive que tenga configurados.

Esta organización nos permitirá trabajar con dos versiones lingüísticas de una misma solución, manteniendo separados sus componentes y facilitando su evolución hacia Google Cloud Agent Runtime y Gemini Enterprise

Una vez iniciado el servidor, abrimos la siguiente dirección en nuestro navegador: http://localhost:8501

Desde la aplicación podremos realizar preguntas sobre las políticas corporativas, consultar las fuentes utilizadas y actualizar manualmente el índice de documentos almacenados en Google Drive.

Ejecutar el agente desde ADK Web

Google ADK incluye una interfaz web de desarrollo que permite interactuar directamente con nuestros agentes, revisar sus respuestas y observar la ejecución de sus herramientas. Desde la carpeta raíz del proyecto ejecutamos:

Para iniciar la versión en inglés, desde la raíz del proyecto ejecutamos:

adk web --port 8000 .\sources_en

Para iniciar la versión en español:

adk web --port 8001 .\sources_es

Posteriormente, abrimos: http://localhost:8000 o http://localhost:8001

En la interfaz seleccionamos nuestro agente corporate_agent y comenzamos a realizar consultas.

Esta modalidad es especialmente útil durante el desarrollo, porque permite inspeccionar la interacción con Gemini y comprobar cuándo el agente ejecuta la herramienta search_corporate_policies.

Ejecutar el agente desde la consola de comandos

También podemos interactuar con nuestro agente directamente desde PowerShell, sin utilizar una interfaz gráfica. Para ello ejecutamos:

Para iniciar la versión en inglés, desde la raíz del proyecto ejecutamos:

adk run .\sources_en\corporate_agent

Para iniciar la versión en español:

adk run .\sources_es\corporate_agent

Este comando inicia una sesión interactiva donde podremos escribir preguntas y recibir las respuestas directamente en la terminal.

Es una alternativa sencilla para realizar pruebas rápidas, comprobar el comportamiento del agente y detectar posibles errores durante el desarrollo.

Validar el funcionamiento del agente

Independientemente de la modalidad de ejecución, podemos realizar algunas preguntas relacionadas con los documentos que tenemos almacenados en Google Drive:

• ¿Cuántos días de vacaciones tienen los empleados al año?

• ¿Cuál es la política de trabajo remoto de la empresa?

• ¿Cómo puedo solicitar el reembolso de un gasto?

• ¿Qué establece la política de reciclaje y sostenibilidad?

Durante estas pruebas debemos comprobar que el agente consulta los documentos mediante search_corporate_policies, genera respuestas coherentes y proporciona referencias a las fuentes originales.

También es recomendable realizar alguna pregunta cuya respuesta no se encuentre en los documentos para verificar que el agente reconoce cuando no dispone de información suficiente.

Nota: Streamlit, ADK Web y ADK CLI permiten interactuar con el mismo agente, pero ofrecen experiencias diferentes. Streamlit es nuestra interfaz personalizada, mientras que ADK Web y ADK CLI están orientados principalmente al desarrollo y las pruebas. Estas dos últimas opciones no sustituyen una interfaz empresarial preparada para producción.

Para detener cualquiera de los servidores o sesiones, podemos utilizar Ctrl + C desde la terminal correspondiente.

Con estas pruebas habremos completado la implementación local de nuestro Asistente de Políticas Corporativas. En la segunda parte de esta serie reutilizaremos el agente desarrollado para desplegarlo en Google Cloud Agent Runtime y ponerlo a disposición de los usuarios mediante Gemini Enterprise.

Conclusiones

A lo largo de este ejercicio hemos desarrollado un Asistente de Políticas Corporativas utilizando Google ADK, Gemini, Google Drive y Streamlit. Mediante una arquitectura sencilla basada en RAG, hemos conectado un agente de inteligencia artificial con documentos empresariales, permitiéndole consultar información, recuperar contenido relevante y generar respuestas en lenguaje natural acompañadas de sus fuentes. Además, hemos explorado aspectos importantes del desarrollo de agentes, como la integración de herramientas, la gestión de sesiones, las instrucciones del modelo y la construcción de una interfaz web.

El desarrollo de agentes de IA representa una oportunidad para que las organizaciones transformen la manera en que sus empleados acceden a la información y realizan sus actividades diarias. Soluciones como la que hemos construido pueden reducir el tiempo dedicado a buscar documentos, facilitar el acceso al conocimiento corporativo y servir como punto de partida para automatizar procesos más complejos. Sin embargo, su adopción también requiere prestar atención a la seguridad, los permisos de acceso, la calidad de la información y la supervisión de las respuestas. Este ejercicio nos permite comprender los fundamentos de la IA agéntica y cómo comenzar a llevar estas capacidades a escenarios empresariales reales.

En la segunda parte de esta serie, daremos el siguiente paso: desplegaremos nuestro agente en Google Cloud Agent Runtime y lo integraremos con Gemini Enterprise, pasando de una aplicación local a una solución accesible desde una plataforma empresarial.

Recursos

Para profundizar en las tecnologías utilizadas durante este ejercicio, puedes consultar la siguiente documentación oficial:

• Google Agent Development Kit (ADK): introducción al desarrollo de agentes, herramientas y ejecución con Python.

• Google AI Studio: plataforma para experimentar con los modelos Gemini y obtener una API Key.

• Gemini API: documentación de los modelos, SDK y configuración de la API.

• Google Drive API: integración de aplicaciones Python con documentos almacenados en Google Drive.

• Streamlit: desarrollo de aplicaciones web interactivas utilizando Python.

• Introducción a RAG — Google Cloud: conceptos y funcionamiento de la generación aumentada por recuperación.

• Google Cloud Agent Runtime: despliegue y ejecución de agentes con Google ADK en Google Cloud.

Espero sea de utilidad !!!

Síguenos:

👉Wiki Cloud | 👉X | 👉LinkedIn | 👉Github | 👉Youtube