GENAI129

Descripción general

En este lab, demostrarás tu capacidad para crear agentes con el Kit de desarrollo de agentes (ADK), implementarlos en Agent Engine y usarlos desde una app web.

Objetivo

En este lab, aprenderás a hacer lo siguiente:

• Crear un agente con el Kit de desarrollo de agentes (ADK) que esté compuesto por un agente raíz y agentes secundarios
• Habilitar agentes con una herramienta de Vertex AI Search y herramientas de funciones personalizadas
• Almacenar el resultado del agente en el estado de la sesión y recuperar valores del estado de la sesión para instrucciones posteriores del agente
• Implementar tu agente en Agent Engine
• Realizar consultas en el agente implementado en Agent Engine

Materiales de aprendizaje relacionados

Si buscas recursos que te ayuden a desarrollar las habilidades necesarias para completar este lab con éxito, revisa las secciones pertinentes de estos recursos:

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lee estas instrucciones. Los labs cuentan con un temporizador que no se puede pausar. El temporizador, que comienza a funcionar cuando haces clic en Comenzar lab, indica por cuánto tiempo tendrás a tu disposición los recursos de Google Cloud.

Este lab práctico te permitirá realizar las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, se te proporcionan credenciales temporales nuevas que utilizarás para acceder a Google Cloud durante todo el lab.

Para completar este lab, necesitarás lo siguiente:

• Acceso a un navegador de Internet estándar. Se recomienda el navegador Chrome.

• Tiempo para completar el lab (recuerda que, una vez que comienzas un lab, no puedes pausarlo).

Cómo iniciar tu lab y acceder a la consola de Google Cloud

1. Haz clic en el botón Comenzar lab. Si debes pagar por el lab, se abrirá un diálogo para que selecciones la forma de pago. A la izquierda, se encuentra el panel Detalles del lab, que tiene estos elementos:

   • El botón para abrir la consola de Google Cloud
   • El tiempo restante
   • Las credenciales temporales que debes usar para el lab
   • Otra información para completar el lab, si es necesaria

2. Haz clic en Abrir la consola de Google Cloud (o haz clic con el botón derecho y selecciona Abrir el vínculo en una ventana de incógnito si ejecutas el navegador Chrome).

   El lab inicia recursos y abre otra pestaña en la que se muestra la página de acceso.

   Sugerencia: Ordena las pestañas en ventanas separadas, una junto a la otra.

   Nota: Si ves el diálogo Elegir una cuenta, haz clic en Usar otra cuenta.

3. De ser necesario, copia el nombre de usuario a continuación y pégalo en el diálogo Acceder.

   {{{user_0.username | "Username"}}}

   También puedes encontrar el nombre de usuario en el panel Detalles del lab.

4. Haz clic en Siguiente.

5. Copia la contraseña que aparece a continuación y pégala en el diálogo Te damos la bienvenida.

   {{{user_0.password | "Password"}}}

   También puedes encontrar la contraseña en el panel Detalles del lab.

6. Haz clic en Siguiente.

   Importante: Debes usar las credenciales que te proporciona el lab. No uses las credenciales de tu cuenta de Google Cloud. Nota: Usar tu propia cuenta de Google Cloud para este lab podría generar cargos adicionales.

7. Haz clic para avanzar por las páginas siguientes:

   • Acepta los Términos y Condiciones.
   • No agregues opciones de recuperación o autenticación de dos factores (esta es una cuenta temporal).
   • No te registres para obtener pruebas gratuitas.

Después de un momento, se abrirá la consola de Google Cloud en esta pestaña.

Nota: Para acceder a los productos y servicios de Google Cloud, haz clic en el menú de navegación o escribe el nombre del servicio o producto en el campo Buscar.

Situación del desafío

Un compañero de trabajo comenzó a desarrollar un agente, Paint Agent, para ayudar al usuario a hacer lo siguiente:

• seleccionar un producto de pintura basado en las hojas de datos de productos de pintura de Cymbal Shops
• elegir un color de la línea de productos seleccionada
• determinar cuánta pintura se necesita según las dimensiones de la habitación
• calcular el precio en función de las opciones seleccionadas

Sin embargo, tu compañero de trabajo se quedó atascado con un error y se fue de la organización.

Eres un nuevo ingeniero de AA en Cymbal Shops. Se te asignó la tarea de completar la implementación de Paint Agent. El agente se estructura de la siguiente manera:

