De prototipos a agentes con ADK

1. Descripción general

¿Dónde comienza la compilación con IA hoy en día? En la mayoría de los casos, suele comenzar con una pregunta simple: "¿El modelo puede ayudar a resolver este problema en el que he estado pensando?". Ahí es exactamente donde entra en juego Google AI Studio. Es un lugar en el que puedes crear prototipos de cualquier cosa rápidamente. Quiero remodelar mi cocina y creo que Gemini puede ayudarme, pero soy ingeniero, no contratista general. Ni siquiera sé qué pedir, hay mucho en cuenta: reglamentaciones, accesorios, etc. Así que analicemos esto y pidamos a Gemini que genere una propuesta muy detallada para nosotros, luego genere un plan de renovación completo y también visualice la remodelación. Pero espera. ¿Cómo puedo ayudar a las empresas a escalar desde aquí? Ingresa AGENTS!!!

Un agente es un programa autónomo que habla con un modelo de IA para realizar una operación basada en objetivos con las herramientas y el contexto que tiene, y es capaz de tomar decisiones autónomas basadas en la verdad.

El kit de desarrollo de agentes (ADK)

El kit de desarrollo de agentes (ADK) es un framework flexible y modular para desarrollar e implementar agentes de IA. El ADK admite la compilación de aplicaciones sofisticadas mediante la composición de varias instancias de agentes distintas en un sistema multiagente (MAS).

En ADK, un sistema multiagente es una aplicación en la que diferentes agentes, que a menudo forman una jerarquía, colaboran o se coordinan para lograr un objetivo más amplio. Estructurar tu aplicación de esta manera ofrece ventajas significativas, como modularidad mejorada, especialización, reusabilidad, capacidad de mantenimiento y la capacidad de definir flujos de control estructurados con agentes de flujo de trabajo dedicados.

Qué compilarás

¿Todo listo para pasar de la PROMPT de nuestro prototipo a la compilación de un agente? Crearemos un agente para ayudar a generar el documento de propuesta del proyecto de renovación de la cocina. Como parte de este lab, aprenderás a hacer lo siguiente:

  1. Compila un agente simple para generar un documento de propuesta de renovación con el ADK
  2. Almacena el documento de propuesta de renovación generado en un bucket de Cloud Storage
  3. Prueba el agente en Cloud Shell y en el resultado web del agente

Requisitos

  • Un navegador, como Chrome o Firefox.
  • Un proyecto de Google Cloud con facturación habilitada.

2. Antes de comenzar

Crea un proyecto

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .
  3. Además, si estás leyendo esto y quieres obtener créditos para comenzar a usar Google Cloud y ADK, usa este vínculo para canjear créditos.
  4. Puedes seguir las instrucciones aquí para canjearlo. Ten en cuenta que este vínculo solo es válido para canjear hasta el 15 de julio de 2025.
  5. Para activar Cloud Shell, haz clic en este vínculo. Para alternar entre la terminal de Cloud Shell (para ejecutar comandos de Cloud) y el editor (para compilar proyectos), haz clic en el botón correspondiente de Cloud Shell.
  6. Una vez que te conectes a Cloud Shell, verifica que ya te hayas autenticado y que el proyecto esté configurado con tu ID con el siguiente comando:
gcloud auth list
  1. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
  1. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>
  1. Asegúrate de tener Python 3.9 o versiones posteriores.

Consulta la documentación para ver otros comandos y usos de gcloud.

3. Prototipo

Ve a Google AI Studio. Comienza a escribir en la instrucción. Esta es mi instrucción:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Ajusta y configura los parámetros del lado derecho para obtener una respuesta óptima.

Con esta simple descripción, Gemini me hizo una propuesta increíblemente detallada para comenzar mi renovación. En efecto, usamos Gemini para obtener respuestas aún mejores de AI Studio y nuestros modelos. También puedes seleccionar diferentes modelos según tu caso de uso.

Elegimos Gemini 2.5 Pro. Este es un modelo de pensamiento, lo que significa que obtenemos aún más tokens de salida, en este caso, hasta 65,000 tokens, para análisis de formato largo y documentos detallados. La caja de pensamiento de Gemini aparece cuando habilitas Gemini 2.5 Pro, que tiene capacidades de razonamiento nativas y puede recibir solicitudes de contexto largo.

