Compila una app de Google Chat con un agente de IA del ADK

En esta página, se explica cómo compilar un complemento de Google Workspace que funciona en Google Chat y que interactúa con un agente de IA del Kit de desarrollo de agentes (ADK) alojado en Vertex AI Agent Engine.

Los agentes de IA perciben su entorno de forma autónoma, razonan y ejecutan acciones complejas de varios pasos para lograr un objetivo definido. En este instructivo, implementarás la muestra de varios agentes del ADK LLM Auditor que critica y revisa hechos con la fundamentación de Gemini y la Búsqueda de Google.

Muestra de LLM Auditor multiagente como app de chat.

En el siguiente diagrama, se muestran la arquitectura y el patrón de mensajería:

Arquitectura de una app de chat implementada con un agente de IA del ADK.

En el diagrama anterior, un usuario que interactúa con una app de Chat implementada con un agente de IA del ADK tiene el siguiente flujo de información:

  1. Un usuario envía un mensaje a una app de Chat, ya sea en un mensaje directo o en un espacio de Chat.
  2. La lógica de la app de Chat que se implementa en Apps Script o como un servidor web con extremos HTTP recibe y procesa el mensaje.
  3. El agente de IA que se implementa con el ADK y se aloja con Vertex AI Agent Engine recibe y procesa la interacción.
  4. De manera opcional, la app de Chat o el agente de IA pueden integrarse con los servicios de Google Workspace, como Calendar o Hojas de cálculo, o con otros servicios de Google, como Google Maps o YouTube.
  5. La app de Chat envía respuestas de forma asíncrona con la API de Google Chat para comunicar el progreso del agente de IA.
  6. Las respuestas se entregan al usuario.

Objetivos

  • Configura el entorno.
  • Implementa el agente de IA del ADK.
  • Implementa la app de Chat.
  • Configura la app de Chat.
  • Prueba la app de Chat.

Requisitos previos

Configura tu entorno

Habilita las APIs de Google Cloud

Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

  • En la consola de Google Cloud, habilita las APIs de Google Chat, Vertex AI y Cloud Resource Manager.

    Habilitar las API

Cómo configurar la pantalla de consentimiento de OAuth

Todas las apps que usan OAuth 2.0 requieren una configuración de pantalla de consentimiento. Configurar la pantalla de consentimiento de OAuth de tu app define lo que se muestra a los usuarios y revisores de apps, y registra tu app para que puedas publicarla más adelante.

  1. En la Consola de APIs de Google, ve a Menú > Plataforma de autenticación de Google > Información de la marca.

    Ir a Información de la marca

  2. Si ya configuraste la plataforma de autenticación de Google, puedes configurar los siguientes parámetros de configuración de la pantalla de consentimiento de OAuth en Información de la marca, Público y Acceso a los datos. Si ves un mensaje que dice Aún no se configuró la plataforma de autenticación de Google, haz clic en Comenzar:
    1. En Información de la aplicación, en Nombre de la aplicación, ingresa un nombre para la app.
    2. En Correo electrónico de asistencia al usuario, elige una dirección de correo electrónico de asistencia en la que los usuarios puedan comunicarse contigo si tienen preguntas sobre su consentimiento.
    3. Haz clic en Siguiente.
    4. En Público, selecciona Interno.
    5. Haz clic en Siguiente.
    6. En Información de contacto, ingresa una Dirección de correo electrónico en la que puedas recibir notificaciones sobre cualquier cambio en tu proyecto.
    7. Haz clic en Siguiente.
    8. En Finalizar, revisa la Política de Datos del Usuario de los Servicios de las APIs de Google y, si estás de acuerdo, selecciona Acepto la Política de Datos del Usuario de los Servicios de las APIs de Google.
    9. Haz clic en Continuar.
    10. Haz clic en Crear.
  3. Por ahora, puedes omitir la adición de permisos. En el futuro, cuando crees una app para usar fuera de tu organización de Google Workspace, debes cambiar el Tipo de usuario a Externo. Luego, agrega los permisos de autorización que requiere tu app. Para obtener más información, consulta la guía completa Configura el consentimiento de OAuth guide.

Crea una cuenta de servicio en la consola de Google Cloud

Para crear una cuenta de servicio nueva con el rol Vertex AI User, sigue estos pasos:

Consola de Google Cloud

  1. En la consola de Google Cloud, ve a Menú > IAM y administración > Cuentas de servicio.

    Ir a Cuentas de servicio

    Los pasos restantes aparecen en la consola de Google Cloud.

  2. Selecciona un proyecto de Google Cloud.
  3. Haga clic en Crear cuenta de servicio.
  4. Ingresa un nombre de cuenta de servicio para mostrar en la consola de Google Cloud.
  5. Si no quieres configurar los controles de acceso ahora, haz clic en Listo para terminar de crear la cuenta de servicio. Para establecer controles de acceso ahora, haz clic en Crear y continuar y continúa con el siguiente paso.
  6. Opcional: Asigna roles a tu cuenta de servicio para otorgar acceso a los recursos de tu proyecto de Google Cloud, además de los recursos de Google Workspace. Para obtener más detalles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
  7. Haz clic en Continuar.
  8. Opcional: Ingresa los usuarios o grupos que pueden administrar y realizar acciones con esta cuenta de servicio. Para obtener más detalles, consulta Identidad temporal como cuenta de servicio.
  9. Haz clic en Listo para terminar de crear la cuenta de servicio.

    Toma nota de la dirección de correo electrónico de la cuenta de servicio.

gcloud CLI

  1. Crea la cuenta de servicio: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. Opcional: Asigna roles a tu cuenta de servicio para otorgar acceso a los recursos de tu proyecto de Google Cloud, además de los recursos de Google Workspace. Para obtener más detalles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

La cuenta de servicio aparece en la página de cuentas de servicio.

Crea una clave privada

Para crear y descargar una clave privada para la cuenta de servicio, sigue estos pasos:

  1. En la consola de Google Cloud, ve a Menú > IAM y administración > Cuentas de servicio.

    Ir a Cuentas de servicio

    Los pasos restantes aparecen en la consola de Google Cloud.

  2. Selecciona un proyecto de Google Cloud.
  3. Haz clic en la dirección de correo electrónico de la cuenta de servicio para la que quieres crear una clave.
  4. Haz clic en la pestaña Claves.
  5. Haz clic en el menú desplegable Agregar clave y, luego, selecciona Crear clave nueva.
  6. Selecciona JSON como el tipo de clave y, luego, haz clic en Crear.

    Ya se generó y descargó el nuevo par de claves pública/privada en tu equipo como un archivo de claves de cuenta de servicio. Guarda el archivo JSON descargado como credentials.json en tu directorio de trabajo. Este archivo es la única copia de esta clave. Después de descargar el archivo de claves, no puedes volver a descargarlo. Para obtener información sobre cómo almacenar tu clave de forma segura, consulta Prácticas recomendadas para administrar claves de cuentas de servicio.

Para obtener más información sobre las cuentas de servicio, consulta Cuentas de servicio en la documentación de IAM de Google Cloud.

Implementa el agente de IA del ADK

  1. Abre la muestra de LLM Auditor en Vertex AI Agent Garden:

    Abrir la muestra

  2. Haz clic en Implementar.

  3. Si se te solicita, selecciona tu proyecto de Google Cloud.

  4. Haz clic en Implementar en Cloud Shell.

  5. Si se te solicita, haz clic en Autorizar y sigue el flujo de OAuth para Cloud Shell.

  6. Cuando Cloud Shell esté completamente cargado, presiona Intro para ejecutar la línea de comandos precargada y comenzar la implementación.

  7. Si se te solicita que ingreses la región, presiona Intro para usar la predeterminada.

  8. Cuando se complete, ve a Vertex AI Agent Engine:

    Abrir Vertex AI Agent Engine

  9. Haz clic en Ícono para crear una copia para copiar el nombre del recurso del agente recién implementado de la tabla.