Tarea 1: Instala el ADK y configura tu entorno

En este entorno de lab, la API de Vertex AI ya se habilitó para ti. Si siguieras estos pasos en tu propio proyecto, podrías habilitarla navegando a Vertex AI y siguiendo la instrucción para hacerlo.

Prepara una pestaña del editor de Cloud Shell

1. Haz clic en Activar Cloud Shell () en la barra de título de la consola de Google Cloud.

   Nota: Como alternativa, selecciona la pestaña del navegador de la consola y presiona G y, luego, S para abrir la terminal de Cloud Shell.

2. Haz clic en Continuar.

3. Cuando se te solicite que autorices Cloud Shell, haz clic en Autorizar.

4. En la esquina superior derecha del panel de la terminal de Cloud Shell, haz clic en el botón Abrir en una ventana nueva .

5. Haz clic en el ícono de lápiz de Abrir editor () en la parte superior del panel para ver los archivos.

6. En la parte superior del menú de navegación de la izquierda, haz clic en el ícono del Explorador () para abrir el explorador de archivos.

7. Haz clic en el botón Abrir carpeta.

8. En el diálogo Abrir carpeta que se abre, haz clic en OK para seleccionar la carpeta principal de tu cuenta de estudiante de Qwiklabs.

9. Cierra cualquier instructivo adicional o panel de Gemini que aparezca en el lado derecho de la pantalla para que el editor de código tenga más espacio en la ventana.

10. Durante el resto de este lab, puedes trabajar en esta ventana como tu IDE con la terminal y el editor de Cloud Shell.

Descarga e instala el ADK y las muestras de código para este lab

1. Pega el siguiente comando en la terminal de Cloud Shell para copiar archivos de un bucket de Cloud Storage, lo que creará un directorio de proyecto con el código para este lab:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab .

2. Actualiza tu variable de entorno PATH e instala el ADK y algunos requisitos adicionales para este lab ejecutando los siguientes comandos en la terminal de Cloud Shell.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt

Tarea 2: Crea una app de búsqueda de AI Applications para obtener información sobre productos de pintura

En esta tarea, implementarás un almacén de datos de AI Applications. Este almacén de datos importará una hoja de datos que describe la pintura de Cymbal Shops (que puedes ver en una pestaña de tu ventana de incógnito en https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf). Esta hoja de datos servirá como fuente de datos de fundamentación para las consultas de los usuarios sobre tus pinturas.

1. Crea un almacén de datos de AI Applications con la siguiente configuración:

   Campo	Valor
   Fuente de datos	Cloud Storage
   Tipo de datos	Documentos
   Carpeta o archivo	Archivo
   Archivo para importar	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   Ubicación	global
   Nombre del almacén de datos	Cymbal Paint
   Analizador de documentos	Analizador de diseño
   Habilitar la anotación de tablas	Habilitado
   Incluir encabezados de principales en los fragmentos	Habilitado

2. Crea una app de búsqueda de AI Applications con la siguiente configuración:

   Campo	Valor
   Tipo de app	Búsqueda personalizada (general)
   Nombre de la app	Paint Search
   Nombre de la empresa	Cymbal Shops
   Ubicación	global
   Almacén de datos	Cymbal Paint

3. Copia los siguientes comandos en un archivo de texto. Actualiza el valor de SEARCH_ENGINE_ID de YOUR_ID con el ID del motor de búsqueda que acabas de crear (se verá como paint-search_1756… y se puede encontrar en la lista de apps en AI Applications):

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. Ejecuta los comandos editados en la terminal de Cloud Shell para crear un archivo .env con variables de autenticación y configuración del modelo. [Nota: Para ver un archivo oculto (indicado por un archivo que comienza con un punto), puedes usar los menús del Editor de Cloud Shell para habilitar Ver > Toggle Hidden Files]

5. Copia el archivo .env en el directorio del agente para proporcionar a tu agente los parámetros de configuración de autenticación necesarios una vez que se implemente:

   cp .env paint_agent/.env

Haz clic en Revisar mi progreso para verificar el objetivo. Crear un almacén de datos y una app de búsqueda

Tarea 3: Depura Paint Agent

Uno de tus compañeros de trabajo comenzó a trabajar en Paint Agent, pero se quedó atascado. Deberás retomar el trabajo donde lo dejó, lo que incluye corregir un error que dejó atrás, para completar y, luego, implementar el agente.

