Verifica la exactitud de las declaraciones con un agente de IA del ADK y un modelo de Gemini

Nivel de programación: Avanzado
Duración: 30 minutos
Tipo de proyecto: Función personalizada

Descripción general

Una función personalizada de verificación de datos para Hojas de cálculo de Google que se usará como un proyecto de Apps Script vinculado potenciado por un agente de Vertex AI y un modelo de Gemini.

En este ejemplo, se muestra cómo puedes usar dos tipos potentes de recursos de IA directamente en tus hojas de cálculo de Google Sheets:

1. Agentes de IA para capacidades de razonamiento sofisticadas, de varios pasos y con varias herramientas, que usan agentes de ADK implementados en Vertex AI Agent Engine.
2. Modelos de IA para capacidades avanzadas de comprensión, generación y resumen con los modelos de Gemini de Vertex AI

Objetivos

• Comprende qué hace la solución.
• Comprende cómo se implementa la solución.
• Implementa el agente de Vertex AI.
• Configura la secuencia de comandos.
• Ejecuta la secuencia de comandos.

Acerca de esta solución

La función personalizada de Hojas de cálculo se llama FACT_CHECK y funciona como una solución integral. Analiza una declaración, fundamenta su respuesta con la información más reciente de la Web y devuelve el resultado en el formato que necesitas:

• Uso:
  • =FACT_CHECK("Your statement here") para obtener un resultado conciso y resumido.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") para un formato de salida específico.
• Justificación: Agente de IA del ADK del auditor de LLM (muestra de Python).
• Formato de salida: Modelo de Gemini

Esta solución solicita las APIs de REST de Vertex AI con UrlFetchApp.

Arquitectura

En el siguiente diagrama, se muestra la arquitectura de los recursos de Google Workspace y Google Cloud que usa la función personalizada.

Requisitos previos

Para usar esta muestra, necesitas cumplir con los siguientes requisitos previos:

• Una Cuenta de Google (es posible que las cuentas de Google Workspace requieran la aprobación del administrador)

• Un navegador web con acceso a Internet

• Requisitos previos del agente del ADK de LLM Auditor

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

Prepare el entorno

En esta sección, se muestra cómo crear y configurar un proyecto de Google Cloud.

Crea un proyecto de Google Cloud

Consola de Google Cloud

1. En la consola de Google Cloud, ve a Menú > IAM y administración > Crear un proyecto.

   Ir a Crear un proyecto

2. En el campo Nombre del proyecto, ingresa un nombre descriptivo para tu proyecto.

   Opcional: Para editar el ID del proyecto, haz clic en Editar. El ID del proyecto no se puede cambiar después de que se crea el proyecto. Por lo tanto, elige un ID que abarque tus necesidades durante todo el ciclo de vida del proyecto.

3. En el campo Ubicación, haz clic en Explorar para mostrar las posibles ubicaciones de tu proyecto. Luego, haga clic en Seleccionar.
   Precaución: ¿No encuentras tu organización de Google Workspace?
   Esto significa que no accediste a una cuenta de Google Workspace. Algunas de las funciones que se describen en la documentación para desarrolladores de Google Workspace solo están disponibles para los proyectos asociados a una organización.
4. Haz clic en Crear. La consola de Google Cloud te redireccionará a la página Panel y tu proyecto se creará en unos minutos.

gcloud CLI

En uno de los siguientes entornos de desarrollo, accede a Google Cloud CLI (gcloud):

• Cloud Shell: Para usar una terminal en línea con la CLI de gcloud ya configurada, activa Cloud Shell.
  Activa Cloud Shell
• Shell local: Para usar un entorno de desarrollo local, instala e inicializa la CLI de gcloud.
  Para crear un proyecto de Cloud, usa el comando gcloud projects create:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID configurando el ID del proyecto que deseas crear.

Habilita la facturación para el proyecto de Cloud

Si no puedes vincular una cuenta de facturación, no tienes los permisos necesarios para realizar este cambio. Para obtener más información, consulta Permisos necesarios para habilitar la facturación.

Consola de Google Cloud

1. En la consola de Google Cloud, ve a Facturación. Haz clic en Menú > Facturación > Mis proyectos.

   Ir a Facturación de Mis proyectos

