GENAI107

Descripción general

En este lab, aprenderás a implementar agentes del ADK en Agent Engine para obtener un entorno escalable y completamente administrado para tus flujos de trabajo basados en agentes.

Esto te permite enfocarte en la lógica de los agentes mientras la infraestructura se asigna y escala por ti.

Objetivo

En este lab, aprenderás lo siguiente:

• Los beneficios de implementar agentes en Agent Engine
• Cómo otorgar los roles necesarios al agente de servicio de Reasoning Engine
• Cómo implementar un agente en Agent Engine con la interfaz de línea de comandos del ADK
• Cómo consultar un agente implementado en Agent Engine
• Cómo supervisar tus agentes implementados
• Cómo borrar agentes

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lea estas instrucciones. Los labs tienen un tiempo límite; no puede ponerlos en pausa. El cronómetro, que comienza a funcionar cuando hace clic en Comenzar lab, indica por cuánto tiempo estarán los recursos en la nube a su disposición.

Este lab práctico de Qwiklabs le permitirá llevar a cabo las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, recibe nuevas credenciales temporales que utilizará para acceder a Google Cloud Platform durante el transcurso del lab.

Lo que necesita

Para completar este lab, necesitará lo siguiente:

• Acceso a un navegador de Internet estándar. Se recomienda el navegador Chrome
• Tiempo para completar el lab

Nota: Si ya tiene un proyecto o una cuenta personal de GCP, no los use para este lab.

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.

Motor del agente

Vertex AI Agent Engine (antes conocido como LangChain en Vertex AI o Vertex AI Reasoning Engine) es un servicio completamente administrado de Google Cloud que permite a los desarrolladores implementar, administrar y escalar agentes de IA en producción.

Puedes obtener más información sobre sus beneficios en la documentación de Vertex AI Agent Engine.

Tarea 1: Instala el ADK y configura tu entorno

Nota: Se recomienda usar una ventana de incógnito en el navegador en la mayoría de los Qwiklabs para evitar confusiones entre tu cuenta de estudiante de Qwiklabs y otras cuentas que accedieron a Google Cloud. Si usas Chrome, la forma más sencilla de hacerlo es cerrar todas las ventanas de incógnito y, luego, hacer clic con el botón derecho en el botón Abrir la consola de Google Cloud en la parte superior del lab y seleccionar Abrir el vínculo en una ventana de incógnito.

Habilita las APIs recomendadas de Vertex AI

1. En este entorno de lab, la API de Vertex AI ya está habilitada 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. Con la ventana de la consola de Google Cloud seleccionada, abre Cloud Shell presionando la tecla G y, luego, la tecla S. También puedes hacer clic en el botón Activar Cloud Shell () en la parte superior derecha de la consola de Cloud.

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. En la terminal de Cloud Shell, ingresa lo siguiente para abrir el Editor de Cloud Shell en tu directorio principal:

   cloudshell workspace ~

6. Cierra cualquier instructivo adicional o panel de Gemini que aparezca en el lado derecho de la pantalla para tener más espacio en la ventana para tu editor de código.
7. Durante el resto de este lab, puedes trabajar en esta ventana como tu IDE con el Editor de Cloud Shell y la terminal de Cloud Shell.

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

1. Actualiza tu variable de entorno PATH e instala el ADK ejecutando los siguientes comandos en la terminal de Cloud Shell.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk

2. Pega los siguientes comandos en la terminal de Cloud Shell para copiar un archivo de un bucket de Cloud Storage y descomprimirlo, 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_to_agent_engine .

3. Instala los requisitos adicionales del lab con este código:

   python3 -m pip install -r adk_to_agent_engine/requirements.txt

4. Ejecuta los siguientes comandos para crear un archivo .env en el directorio adk_to_agent_engine. (Nota: Para ver un archivo oculto que comienza con un punto, puedes usar los menús del Editor de Cloud Shell para habilitar Ver > Toggle Hidden Files):

   cd ~/adk_to_agent_engine 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}}} MODEL=gemini-2.5-flash EOF

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 transcript_summarization_agent/.env

Tarea 2: Implementa en Agent Engine con el método de implementación de línea de comandos