1. En la terminal de Cloud Shell, ejecuta la versión actual del agente con este comando:

   adk run paint_agent

2. Cuando aparezca el prompt [user]:, ingresa lo siguiente:

   hola

   Si el agente te pregunta si te gustaría obtener más información sobre las pinturas de Cymbal Shops, responde lo siguiente:

   sí

   El resultado esperado termina con lo siguiente:

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   En los siguientes pasos, resolverás este error.

3. Abre el archivo adk_challenge_lab/paint_agent/agent.py y revisa las listas de agentes secundarios y herramientas que utiliza el root_agent. Observa que incluye agentes secundarios. La transferencia a agentes secundarios invoca una herramienta implícita transfer_to_agent.

4. La herramienta del root_agent no es una herramienta de búsqueda, por lo que al menos uno de los agentes secundarios debe invocar una herramienta de búsqueda. Explora los agentes secundarios que se encuentran en el directorio sub_agents para encontrar la herramienta de búsqueda que se usa (en este caso, un VertexAiSearchTool):

5. Si bien una herramienta de búsqueda no se puede combinar con otras herramientas que no son de búsqueda en un agente (incluso si se usa en un agente secundario como se ve aquí), el ADK proporciona una herramienta llamada AgentTool que puede unir un agente aislado que usa una herramienta de búsqueda. Luego, ese agente como herramienta puede usarse con otras herramientas.

   De vuelta en el archivo adk_challenge_lab/paint_agent/agent.py del root_agent, agrega un AgentTool() a la lista de herramientas del root_agent. Proporciona los siguientes argumentos a AgentTool():

   • agent debe establecerse en el agente secundario que usa la herramienta de búsqueda que descubriste anteriormente.
   • skip_summarization debe establecerse en False porque quieres que el agente informe sobre lo que devolvió la herramienta de búsqueda.

6. Quita ese agente secundario de la lista sub_agents.

7. Guarda el archivo.

8. En la terminal de Cloud Shell, vuelve a ejecutar el agente con lo siguiente:

   adk run paint_agent

   Ahora deberías poder chatear con el agente y obtener información sobre la pintura de Cymbal Shops.

9. Haz que el agente te diga el precio de las pinturas EcoGreens y Forever Paint.

   Haz clic en Revisar mi progreso para verificar el objetivo. Depurar tu agente

10. Cuando termines de chatear con el agente a través de la interfaz de línea de comandos, escribe exit para finalizar la conversación.

Tarea 4: Guarda y utiliza el estado compartido

Tu root_agent importa y usa una herramienta set_session_value de adk_challenge_lab/paint_agent/tools.py, pero no está completamente implementada.

1. Actualiza la función set_session_value en el archivo adk_challenge_lab/paint_agent/tools.py para almacenar pares key-value en el diccionario state de ToolContext.

2. Actualiza la respuesta de la función para que muestre un mensaje de estado de f"stored '{value}' in '{key}'".

3. Abre el archivo agent.py asociado con coverage_calculator_agent (agente secundario de room_planner, que es un agente secundario de tu root_agent).

4. Observa que sus instrucciones no cargan correctamente los valores del diccionario de estado. Actualiza la instrucción para reemplazar los términos EN MAYÚSCULAS y, en su lugar, usa la plantilla de claves de ADK para cargar valores de estado en las instrucciones.

5. Prueba tu agente con lo siguiente:

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

6. Selecciona paint_agent.

7. Ahora deberías poder tener la siguiente conversación con tu agente:

   Tú	Respuesta del agente
   hola	[Ofrece compartir información sobre las pinturas de Cymbal Shops].
   sí	[Comparte información sobre los productos de pintura, p. ej., Project Paint, EcoGreens, SureCoverage, Forever Paint].
   Quiero usar EcoGreens	[La pestaña Estado debería mostrar los valores de estado actualizados. Pregunta cuántas habitaciones hay y cómo se llama cada una].
   Solo una habitación, mi oficina	[Te pide que elijas un color para tu oficina].
   Deep Ocean	[Te pide las dimensiones de la habitación].
   3 m × 4 m. 3 m de altura. 1 puerta y 2 ventanas.	[Confirma la cantidad de capas].
   Dos capas.	[Calcula que necesitarás una cobertura de 74 m²].

8. Cuando termines de chatear con tu agente, puedes cerrar la pestaña del navegador de la IU de desarrollo.

   Haz clic en Revisar mi progreso para verificar el objetivo. Establecer y utilizar el estado de la sesión

