✋ 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.
| Carpeta o Archivo | Descripción |
|---|---|
| sources_en/ | Contiene la versión del agente en inglés, incluyendo su interfaz, instrucciones y políticas corporativas. |
| sources_es/ | Contiene la versión del agente en español, que utilizaremos como referencia durante este artículo. |
| .streamlit/ | Contiene config.toml, utilizado para personalizar la apariencia y configuración de Streamlit. |
| corporate_agent/ | Contiene la lógica principal del agente de inteligencia artificial desarrollado con Google ADK. |
| corporate_agent/agent.py | Define el agente principal (root_agent), sus instrucciones, el modelo Gemini y la herramienta de búsqueda de políticas. |
| corporate_agent/drive_rag.py | Implementa la conexión con Google Drive, la lectura de documentos, su fragmentación, indexación y recuperación mediante RAG. |
| corporate_policies/ | Contiene ejemplos de políticas corporativas en archivos TXT, redactados en el idioma correspondiente a cada versión. Estos documentos servirán como base de conocimiento al cargarlos en Google Drive. |
| credentials/ | Carpeta destinada a almacenar las credenciales locales necesarias para acceder a Google Drive. |
| deployment/ | Contiene los scripts necesarios para desplegar el agente en Google Cloud Agent Runtime. Se utilizará principalmente en la segunda parte de la serie, cuando se implemente el agente en Gemini Enterprise. |
| prompts/ | Almacena las instrucciones o prompts del agente en el idioma correspondiente. |
| test/ | Agrupa las pruebas para validar la conexión con Google Drive, el funcionamiento de Gemini y la ejecución del agente desplegado en Agent Runtime. |
__init__.py | Archivos utilizados para identificar paquetes Python y organizar la importación de módulos. |
| .env | Almacena las variables de entorno de la aplicación, como la configuración de Gemini, Google Drive y Agent Runtime. |
| .gitignore | Define los archivos y carpetas que Git debe excluir, como credenciales, cachés y entornos virtuales. |
| app.py | Implementa la interfaz web desarrollada con Streamlit, incluyendo el chatbot, las sesiones y las métricas de consumo. |
| pyproject.toml | Define la configuración de empaquetado del proyecto, necesaria para generar el paquete instalable del agente. |
| README.md | Contiene la documentación general del proyecto, los requisitos, las instrucciones de instalación y los comandos de ejecución en idioma inglés. |
| README_ES.md | Contiene la documentación general del proyecto, los requisitos, las instrucciones de instalación y los comandos de ejecución en idioma español. |
| requirements.txt | Incluye las dependencias de Python necesarias para configurar el entorno de desarrollo y ejecutar la 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.
| Dependencia | Descripción |
|---|---|
| google-adk | Framework de Google que utilizaremos para desarrollar nuestro agente de IA, definir sus instrucciones, integrar herramientas y gestionar las sesiones de conversación. |
| google-genai | SDK para interactuar con los modelos Gemini, enviar consultas y obtener respuestas generadas por el modelo. |
| google-api-python-client | Cliente que permite consumir las APIs de Google. En nuestro caso, lo utilizaremos para consultar y descargar documentos mediante Google Drive API. |
| google-auth | Proporciona los mecanismos de autenticación necesarios para acceder a los servicios de Google mediante credenciales autorizadas. |
| google-auth-oauthlib | Facilita la implementación de flujos OAuth 2.0 cuando una aplicación necesita autenticarse con una cuenta de usuario. |
| google-cloud-storage | Permite interactuar con Google Cloud Storage. Lo utilizaremos principalmente en la segunda parte de la serie para validar el bucket de almacenamiento utilizado durante el despliegue. |
| python-dotenv | Permite cargar las variables de configuración definidas en el archivo .env, como el modelo Gemini y los parámetros de conexión con Google Drive. |
| python-docx | Biblioteca utilizada para leer y extraer contenido de documentos Microsoft Word (.docx). |
| pypdf | Permite extraer texto de archivos PDF que contienen texto seleccionable. |
| streamlit | Framework de Python con el que construiremos la interfaz web del asistente, incluyendo el chatbot y los indicadores de consumo. |
| pydantic | Biblioteca para definir, validar y estructurar datos mediante modelos Python. También es utilizada por componentes del ecosistema Google ADK. |
| cloudpickle | Permite serializar objetos Python, una capacidad útil para empaquetar y desplegar componentes del agente en entornos remotos. |
| google-cloud-aiplatform[agent_engines,adk]>=1.112.0 | Instala el SDK de Vertex AI con dependencias adicionales para Agent Runtime y Google ADK. Lo utilizaremos en la segunda parte para desplegar y probar el agente en Google Cloud. |
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.
| Variable | Descripción |
|---|---|
| GOOGLE_API_KEY | Clave de acceso a Gemini API, generada desde Google AI Studio. Debemos reemplazar YOUR_GEMINI_API_KEY por nuestra API Key. |
| GOOGLE_GENAI_USE_VERTEXAI | Indica si utilizaremos Gemini API (FALSE) o Vertex AI (TRUE). Para esta primera implementación local mantendremos FALSE. |
| GEMINI_MODEL | Define el modelo Gemini que utilizará nuestro agente. En este ejemplo configuramos gemini-3.5-flash-lite, siempre que esté disponible para nuestro proyecto. |
| GEMINI_VERTEX_LOCATION | Establece la ubicación del endpoint de inferencia cuando utilizamos Vertex AI. Mantendremos global, que utilizaremos en la segunda parte del ejercicio. |
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.
| Variable | Descripción |
|---|---|
| DRIVE_AUTH_MODE | Define el mecanismo de autenticación utilizado para acceder a Google Drive. Para nuestra aplicación local utilizaremos service_account_file, que permite autenticarnos mediante un archivo JSON de una cuenta de servicio. |
| DRIVE_SERVICE_ACCOUNT_FILE | Indica la ubicación del archivo JSON que contiene las credenciales de la cuenta de servicio. Debemos comprobar que exista en la ruta credentials/service-account.json. |
| GOOGLE_DRIVE_FOLDER_ID | Identificador de la carpeta de Google Drive donde almacenaremos las políticas corporativas. Debemos reemplazar YOUR_DRIVE_FOLDER_ID por el identificador real de nuestra carpeta. |
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.
| Variable | Descripción |
|---|---|
| GOOGLE_CLOUD_PROJECT | Identificador del proyecto de Google Cloud. Reemplazaremos YOUR_PROJECT_ID por el ID real de nuestro proyecto. |
| AGENT_RUNTIME_LOCATION | Región de Google Cloud donde desplegaremos el agente. En este ejemplo utilizaremos europe-west1. |
| AGENT_RUNTIME_STAGING_BUCKET | Bucket de Google Cloud Storage utilizado durante el despliegue para almacenar temporalmente los archivos necesarios. Debemos reemplazar YOUR_STAGING_BUCKET por el nombre del bucket creado. |
| AGENT_RUNTIME_SERVICE_ACCOUNT | Cuenta de servicio que utilizará el agente cuando se ejecute en Google Cloud. Debemos reemplazar el correo de ejemplo por el de la cuenta configurada para Agent Runtime. |
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.
| Variable | Descripción | Valor del ejemplo |
|---|---|---|
| RAG_TOP_K | Cantidad máxima de fragmentos relevantes que recuperará el agente por consulta. | 3 |
| RAG_MAX_FRAGMENT_CHARS | Número máximo de caracteres que se enviarán al modelo por cada fragmento recuperado. | 900 |
| RAG_REFRESH_INTERVAL_SECONDS | Intervalo de actualización automática del índice RAG, expresado en segundos. Se utiliza cuando el agente administra su propia caché, como en Agent Runtime. | 300 (5 minutos) |
| MAX_DRIVE_FILES | Número máximo de archivos de Google Drive que se procesarán durante la indexación. | 250 |
| MAX_FILE_BYTES | Tamaño máximo permitido por archivo, expresado en bytes. | 10000000 (10 MB decimales) |
| MAX_DOCUMENT_CHARS | Número máximo de caracteres que se extraerán y procesarán de cada documento. | 150000 |
| AGENT_TIMEOUT_SECONDS | Tiempo máximo de espera para completar una consulta desde la aplicación Streamlit. | 180 segundos |
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.
| Variable | Descripción |
|---|---|
| GEMINI_INPUT_USD_PER_1M | Precio de referencia en dólares por cada millón de tokens de entrada. |
| GEMINI_OUTPUT_USD_PER_1M | Precio de referencia en dólares por cada millón de tokens de salida. |
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.
- Accedemos a Google Cloud Console e iniciamos sesión.
- Seleccionamos el proyecto de Google Cloud que utilizaremos para el ejercicio.
- En el menú lateral, nos dirigimos a APIs y servicios → Biblioteca.
- Buscamos Google Drive API.
- 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:
- Accedemos a IAM y administración → Cuentas de servicio (Service Accounts).
- Hacemos clic en Crear cuenta de servicio (Create Service Account).
- Introducimos los siguientes valores de ejemplo:
| Campo | Valor sugerido |
|---|---|
| Nombre | Corporate Policies Drive Reader |
| ID de cuenta de servicio | drive-agent-reader |
| Descripción | Cuenta de servicio para consultar políticas corporativas almacenadas en Google Drive |
El correo electrónico de la cuenta tendrá una estructura similar a:
drive-agent-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com - Seleccionamos Crear y continuar (Create and Continue).
- En la asignación de roles del proyecto, podemos continuar sin añadir permisos IAM generales.
- 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 c...