La interfaz de línea de comandos del ADK proporciona accesos directos para implementar agentes en Agent Engine, Cloud Run y Google Kubernetes Engine (GKE). Puedes usar los siguientes comandos base para implementar en cada uno de estos servicios:

• adk deploy agent_engine (con sus argumentos de línea de comandos descritos en el decorador @deploy.command("agent_engine"))
• adk deploy cloud_run (con sus argumentos de línea de comandos descritos en el decorador @deploy.command("cloud_run"))
• adk deploy gke (con sus argumentos de línea de comandos descritos en el decorador @deploy.command("gke"))

El comando adk deploy agent_engine envuelve tu agente en una clase reasoning_engines.AdkApp y, luego, implementa esta app en el entorno de ejecución administrado de Agent Engine, que está listo para recibir consultas de agentes.

Cuando se implementa una AdkApp en Agent Engine, usa automáticamente un VertexAiSessionService para un estado de sesión persistente y administrado. Esto proporciona memoria conversacional de varios turnos sin ninguna configuración adicional. Para las pruebas locales, la aplicación usa de forma predeterminada un InMemorySessionService temporal.

Para implementar una app de Agent Engine con adk deploy agent_engine, completa los siguientes pasos:

1. En el directorio adk_to_agent_engine/transcript_summarization_agent, haz clic en el archivo agent.py para revisar las instrucciones de este agente de resumen simple.

2. Para implementar un agente, debes proporcionar sus requisitos. En el editor de Cloud Shell, haz clic con el botón derecho en el directorio transcript_summarization_agent. (Es posible que debas hacer clic en Allow para habilitar el menú de clic derecho).

3. Selecciona New File…

4. Asigna al archivo un nombre como el de un archivo de requisitos de Python estándar: requirements.txt.

5. Pega lo siguiente en el archivo:

   google-cloud-aiplatform[adk,agent_engines]==1.110.0

6. Guarda el archivo.

7. En la terminal de Cloud Shell, ejecuta el comando de implementación:

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   Puedes seguir el estado desde el archivo de registro que se vinculará desde el resultado del comando. Durante la implementación, se realizan los siguientes pasos:

   1. Se genera un conjunto de artefactos de forma local, que incluye lo siguiente:
      • *.pkl: un archivo pickle correspondiente a local_agent.
      • requirements.txt: este archivo de la carpeta del agente define los requisitos del paquete.
      • dependencies.tar.gz: un archivo tar que contiene paquetes adicionales.
   2. El paquete se sube a Cloud Storage (con un directorio definido, si se especifica) para organizar los artefactos.
   3. Los URI de Cloud Storage para los artefactos respectivos se especifican en PackageSpec.
   4. El servicio Vertex AI Agent Engine recibe la solicitud, crea contenedores y activa servidores HTTP en el backend.

   Nota: La implementación debería tardar unos 10 minutos, pero puedes continuar con este lab mientras se implementa.

   Cuestionario para realizar mientras se implementa tu agente

   Cada uno de los comandos adk deploy ... requiere que se establezcan ciertos argumentos. Para obtener los argumentos más actualizados, haz clic en los comandos vinculados en la lista que aparece en la parte superior de esta tarea y busca los argumentos marcados como "Obligatorio".

   Algunos argumentos obligatorios, como --project y --region de la implementación adk deploy agent_engine, pueden cargar sus valores desde el archivo .env del agente si está presente.

   Responde las siguientes preguntas en función de los argumentos de adk deploy agent_engine:

   Aspectos destacados del resultado esperado:

   Copying agent source code... Copying agent source code complete. Initializing Vertex AI... [...] Creating AgentEngine Create AgentEngine backing LRO: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480/operations/2777364189918789632 View progress and logs at https://console.cloud.google.com/logs/query?project=qwiklabs-gcp-04-f71a2270bd79 AgentEngine created. Resource name: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480 To use this AgentEngine in another session: agent_engine = vertexai.agent_engines.get('projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480') Cleaning up the temp folder: /tmp/agent_engine_deploy_src/20250813_175223

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

Tarea 3: Obtén y consulta un agente implementado en Agent Engine