9. Selecciona el panel de la terminal de Cloud Shell y presiona CTRL + C para detener el servidor.

Tarea 5: Implementa el agente en Agent Engine

1. En la terminal de Cloud Shell, asegúrate de que te encuentras en el directorio adk_challenge_lab:

   cd ~/adk_challenge_lab

2. Implementa tu agente con el comando de implementación adecuado para implementar paint_agent en Agent Engine con los siguientes argumentos:

   Parámetro	Argumento
   --display_name	"Paint Agent"
   --staging_bucket	gs://-bucket

3. Mientras el agente se implementa, otorga los roles de IAM Usuario de Vertex AI y Usuario de Discovery Engine al Agente de servicio de Vertex AI Reasoning Engine.

4. Ten en cuenta que, cuando se completa la implementación, el nombre del recurso del agente implementado se imprime en la consola.

   Haz clic en Revisar mi progreso para verificar el objetivo. Implementar el agente en Agent Engine

Tarea 6: Hazle preguntas al agente implementado

1. En el archivo adk_challenge_lab/chainlit_ui/app.py, busca y actualiza la siguiente línea con el nombre de recurso de tu agente implementado para cargar tu agente remoto:

   agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')

2. Ejecuta la IU con lo siguiente:

   cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

   Resultado esperado:

   2025-08-25 12:30:00 - Your app is available at http://localhost:8000

3. Haz clic en el vínculo http://localhost:8000 para abrirlo en una nueva pestaña del navegador.

4. Ten la siguiente conversación con tu agente implementado:

   Tú	Respuesta del agente
   hola	[Ofrece compartir información sobre Cymbal Paints].
   sí	[Comparte información sobre los productos de pintura, p. ej., Project Paint, EcoGreens, SureCoverage, Forever Paint]
   Quiero usar Forever Paint	[Pregunta cuántas habitaciones hay y cómo se llama cada una].
   Dos habitaciones: la sala de estar y la habitación del bebé.	[Te pide que elijas un color para tu oficina].
   "Sunlight through a canvas tent" para la habitación del bebé y "Coffee Cream" para la sala de estar.	[Te pide las dimensiones de la habitación].
   La sala de estar mide 5 m × 4 m. 2.5 m de altura. 1 puerta y 3 ventanas.	[Pregunta la cantidad de capas]
   Dos capas.	[Solicita las dimensiones de la habitación del bebé].
   La habitación del bebé mide 3 m × 3 m. 2.5 m de altura. 1 puerta y 1 ventana.	[Proporciona una estimación de una capa y confirma la cantidad de capas]
   Siempre dos capas.	[Calcula que necesitarás una cobertura de 77 m² para la sala de estar y de 53 m² para la habitación del bebé.]

5. Si quieres iniciar una nueva conversación con tu agente, puedes hacer clic en el ícono de la parte superior izquierda para crear un nuevo chat.

   Haz clic en Revisar mi progreso para verificar el objetivo. Configurar un frontend para hacerle preguntas al agente

¡Felicitaciones!

En este lab, hiciste lo siguiente:

• Crear un agente con el Kit de desarrollo de agentes (ADK) compuesto por un agente raíz y agentes secundarios
• Habilitar agentes con una herramienta de Vertex AI Search y herramientas de funciones personalizadas
• Almacenar la salida del agente en un diccionario de estado de la sesión y recuperar valores del diccionario de estado de la sesión para instrucciones posteriores del agente
• Implementar tu agente en Agent Engine
• Hacerle preguntas al agente implementado en Agent Engine

Capacitación y certificación de Google Cloud

Recibe la formación que necesitas para aprovechar al máximo las tecnologías de Google Cloud. Nuestras clases incluyen habilidades técnicas y recomendaciones para ayudarte a avanzar rápidamente y a seguir aprendiendo. Para que puedas realizar nuestros cursos cuando más te convenga, ofrecemos distintos tipos de capacitación de nivel básico a avanzado: a pedido, presenciales y virtuales. Las certificaciones te ayudan a validar y demostrar tus habilidades y tu conocimiento técnico respecto a las tecnologías de Google Cloud.

Última actualización del manual: 26 de febrero de 2026

Prueba más reciente del lab: 26 de febrero de 2026

Copyright 2026 Google LLC. All rights reserved. Google y el logotipo de Google son marcas de Google LLC. Los demás nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que estén asociados.