Compila una app de Google Chat con un agente Agent2UI

En esta página, se explica cómo compilar un complemento de Google Workspace que funcione en Google Chat y se conecte con un agente de IA que use el protocolo Agent2UI (A2UI). Desarrollas el agente con el Kit de desarrollo de agentes (ADK) y lo alojas en Vertex AI Agent Engine.

Los agentes de IA perciben su entorno, razonan y ejecutan acciones complejas de varios pasos de forma autónoma para lograr un objetivo definido. En este instructivo, implementarás un agente de IA básico que devuelve información de perfil estática recuperada de una herramienta.

A2UI permite que los agentes de IA generen IUs interactivas, enriquecidas y adaptables que se renderizan de forma nativa. Luego, puedes enfocarte en la lógica de los agentes de IA, no en las IU.

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

En el diagrama, un usuario que interactúa con una app de chat implementada con un agente de A2UI 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 A2UI alojado 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 Calendario o Hojas de cálculo, o con otros servicios de Google, como Google Maps o YouTube.
5. La app de Chat genera y envía respuestas adaptativas de forma asíncrona, y usa 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 A2UI.
• Implementa la app de Chat.
• Configura la app de Chat.
• Prueba la app de Chat.

Requisitos previos

• Una cuenta de Google Workspace para empresas o Enterprise con acceso a Google Chat
• Un proyecto de Google Cloud con facturación habilitada. Para verificar que un proyecto existente tenga habilitada la facturación, consulta Verifica el estado de facturación de tus proyectos. Para crear un proyecto y configurar la facturación, consulta Crea un proyecto de Google Cloud.
• Python 3.11 y versiones posteriores: Para la instalación, sigue las instrucciones del sitio web oficial de Python.
• Python Poetry: Para la instalación, sigue las instrucciones en el sitio web oficial de Poetry.
• Google Cloud CLI: Para la instalación, sigue las instrucciones del sitio web oficial de Google Cloud.

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. Cuando configuras la pantalla de consentimiento de OAuth de tu app, defines lo que se muestra a los usuarios y revisores de apps, y registras tu app para que puedas publicarla más adelante.

1. En la consola de Google Cloud, ve a Menú menu > Google Auth platform > Branding.

   Ir a Branding

2. Si ya configuraste el Google Auth platform, puedes configurar los siguientes parámetros de configuración de la pantalla de consentimiento de OAuth en Branding, Audience y Data Access. Si ves un mensaje que dice Google Auth platform aún no se configuró, haz clic en Comenzar:
1. En Información de la app, en Nombre de la app, 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 a 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 la aceptas, 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 el momento, puedes omitir la adición de permisos. En el futuro, cuando crees una app para usarla fuera de tu organización de Google Workspace, deberás 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.

Crea una cuenta de servicio en la consola de Google Cloud

Sigue estos pasos para crear una cuenta de servicio nueva con el rol Vertex AI User:

Consola de Google Cloud

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

   Ir a Cuentas de servicio

2. Haga clic en Crear cuenta de servicio.
3. Completa los detalles de la cuenta de servicio y, luego, haz clic en Crear y continuar.
4. Opcional: Asigna roles a tu cuenta de servicio para otorgar acceso a los recursos de tu proyecto de Google Cloud. Para obtener más detalles, consulta Otorga, cambia y revoca el acceso a los recursos.
5. Haz clic en Continuar.
6. Opcional: Ingresa los usuarios o grupos que pueden administrar esta cuenta de servicio y realizar acciones con ella. Para obtener más detalles, consulta Administra la suplantación de identidad de cuentas de servicio.
7. Haz clic en Listo. 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. Para obtener más detalles, consulta Otorga, cambia y revoca el acceso a los recursos.

La cuenta de servicio aparecerá 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ú menu > IAM y administración > Cuentas de servicio.

   Ir a Cuentas de servicio

2. Selecciona tu cuenta de servicio.
3. Haz clic en Claves > Agregar clave > Crear clave nueva.
4. Selecciona JSON y, luego, haz clic en Crear.

   Se generará y descargará el nuevo par de claves pública/privada en tu equipo como un archivo nuevo. Guarda el archivo JSON descargado como credentials.json en tu directorio de trabajo. Este archivo es la única copia de esta clave. Para obtener información sobre cómo almacenar tu clave de forma segura, consulta Cómo administrar claves para cuentas de servicio.

5. Haz clic en Cerrar.

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 A2UI

1. Si aún no lo hiciste, autentícate con tu cuenta de Google Cloud y configura Google Cloud CLI para usar tu proyecto de Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Reemplaza PROJECT_ID por el ID del proyecto de Cloud.

