Compila una app de Google Chat con un agente Agent2Agent

Versión preliminar de Vertex AI Agent Builder: El desarrollo y el uso de un agente Agent2Agent (A2A) se encuentran en versión preliminar. Consulta la documentación completa.

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 Agent2Agent (A2A). Desarrollas el agente con el Kit de desarrollo de agentes (ADK) y lo alojas en Vertex AI Agent Engine.

Nota: En Google Chat, los complementos aparecen para los usuarios como apps de Google Chat. También puedes compilar tu app de Chat con eventos de interacción de la API de Google Chat. Para obtener más información, consulta la descripción general de la extensión de Google Chat.

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 el ejemplo multiagente de LLM Auditor, que critica y revisa hechos con la fundamentación de Gemini y la Búsqueda de Google.

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 A2A 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 A2A 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 envía respuestas de forma asíncrona, ya que 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 A2A.
• 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 comprobar si un proyecto existente tiene la facturación habilitada, consulta Verificar el estado de facturación de tus proyectos. Para crear un proyecto y configurar la facturación, consulta Crear un proyecto de Google Cloud.
• Requisitos previos del agente ADK de LLM Auditor
  • Python 3.11+: para la instalación, siga las instrucciones en el sitio web oficial de Python.
  • Python Poetry: para la instalación, siga las instrucciones en el sitio web oficial de Poetry.
  • CLI de Google Cloud: para la instalación, siga las instrucciones en el sitio web oficial de Google Cloud.

Configura tu entorno

Habilita las APIs de Google Cloud

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

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

  Habilitar las API

Cómo configurar la pantalla de consentimiento de OAuth

Todas las aplicaciones que utilizan OAuth 2.0 requieren una configuración de pantalla de consentimiento. La configuración de la pantalla de consentimiento de OAuth de su aplicación define lo que se muestra a los usuarios y revisores de la aplicación, y registra su aplicación para que pueda publicarla más tarde.

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

   Ir a Branding

2. Si ya ha configurado Google Auth platform, puede configurar los siguientes ajustes de la pantalla de consentimiento de OAuth en Marca, Audiencia y Acceso a datos. Si ves un mensaje que dice Google Auth platform aún no configurado, haz clic en Comenzar:
1. En Información de la aplicación, en Nombre de la aplicación, ingrese un nombre para la aplicación.
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 ahora, puedes omitir la adición de ámbitos. En el futuro, cuando crees una aplicación para usarla fuera de tu organización de Google Workspace, deberás cambiar el Tipo de usuario a Externo. Luego agregue los alcances de autorización que requiere su aplicación. Para obtener más información, consulta la guía completa Configurar el consentimiento de OAuth.

Crear una cuenta de servicio en la consola de Google Cloud

Cree una nueva cuenta de servicio con el rol Vertex AI User siguiendo 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

2. Haga clic en Crear cuenta de servicio.
3. Complete los detalles de la cuenta de servicio y luego haga clic en Crear y continuar.
   Nota: De forma predeterminada, Google crea un ID de cuenta de servicio único. Si desea cambiar el ID, modifíquelo en el campo ID de la cuenta de servicio.
4. Opcional: Asigne roles a su cuenta de servicio para otorgar acceso a los recursos de su proyecto de Google Cloud. Para obtener más detalles, consulte Otorgar, cambiar y revocar acceso a los recursos.
5. Haz clic en Continuar.
6. Opcional: Ingrese usuarios o grupos que puedan administrar y realizar acciones con esta cuenta de servicio. Para obtener más detalles, consulte Administrar la suplantación de cuentas de servicio.
7. Haz clic en Listo. Anote 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: Asigne roles a su cuenta de servicio para otorgar acceso a los recursos de su proyecto de Google Cloud. Para obtener más detalles, consulte Otorgar, cambiar y revocar acceso a los recursos.

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

Crea una clave privada

Advertencia: Este ejemplo utiliza una clave de cuenta de servicio exportada para simplificar. No se recomienda exportar una clave privada en producción porque no debe almacenarse en una ubicación insegura, como el control de origen.