Consulta el siguiente fragmento de la respuesta:

a80d4bad4b3864f7.png

AI Studio analizó mis datos y produjo todo tipo de elementos, como gabinetes, encimeras, revestimientos, pisos, lavabos, cohesión, paleta de colores y selección de materiales. Gemini incluso cita fuentes.

Ahora intenta ver cómo cobra vida la idea con una instrucción diferente.

  1. Copia esta instrucción y pégala en el editor de instrucciones:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. Adjunta una imagen de tu cocina actual (o puedes usar mi imagen de cocina de muestra).
  2. Cambia el modelo a "Gemini 2.0 Flash Preview Image Generation" para tener acceso a la generación de imágenes.

Obtuve este resultado:

b5b1e83fcada28f5.png

Ese es el poder de Gemini.

Desde la comprensión de videos hasta la generación de imágenes nativas y la fundamentación de información real con la Búsqueda de Google, hay funciones que solo se pueden compilar con Gemini.

Desde AI Studio, puedes tomar este prototipo, obtener la clave de API y escalarlo a una aplicación de agentes completa con el poder del ADK de Vertex AI.

4. Configuración del ADK

Ahora, ve a la terminal de Cloud Shell que activamos en la sección "Antes de comenzar":

  1. Crea y activa un entorno virtual (recomendado)

En la terminal de Cloud Shell, crea un entorno virtual:

python -m venv .venv

Activa el entorno virtual:

source .venv/bin/activate
  1. Instala el ADK
pip install google-adk

5. Estructura del proyecto

  1. En la terminal de Cloud Shell, crea un directorio raíz para tus apps de agentes en la ubicación del proyecto que desees:
mkdir agentic-apps
  1. Dentro del directorio principal, crea una carpeta específica para nuestro proyecto actual:
mkdir renovation-agent
  1. Ve al editor de Cloud Shell y crea los siguientes archivos (vacíos al principio) para crear la siguiente estructura de proyecto:
renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Código fuente

  1. Ve a "init.py" y actualízalo con el siguiente contenido:
from . import agent
  1. Ve a agent.py y actualiza el archivo con el siguiente contenido de la siguiente ruta:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py

En agent.py, importamos las dependencias necesarias, recuperamos los parámetros de configuración del archivo .env y definimos el root_agent, que genera un documento de propuesta y lo almacena en un bucket de Cloud Storage. Para realizar el paso de Cloud Storage, usamos una herramienta llamada store_pdf.

  1. Asegúrate de tener el bucket de Cloud Storage

Esto sirve para almacenar el documento de propuesta que genera el agente. Créala y aprovisiona el acceso para que el sistema de agentes que creamos con Vertex AI pueda acceder a ella. Sigue estos pasos para hacerlo:

https://cloud.google.com/storage/docs/creating-buckets#console