Para consultar el agente, primero debes otorgarle la autorización para llamar a modelos a través de Vertex AI.

1. Para ver el agente de servicio y su rol asignado, navega a IAM en la consola.

2. Marca la casilla de verificación Incluir asignaciones de roles proporcionadas por Google.

3. Busca el agente de servicio de Reasoning Engine de AI Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) y haz clic en el ícono de lápiz de edición en la fila de este agente de servicio.

4. Haz clic en + Agregar otro rol.

5. En el campo Selecciona un rol, ingresa Usuario de Vertex AI. Si implementas un agente que usa herramientas para acceder a otros datos, también le otorgarás acceso a esos sistemas a este agente de servicio.

6. Guarda tus cambios.

7. De vuelta en el editor de Cloud Shell, dentro del directorio adk_to_agent_engine, abre el archivo query_agent_engine.py.

8. Revisa el código y los comentarios para ver lo que está haciendo.

9. Revisa la transcripción que se pasó al agente para evaluar si genera un resumen adecuado.

10. En la terminal de Cloud Shell, ejecuta el archivo desde el directorio adk_to_agent_engine con este comando:

    cd ~/adk_to_agent_engine/transcript_summarization_agent python3 query_agent_engine.py

    Resultado de ejemplo (el tuyo puede ser un poco diferente):

    [remote response] The user wants to buy a boat, and after being asked about the size, inquires how much boat $50,000 will purchase. The Virtual Agent responds that $50,000 will get a "very nice boat," to which the user agrees to proceed.

Haz clic en Revisar mi progreso para verificar el objetivo. Consultar a un agente.

Tarea 4: Ver y borrar agentes implementados en Agent Engine

1. Cuando tu agente haya completado su implementación, regresa a una pestaña del navegador que muestre la consola de Cloud y navega a Agent Engine buscándolo y seleccionándolo en la parte superior de la consola.

2. En el menú desplegable Región, asegúrate de que esté seleccionada tu ubicación para este lab ().

3. Verás el nombre visible de tu agente implementado. Haz clic en él para ingresar a su panel de supervisión.

4. Observa las pestañas Métricas y Sesión, que te brindarán información sobre cómo se usa tu agente.

5. Cuando quieras borrar tu agente, selecciona Detalles de la implementación en la parte superior de su panel de supervisión.

6. En la pestaña del navegador en la que se ejecuta la terminal de Cloud Shell, pega el siguiente comando, pero no lo ejecutes aún:

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

7. En el panel Deployment info de Agent Engine, copia el campo Name, que tendrá un formato como el siguiente: projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504.

8. Vuelve a la terminal de Cloud Shell y reemplaza el final del comando REPLACE_WITH_AE_ID por el nombre del recurso que copiaste.

9. Presiona Return para ejecutar el comando de borrado.

   Resultado de ejemplo:

   Deleting AgentEngine resource: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696 Delete AgentEngine backing LRO: projects/1029886909158/locations/us-central1/operations/2884525977596067840 AgentEngine resource deleted: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696

10. En la consola de Cloud, vuelve al panel de Agent Engine para ver que el agente se borró.

11. Para ver el código simple del SDK de Python para enumerar y borrar agentes, consulta el contenido del archivo adk_to_agent_engine/agent_engine_utils.py.

Haz clic en Revisar mi progreso para verificar el objetivo. Enumerar y borrar agentes.

¡Felicitaciones!

En este lab, aprendiste lo siguiente:

• Los beneficios de implementar agentes en Agent Engine
• Cómo otorgar los roles necesarios al agente de servicio de Reasoning Engine
• Cómo implementar un agente en Agent Engine con la interfaz de línea de comandos del ADK
• Cómo consultar un agente implementado en Agent Engine
• Cómo supervisar tus agentes implementados
• Cómo borrar agentes

Próximos pasos

Puedes obtener más información sobre la creación de agentes con el kit de desarrollo de agentes en otros labs de esta serie:

• Potencia a los agentes del ADK con herramientas.
• Crea sistemas multiagente con el ADK.
• Implementa agentes del ADK 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: 19 de agosto de 2025

Prueba más reciente del lab: 19 de agosto de 2025

Copyright 2020 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.