2. En Selecciona una organización, elige la organización asociada con tu proyecto de Google Cloud.
3. En la fila del proyecto, abre el menú Acciones (), haz clic en Cambiar facturación y elige la cuenta de Facturación de Cloud.
4. Haz clic en Establecer cuenta.

gcloud CLI

1. Para enumerar las cuentas de facturación disponibles, ejecuta el siguiente comando:

   gcloud billing accounts list

2. Vincula una cuenta de facturación a un proyecto de Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Reemplaza lo siguiente:

   • PROJECT_ID es el ID del proyecto del proyecto de Cloud para el que deseas habilitar la facturación.
   • BILLING_ACCOUNT_ID es el ID de la cuenta de facturación que se vinculará con el proyecto de Google Cloud.

Habilita la API de Vertex AI

Consola de Google Cloud

1. En la consola de Google Cloud, habilita la API de Vertex AI.

   Habilitar las API

2. Confirma que habilitarás la API de Vertex AI en el proyecto de Cloud correcto y, luego, haz clic en Siguiente.

3. Confirma que habilitarás la API correcta y, luego, haz clic en Habilitar.

gcloud CLI

1. Si es necesario, configura el proyecto actual de Cloud como el que creaste con el comando gcloud config set project:

   gcloud config set project PROJECT_ID

   Reemplaza PROJECT_ID por el ID del proyecto del proyecto de Cloud que creaste.

2. Habilita la API de Vertex AI con el comando gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

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ú > 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.
   Nota: De forma predeterminada, Google crea un ID de cuenta de servicio único. Si quieres cambiar el ID, modifícalo en el campo ID de cuenta de servicio.
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. A continuación, crea una clave privada para la cuenta de servicio.

Crea una clave privada

Advertencia: Este ejemplo usa una clave de cuenta de servicio exportada para mayor simplicidad. 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 seguras de cuentas de servicio y las prácticas recomendadas, consulta Cuándo usar cuentas de servicio.

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

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 IA del ADK de LLM Auditor

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

2. Descarga este repositorio de GitHub

   Descargar

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. Crea un nuevo bucket de Cloud Storage 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 que creaste.
   3. PROJECT_LOCATION con la ubicación del proyecto de Cloud que creaste.

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 que creaste.
   3. PROJECT_LOCATION con la ubicación del proyecto de Cloud que creaste.

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, ya que lo necesitarás más adelante para configurar la función personalizada.

   python3 deployment/deploy.py --list

Revisa el código de muestra

De manera opcional, antes de crear la nueva hoja de cálculo, tómate un momento para revisar y familiarizarte con el código de muestra alojado en GitHub.

Ver en GitHub

Crea y configura una hoja de cálculo nueva

1. Haz clic en el siguiente botón y crea una copia completa de la hoja de cálculo de Hojas de cálculo de Google de ejemplo, incluido su proyecto de Apps Script vinculado al contenedor.

   Copia la hoja de cálculo de Hojas de cálculo de Google

2. En la hoja de cálculo que se creó, ve a Extensiones > Apps Script.

3. En el proyecto de Apps Script, ve a Configuración del proyecto, haz clic en Editar propiedades de la secuencia de comandos y, luego, en Agregar propiedad de la secuencia de comandos para agregar las siguientes propiedades de la secuencia de comandos:

   1. LOCATION con la ubicación del proyecto de Google Cloud creado en los pasos anteriores, como us-central1.
   2. GEMINI_MODEL_ID con el modelo de Gemini que quieras usar, como gemini-2.5-flash-lite.
   3. REASONING_ENGINE_ID con el ID del agente del ADK del Auditor de LLM implementado en pasos anteriores, como 1234567890
   4. 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 las secuencias de comandos.

Prueba la función personalizada

1. Ve a la hoja de cálculo recién creada.
2. Cambia las instrucciones en la columna A.
3. Las fórmulas de la columna B se ejecutan y, luego, muestran los resultados de la verificación de datos.

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 borrar el proyecto.

Próximos pasos

• Funciones personalizadas en Hojas de cálculo de Google
• Extensión de Hojas de cálculo de Google