Crea y configura el proyecto de la app de Chat

  1. Haz clic en el siguiente botón para abrir el proyecto de Apps Script de Guía de inicio rápido del agente de IA del ADK.

    Abre el proyecto

  2. Haz clic en Descripción general > Ícono para crear una copia Crear una copia.

  3. En tu proyecto de Apps Script, haz clic en El ícono de configuración del proyecto Configuración del proyecto > Editar propiedades de la secuencia de comandos > Agregar propiedad de la secuencia de comandos para agregar las siguientes propiedades de la secuencia de comandos:

    1. REASONING_ENGINE_RESOURCE_NAME con el nombre del recurso del agente de Vertex AI copiado en los pasos anteriores
    2. SERVICE_ACCOUNT_KEY con la clave JSON de la cuenta de servicio descargada en los pasos anteriores, como { ... }

  4. Haz clic en Guardar las propiedades de las secuencias de comandos

  5. En la Consola de APIs de Google, ve a Menú > IAM y administración > Configuración.

    Ir a Configuración de IAM y administrador

  6. En el campo Número de proyecto, copia el valor.

  7. En tu proyecto de Apps Script, haz clic en El ícono de configuración del proyecto Configuración del proyecto.

  8. En Proyecto de Google Cloud, haz clic en Cambiar proyecto.

  9. En Número de proyecto de Google Cloud, pega el número de proyecto de Google Cloud copiado en los pasos anteriores.

  10. Haz clic en Establecer el proyecto. Ahora, el proyecto de Cloud y el proyecto de Apps Script están conectados.

Crea una implementación de prueba

Necesitas un ID de implementación para este proyecto de Apps Script, de modo que puedas usarlo en el siguiente paso.

Para obtener el ID de implementación principal, haz lo siguiente:

  1. En el proyecto de Apps Script de la app de Chat, haz clic en Implementar > Implementaciones de prueba.
  2. En ID de implementación principal, haz clic en Ícono para crear una copia Copiar.
  3. Haz clic en Listo.

Configura la app de Chat

Con tu implementación de Apps Script, sigue estos pasos para implementar la app de Google Chat para realizar pruebas:

  1. En la Consola de APIs, busca Google Chat API, y haz clic en Google Chat API.
  2. Haz clic en Administrar.

  3. Haz clic en Configuración y configura la app de Chat:

    1. En el campo Nombre de la aplicación, ingresa ADK Quickstart.
    2. En el campo URL del avatar, ingresa https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. En el campo Descripción, ingresa ADK Quickstart.
    4. En Funcionalidad, selecciona Unirse a espacios y conversaciones grupales.
    5. En Configuración de la conexión, selecciona Proyecto de Apps Script.
    6. En el campo ID de implementación, pega el ID de implementación principal que copiaste anteriormente.
    7. En Visibilidad, selecciona Personas y grupos específicos de tu dominio y, luego, ingresa tu correo electrónico.

  4. Haz clic en Guardar.

La app de Chat está lista para responder a los mensajes.

Prueba la app de Chat

Para probar tu app de Chat, abre un espacio de mensajes directos con la app de Chat y envía un mensaje:

  1. Abre Google Chat con la cuenta de Google Workspace que proporcionaste cuando te agregaste como verificador de confianza.

    Ve a Google Chat

  2. Haz clic en Nuevo chat.
  3. En el campo Agregar 1 o más personas, escribe el nombre de tu app de Chat.

  4. Selecciona tu app de Chat en los resultados. Se abrirá un mensaje directo.

  5. En el nuevo mensaje directo con la app, escribe The Eiffel Tower was completed in 1900 y presionaenter.

    La app de Chat responde con respuestas de subagentes Critic y Reviser.

Para agregar verificadores de confianza y obtener más información sobre las pruebas de funciones interactivas, consulta Prueba funciones interactivas para apps de Google Chat.

Solucionar problemas

Cuando una app o tarjeta de Google Chat muestra un error, la interfaz de Chat muestra un mensaje que dice "Se produjo un error" o "No se pudo procesar la solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app o tarjeta de Chat produce un resultado inesperado; por ejemplo, es posible que no aparezca un mensaje de tarjeta.

Aunque es posible que no se muestre un mensaje de error en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando se activa el registro de errores para las apps de Chat. Para obtener ayuda para ver, depurar y corregir errores, consulta Soluciona y corrige errores de Google Chat.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este instructivo, te recomendamos que borres el proyecto de Cloud.

  1. En la Consola de APIs de Google, ve a la página Administrar recursos. Haz clic en Menú > IAM y administración > Administrar recursos.

    Ir al administrador de recursos

  2. En la lista de proyectos, selecciona 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 borrar el proyecto.