Para obtener más información sobre las implementaciones de cuentas de servicio seguras y las mejores prácticas, consulte Elegir cuándo usar cuentas de servicio.

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

1. En la consola de Google Cloud, ve a Menú > 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 A2A

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 muestras del ADK con este botón:

   Descarga adk-samples

3. En tu entorno de desarrollo local preferido, extrae el archivo descargado y abre el directorio adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. Actualiza la implementación para implementar el agente del ADK como un agente remoto de A2A:

   1. pyproject.toml: Agrega dependencias del ADK y del SDK de A2A en el grupo de implementación.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml

      Ver en GitHub
      [project]
      name = "llm-auditor"
      version = "0.1.0"
      description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
      authors = [
          { name = "Chun-Sung Ferng", email = "[e-mail]" },
          { name = "Cyrus Rashtchian", email = "[e-mail]" },
          { name = "Da-Cheng Juan", email = "[e-mail]" },
          { name = "Ivan Kuznetsov", email = "[e-mail]" },
      ]
      license = "Apache License 2.0"
      readme = "README.md"
      
      [tool.poetry.dependencies]
      python = "^3.10"
      google-adk = "^1.0.0"
      google-cloud-aiplatform = { extras = [
          "adk",
          "agent-engines",
      ], version = "^1.93.0" }
      google-genai = "^1.9.0"
      pydantic = "^2.10.6"
      python-dotenv = "^1.0.1"
      
      [tool.poetry.group.dev]
      optional = true
      
      [tool.poetry.group.dev.dependencies]
      google-adk = { version = "^1.0.0", extras = ["eval"] }
      pytest = "^8.3.5"
      pytest-asyncio = "^0.26.0"
      
      [tool.poetry.group.deployment]
      optional = true
      
      [tool.poetry.group.deployment.dependencies]
      absl-py = "^2.2.1"
      google-adk = "^1.0.0"
      a2a-sdk = "^0.3.0"
      
      [build-system]
      requires = ["poetry-core>=2.0.0,<3.0.0"]
      build-backend = "poetry.core.masonry.api"

   2. deployment/deploy.py: Reemplaza la implementación de la app del ADK por un agente y una tarjeta de A2A.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py

      Ver en GitHub
      # Copyright 2025 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.
      
      """Deployment script for LLM Auditor."""
      
      import os
      
      from absl import app
      from absl import flags
      from dotenv import load_dotenv
      from llm_auditor.agent import root_agent
      import vertexai
      from vertexai import agent_engines
      
      # A2A wrapping
      from a2a.types import AgentSkill
      from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
      from google.adk.runners import InMemoryRunner
      from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
      from vertexai.preview.reasoning_engines import A2aAgent
      
      FLAGS = flags.FLAGS
      flags.DEFINE_string("project_id", None, "GCP project ID.")
      flags.DEFINE_string("location", None, "GCP location.")
      flags.DEFINE_string("bucket", None, "GCP bucket.")
      flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")
      
      flags.DEFINE_bool("list", False, "List all agents.")
      flags.DEFINE_bool("create", False, "Creates a new agent.")
      flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
      flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])
      
      
      def create() -> None:
          """Creates an agent engine for LLM Auditor."""
          agent_card = create_agent_card(
              agent_name=root_agent.name,
              description=root_agent.description,
              skills=[AgentSkill(
                  id='audit_llm_output',
                  name='Audit LLM Output',
                  description='Critiques and revises outputs from large language models.',
                  tags=['LLM', 'Audit', 'Revision'],
                  examples=[
                      'The earth is flat.',
                      'The capital of France is Berlin.',
                      'The last winner of the Super Bowl was the New England Patriots in 2020.',
                  ],
              )]
          )
          a2a_agent = A2aAgent(
              agent_card=agent_card,
              agent_executor_builder=lambda: A2aAgentExecutor(
                  runner=InMemoryRunner(
                      app_name=root_agent.name,
                      agent=root_agent,
                  )
              )
          )
          a2a_agent.set_up()
      
          remote_agent = agent_engines.create(
              a2a_agent,
              display_name=root_agent.name,
              requirements=[
                      "google-adk (>=0.0.2)",
                      "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                      "google-genai (>=1.5.0,<2.0.0)",
                      "pydantic (>=2.10.6,<3.0.0)",
                      "absl-py (>=2.2.1,<3.0.0)",
                      "a2a-sdk>=0.3.22",
                      "uvicorn",
              ],
              # In-memory runner
              max_instances=1,
              env_vars ={
                  "NUM_WORKERS": "1"
              },
              extra_packages=["./llm_auditor"],
          )
          print(f"Created remote agent: {remote_agent.resource_name}")
      
      
      def delete(resource_id: str) -> None:
          remote_agent = agent_engines.get(resource_id)
          remote_agent.delete(force=True)
          print(f"Deleted remote agent: {resource_id}")
      
      
      def list_agents() -> None:
          remote_agents = agent_engines.list()
          TEMPLATE = '''
      {agent.name} ("{agent.display_name}")
      - Create time: {agent.create_time}
      - Update time: {agent.update_time}
      '''
          remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
          print(f"All remote agents:\n{remote_agents_string}")
      
      def main(argv: list[str]) -> None:
          del argv  # unused
          load_dotenv()
      
          project_id = (
              FLAGS.project_id
              if FLAGS.project_id
              else os.getenv("GOOGLE_CLOUD_PROJECT")
          )
          location = (
              FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
          )
          bucket = (
              FLAGS.bucket if FLAGS.bucket
              else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
          )
      
          print(f"PROJECT: {project_id}")
          print(f"LOCATION: {location}")
          print(f"BUCKET: {bucket}")
      
          if not project_id:
              print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
              return
          elif not location:
              print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
              return
          elif not bucket:
              print(
                  "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
              )
              return
      
          vertexai.init(
              project=project_id,
              location=location,
              staging_bucket=f"gs://{bucket}",
          )
      
          if FLAGS.list:
              list_agents()
          elif FLAGS.create:
              create()
          elif FLAGS.delete:
              if not FLAGS.resource_id:
                  print("resource_id is required for delete")
                  return
              delete(FLAGS.resource_id)
          else:
              print("Unknown command")
      
      
      if __name__ == "__main__":
          app.run(main)

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

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

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