2. Descarga el repositorio de GitHub de googleworkspace/add-ons-samples con este botón:

   Descargar el repositorio

3. En tu entorno de desarrollo local preferido, extrae el archivo descargado y abre el directorio add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

4. Crea un bucket de Cloud Storage nuevo dedicado al agente del ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Reemplaza lo siguiente:

   1. CLOUD_STORAGE_BUCKET_NAME con un nombre de bucket único que desees usar.
   2. PROJECT_ID por el ID del proyecto de Cloud.
   3. PROJECT_LOCATION por la ubicación de tu proyecto de Cloud

5. Configura las siguientes variables de entorno:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   Reemplaza lo siguiente:

   1. CLOUD_STORAGE_BUCKET_NAME por el nombre del bucket que creaste.
   2. PROJECT_ID por el ID del proyecto de Cloud.
   3. PROJECT_LOCATION con la ubicación de tu proyecto de Cloud

6. Instala e implementa el agente del ADK desde el entorno virtual.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Recupera el ID del agente. La necesitarás más adelante, cuando configures la app de Chat.

   python3 deployment/deploy.py --list

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 la Guía de inicio rápido del agente de IA de A2UI.

   Abre el proyecto

2. Haz clic en info_outline Descripción general > Crear una copia.

3. En tu proyecto de Apps Script, haz clic en 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 por el nombre del recurso del agente de Vertex AI que copiaste en los pasos anteriores
   2. SERVICE_ACCOUNT_KEY con la clave JSON de la cuenta de servicio que se descargó en los pasos anteriores, como { ... }.

4. Haz clic en Guardar las propiedades de la secuencia de comandos.

5. En la consola de Google Cloud, ve a Menú menu > IAM y administración > Configuración.

   Ir a Configuración de IAM y administrador

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

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

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

9. En Número de proyecto de GCP, pega el número de proyecto de Google Cloud que copiaste 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 la 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 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, busca Google Chat API y haz clic en API de Google Chat.
2. Haz clic en Administrar.

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

   1. En el campo Nombre de la app, ingresa A2UI 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 A2UI Quickstart.
   4. En Funcionalidad, selecciona Unirse a espacios y conversaciones grupales.
   5. En Configuración de 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 escribe tu correo electrónico.

4. Haz clic en Guardar.

La app de Chat está lista para responder 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.

   Ir a Google Chat

2. Haz clic en add Nuevo chat.
3. En el campo Agrega 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 Hello! y presiona enter.

   La app de Chat responde con un mensaje de saludo y una tarjeta que contiene el nombre del perfil, la imagen y el botón de LinkedIn.

6. Actualiza la implementación del agente de la A2UI para que también devuelva el título del perfil.

   En tu entorno de desarrollo local, abre el archivo a2ui/agent.py y quita la marca de comentario de la línea en la herramienta que agrega el título a los datos devueltos.

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   Ver en GitHub
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. Actualice el ADK previamente implementado con la nueva versión de la implementación.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   Reemplace RESOURCE_ID con el nombre del recurso del agente Vertex AI copiado en los pasos anteriores.

8. En el mensaje directo con la aplicación, escribe Hello again! y presiona enter.

   La aplicación Chat responde a un mensaje con un texto y una tarjeta que contiene el título del perfil.

Para agregar evaluadores de confianza y obtener más información sobre cómo probar funciones interactivas, consulta Probar funciones interactivas para aplicaciones de Google Chat.

Solucionar problemas

Cuando una aplicación o una tarjeta de Google Chat devuelve un error, la interfaz de Chat muestra un mensaje que dice "Algo salió mal". o "No se puede procesar su solicitud". A veces, la interfaz de chat no muestra ningún mensaje de error, pero la aplicación o la tarjeta de chat producen 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 interfaz de chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarlo a corregir errores cuando el registro de errores para las aplicaciones de chat está activado. Para obtener ayuda para ver, depurar y corregir errores, consulta Solucionar y corregir 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 Google Cloud, ve a la página Administrar recursos. Haz clic en Menú menu > 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 delete.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

Temas relacionados

• Compila una app de Google Chat con un agente de IA de ADK
• Crea una app de Google Chat con un agente A2A
• Verifica la veracidad de las afirmaciones con un agente de IA del ADK y un modelo de Gemini
• Planifica viajes con un agente de IA accesible en todo Google Workspace
• Integra conceptos básicos de la IA en apps de Chat
• Responde preguntas en función de conversaciones de Chat con una app de Chat basada en IA de Gemini
• Responde a incidentes con Google Chat, Vertex AI, Apps Script y autenticación de usuarios
• Administra proyectos con Google Chat, Vertex AI y Firestore