Se usó la API de Cloud Translation para traducir esta página.

De prototipos a agentes con ADK

1. Descripción general

¿Dónde comienza la creación con IA hoy en día? Para la mayoría de nosotros, a menudo comienza con una pregunta simple: "¿El modelo puede ayudar a resolver el problema en el que he estado pensando?". Ahí es donde entra en juego Google AI Studio. Es un lugar donde puedes crear prototipos rápidamente. Quiero remodelar mi cocina y apuesto a que Gemini puede ayudarme, pero soy ingeniero, no contratista general. Ni siquiera sé qué pedir, hay mucho que tener en cuenta: reglamentaciones, accesorios, etcétera. Así que desglosaremos esto y le pediremos a Gemini que genere una instrucción superdetallada para nosotros, luego que genere un plan de renovación completo y que también visualice la remodelación. Pero espera. ¿Cómo puedo ayudar a las empresas a expandirse a partir de ahora? Ingresa AGENTES.

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 y, luego, implementar agentes de IA. El ADK admite la creación de aplicaciones sofisticadas componiendo varias instancias de agentes distintas en un sistema multiagente (MAS).

En el 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 mayor. Estructurar tu aplicación de esta manera ofrece ventajas significativas, como mayor modularidad, especialización, reutilización, capacidad de mantenimiento y la posibilidad de definir flujos de control estructurados con agentes de flujo de trabajo dedicados.

Qué compilarás

¿Todo listo para pasar de nuestro PROMPT de prototipo a la creació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, harás lo siguiente:

Crea un agente simple para generar un documento de propuesta de renovación con el ADK
Almacena el documento de propuesta de renovación generado en un bucket de Cloud Storage
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

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
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 .
Además, si estás leyendo esto y quieres obtener créditos para comenzar a usar Google Cloud y el ADK, usa este vínculo para canjear créditos.
Puedes seguir las instruccionesaquí para canjearlo. Ten en cuenta que este vínculo solo es válido hasta el 15 de julio de 2025 para canjear la tarjeta.
Haz clic en este vínculo para activar Cloud Shell. 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.
Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto con el siguiente comando:

gcloud auth list

En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Asegúrate de tener Python 3.9 o una versión posterior.

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

3. Prototipo

Ve a Google AI Studio. Comienza a escribir 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.

Según esta simple descripción, Gemini me creó una instrucción 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 para usar, según tu caso de uso.

Elegimos Gemini 2.5 Pro. Este es un modelo de Thinking, 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 documentación detallada. La caja de pensamiento de Gemini aparece cuando habilitas Gemini 2.5 Pro, que tiene capacidades de razonamiento nativas y puede procesar solicitudes de contexto largo.

A continuación, se muestra el fragmento de la respuesta:

AI Studio analizó mis datos y produjo todos estos elementos, como gabinetes, encimeras, salpicaduras, pisos, fregaderos, cohesión, paleta de colores y selección de materiales. Gemini incluso cita fuentes.

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

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.

Adjunta una imagen de tu cocina actual (o puedes usar mi imagen de cocina de muestra).
Cambia el modelo a "Generación de imágenes de vista previa de Gemini 2.0 Flash" para que puedas generar imágenes.

Obtuve este resultado:

Ese es el poder de Gemini.

Desde comprender videos hasta generar imágenes de forma nativa y fundamentar información real con la Búsqueda de Google, hay cosas que solo se pueden crear con Gemini.

En AI Studio, puedes tomar este prototipo, obtener la clave de API y escalarlo a una aplicación basada en agentes completa con la potencia del ADK de Vertex AI.

4. Configuración del ADK

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

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

Instala el ADK.

pip install google-adk

5. Estructura del proyecto

En la terminal de Cloud Shell, crea un directorio raíz para tus apps con agentes en la ubicación del proyecto que desees:

mkdir agentic-apps

Dentro del directorio principal, crea una carpeta específica para nuestro proyecto actual:

mkdir renovation-agent

Ve al editor de Cloud Shell y crea la siguiente estructura de proyecto. Para ello, crea los archivos (vacíos al principio):

renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Código fuente

Ve a "init.py" y actualízalo con el siguiente contenido:

from . import agent

Ve a agent.py y actualiza el archivo con el siguiente contenido de la siguiente ruta:

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.

NOTA: Actualmente, el PDF NO TIENE FORMATO. Según el PR de la comunidad de desarrolladores, se incluyó el siguiente fragmento aquí [no se probó]. Puedes incluirlo en el método store_pdf:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"

Asegúrate de tener el bucket de Cloud Storage

Se usa para almacenar el documento de propuesta que genera el agente. Crea el acceso y aprovisiónalo para que el sistema de agentes que creamos con Vertex AI pueda acceder a él. Sigue estos pasos:

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).

Para configurar el acceso al bucket, ve a la consola de Cloud Storage y 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.

Ve 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.

Crea una lista de dependencias

Enumera todas las dependencias en requirements.txt. Puedes copiarlo desde repo.

Explicación del código fuente del sistema de un solo agente

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

Definición del agente

Agente raíz (organizador): proposal_agent

El root_agent actúa como el organizador 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, el agente raíz 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 (ya sea la terminal o la IU web).

El agente raíz recibe la solicitud.
El agente raíz analiza la solicitud y la enruta a la herramienta cuando sea necesario.
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.
Luego, devuelve la respuesta al root_agent.
El agente raíz 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 a 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 generada. 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, las funciones de root_agent o de asistencia leerán valores de este archivo. Asegúrate de que todas las variables obligatorias 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 externo de LLM, lo 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.

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

9. Configuración de variables de entorno

Configura los valores de los parámetros en el archivo .env de la plantilla en este repo. 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

Con la terminal, navega al directorio principal de tu proyecto del agente:

cd agentic-apps/renovation-agent

Instala todas las dependencias

pip install -r requirements.txt

Puedes ejecutar el siguiente comando en tu terminal de Cloud Shell para ejecutar el agente:

adk run .

Puedes ejecutar el siguiente comando para ejecutarlo en una IU web aprovisionada por el ADK:

Nota: Debes ejecutar este comando FUERA de la carpeta de tu proyecto del agente, salir un paso y, luego, ejecutarlo:

adk web

Haz la 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 . El resultado es el siguiente".

…

Puedes validar si el documento de la Propuesta de renovación se creó en el bucket de Cloud Storage.

12. Implementa en Cloud Run

Crea un archivo llamado Dockerfile dentro de la carpeta raíz del proyecto:

cd agentic-apps/renovation-agent

Copia el contenido del repositorio de GitHub

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

en este archivo Dockerfile.

Realiza la implementación en Cloud Run con el siguiente comando:

adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

Eso es todo. Una vez que se implemente, deberías ver tu extremo en la terminal, que estará listo para que lo uses.

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

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

14. Felicitaciones

¡Felicitaciones! Creaste y usaste correctamente tu app multiagente con el ADK. El sistema multiagente está diseñado para optimizar el proceso de renovación de la cocina 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 el agente raíz coordina sus actividades para brindar una solución integral. El sistema aprovecha los LLM, los servicios de Google Cloud y, potencialmente, las APIs externas para ofrecer su funcionalidad. Aquí encontrarás un vínculo a la documentación del producto.