8. 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 A2A.

   Abre el proyecto

2. Haz clic en 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ú > IAM y administración > Configuración.

   Ir a Configuración de IAM y administración

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

7. En su proyecto de Apps Script, haga 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, pegue el número de proyecto de Google Cloud copiado en los pasos anteriores.

10. Haz clic en Establecer el proyecto. El proyecto Cloud y el proyecto Apps Script ahora están conectados.

Crear una implementación de prueba

Necesita un ID de implementación para este proyecto de Apps Script, para poder usarlo en el siguiente paso.

Para obtener el ID de implementación del cabezal, haga lo siguiente:

1. En el proyecto Apps Script de la aplicación Chat, haga clic en Implementar > Probar implementaciones.
2. En ID de implementación principal, haga clic en Copiar.
3. Haz clic en Listo.

Configurar la aplicación Chat

Usando su implementación de Apps Script, siga estos pasos para implementar la aplicación 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. Haga clic en Configuración y configure la aplicación Chat:

   1. En el campo Nombre de la aplicación, ingrese A2A Quickstart.
   2. En el campo URL de avatar, ingrese https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. En el campo Descripción, ingresa A2A Quickstart.
   4. En Funcionalidad, seleccione 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 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.

   Nota: Si no ves tu app de Chat en la lista de resultados, asegúrate de haber incluido tu cuenta de Google Workspace en la configuración de Visibilidad de la página Configuración de la API de Chat en la consola de Google Cloud.

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 las respuestas de los subagentes Crítico y Revisor.

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

Solucionar problemas

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

Si bien 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.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo en el proyecto. Si utilizaste un proyecto existente para este instructivo, cuando lo borres, también borrarás cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URLs que utilizan el ID del proyecto, como una URL en appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de todo el proyecto.

Si planeas explorar varios instructivos y guías de inicio rápido, la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

1. En la consola de Google Cloud, 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 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 de Agent2UI
• 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