Asigna el nombre “next-demo-store” a tu bucket. Si le asignas otro nombre, recuerda actualizar el valor de STORAGE_BUCKET en el archivo .env (en el paso de configuración de variables de entorno).

  1. Para configurar el acceso al bucket, ve a la consola de Cloud Storage y, luego, a tu bucket de almacenamiento (en nuestro caso, el nombre del bucket es "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.

Navega a Permisos -> Ver principales -> Otorgar acceso. Selecciona Principals como "allUsers" y Role como "Storage Object User".

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. Crea una lista de dependencias

Enumera todas las dependencias en requirements.txt. Puedes copiarlo del repositorio.

Explicación del código fuente del sistema de agente único

El archivo agent.py define la estructura y el comportamiento de nuestro sistema multiagente de renovación de cocinas con el kit de desarrollo de agentes (ADK). Desglosemos los componentes clave:

Definición del agente

Agente raíz (Orchestrator): proposal_agent

root_agent actúa como el orquestador de este sistema de un solo agente. Recibe la solicitud de renovación inicial y determina qué herramientas invocar según las necesidades de la solicitud.

Luego, root_agent recopila las respuestas de las herramientas y las combina para proporcionar una respuesta integral al usuario. En este caso, solo tenemos una herramienta "store_pdf".

7. Flujo de datos y conceptos clave

El usuario inicia una solicitud a través de la interfaz del ADK (la terminal o la IU web).

  1. El root_agent recibe la solicitud.
  2. root_agent analiza la solicitud y la enruta a la herramienta según sea necesario.
  3. La herramienta "store_pdf" está diseñada para escribir el contenido de texto renovado en un archivo PDF y, luego, subirlo a Google Cloud Storage.
  4. Luego, muestra la respuesta a root_agent.
  5. root_agent combina las respuestas y proporciona un resultado final al usuario.

LLM (modelos de lenguaje grandes)

Los agentes dependen en gran medida de los LLM para generar texto, responder preguntas y realizar tareas de razonamiento. Los LLM son el “cerebro” detrás de la capacidad de los agentes para comprender y responder las solicitudes de los usuarios. En esta aplicación, usamos Gemini 2.5.

Google Cloud Storage

Se usa para almacenar los documentos de la propuesta de renovación generados. Debes crear un bucket y otorgar los permisos necesarios para que los agentes accedan a él.

Cloud Run (opcional)

OrderingAgent usa una función de Cloud Run para interactuar con AlloyDB. Cloud Run proporciona un entorno sin servidores para ejecutar código en respuesta a solicitudes HTTP.

AlloyDB

Si usas OrderingAgent, deberás configurar una base de datos de AlloyDB para almacenar la información de los pedidos.

Archivo.env

El archivo .env almacena información sensible, como claves de API, credenciales de bases de datos y nombres de buckets. Es fundamental mantener este archivo seguro y no confirmarlo en tu repositorio. También almacena la configuración de los agentes y tu proyecto de Google Cloud. Por lo general, root_agent o las funciones de compatibilidad leen valores de este archivo. Asegúrate de que todas las variables requeridas estén configuradas correctamente en el archivo .env. Esto incluye el nombre del bucket de Cloud Storage

8. Configuración del modelo

La capacidad de tu agente para comprender las solicitudes de los usuarios y generar respuestas se basa en un modelo de lenguaje grande (LLM). Tu agente debe realizar llamadas seguras a este servicio de LLM externo, que requiere credenciales de autenticación. Sin una autenticación válida, el servicio de LLM rechazará las solicitudes del agente, y este no podrá funcionar.

  1. Obtén una clave de API de Google AI Studio.
  2. En el siguiente paso, en el que configurarás el archivo .env, reemplaza <<your API KEY>> por el valor real de la CLAVE DE API.

9. Configuración de las variables de entorno

  1. Configura los valores de los parámetros en el archivo .env de la plantilla en este repositorio. En mi caso, el archivo .env tiene estas variables:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Reemplaza los marcadores de posición por tus valores.

10. Ejecuta tu agente

  1. En la terminal, navega al directorio superior de tu proyecto de agente:
cd agentic-apps/renovation-agent
  1. Instala todas las dependencias
pip install -r requirements.txt
  1. Puedes ejecutar el siguiente comando en la terminal de Cloud Shell para ejecutar el agente:
adk run .
  1. Puedes ejecutar lo siguiente para ejecutarlo en una IU web aprovisionada de ADK:
adk web
  1. Prueba con las siguientes instrucciones:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Resultado

Para el comando adk run . resultado es el siguiente".

ae50e6f6b2bab0a0.png

38a2c34667a8fd05.png

a8a39e8323d3ceb9.png

Puedes validar si el documento Renovation Proposal se creó en el bucket de Cloud Storage.

12. Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta publicación:

  1. En la consola de Google Cloud, ve a la página Administrar recursos.
  2. En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

13. Felicitaciones

¡Felicitaciones! Creaste e interactuaste correctamente con tu app de varios agentes con el ADK. El sistema de varios agentes está diseñado para optimizar el proceso de renovación de cocinas automatizando tareas como la generación de propuestas, la verificación de permisos y el seguimiento del estado de los pedidos. Cada agente tiene un rol específico, y root_agent coordina sus actividades para proporcionar una solución integral. El sistema aprovecha los LLM, los servicios de Google Cloud y, posiblemente, las APIs externas para ofrecer su funcionalidad. Aquí encontrarás un vínculo a la documentación del producto.