Configura los requisitos previos para las tareas de enriquecimiento

Antes de crear tareas de enriquecimiento en Knowledge Studio, es posible que debas configurar varios componentes de infraestructura subyacentes según tu arquitectura de seguridad y las fuentes de datos de destino.

En esta guía, se describe cómo configurar cuentas de servicio administradas por el cliente, proveedores de autenticación de terceros, buckets de Cloud Storage y vistas de Cloud Logging.

En la siguiente tabla, se describen los parámetros de configuración de requisitos previos y cuándo debes configurarlos:

Función de configuración Cuándo configurar
APIs de Google Cloud Obligatorio. Debes habilitar las APIs de Google Cloud subyacentes para ejecutar flujos de trabajo de enriquecimiento.
Cuenta de servicio administrada por el cliente Quieres restringir el acceso de lectura y escritura en tus conjuntos de datos de destino.
Roles de Identity and Access Management (IAM) de los usuarios Debes otorgar permisos a los administradores y revisores de flujos de trabajo para que generen y aprueben metadatos.
Proveedores de autenticación de terceros Te conectas a fuentes de conocimiento de terceros (como Microsoft SharePoint, Atlassian Confluence o GitHub).
Buckets de Cloud Storage Estás transfiriendo contexto empresarial no estructurado (como archivos PDF, Markdown y CSV) y conjuntos de datos de evaluación.
Conjuntos de datos de evaluación Quieres proporcionar consultas de origen y conjuntos de datos de referencia para hacer un seguimiento activo de la exactitud del agente.
Trazas de agentes para el autoaprendizaje Quieres que el agente de enriquecimiento analice automáticamente las interacciones de los agentes de Gemini Enterprise downstream.
Generación de perfiles y estadísticas de datos (recomendado) Quieres mejorar la calidad del enriquecimiento generando perfiles estadísticos y estadísticas de IA de referencia en las tablas que se usan con frecuencia.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Detalles de las APIs requeridas

Para configurar y ejecutar tareas de enriquecimiento, las APIs habilitadas realizan las siguientes funciones:

Nombre de la API Identificador de servicio Propósito en los flujos de trabajo de enriquecimiento
API de Dataplex dataplex.googleapis.com Es la API del plano de control principal. Administra EnrichmentTask, EnrichmentRun, conjuntos de contexto, Change Requests y EnrichmentChatService.
API de BigQuery bigquery.googleapis.com Es obligatorio para analizar esquemas de tablas, transferir el historial de ejecución de SQL y consultar tablas de seguimiento de análisis de agentes de BigQuery.
API de Cloud Storage storage.googleapis.com Es obligatorio para transferir conjuntos de evaluación y administrar muestras de conjuntos de datos de evaluación.
API de Service Account Credentials de IAM iamcredentials.googleapis.com Es necesario para autenticar de forma segura el agente de ejecución y otorgar credenciales de corta duración (SLC) durante las tareas.

Configura una cuenta de servicio administrada por el cliente

Las tareas de enriquecimiento usan una cuenta de servicio administrada por el cliente para ejecutar operaciones. Esto te permite restringir el acceso de lectura y escritura en tus conjuntos de datos de destino.

  1. Cree la cuenta de servicio.

    Para crear una cuenta de servicio, debes ser propietario del proyecto (roles/owner) o editor (roles/editor), o tener el rol de administrador de cuentas de servicio (roles/iam.serviceAccountAdmin).

    Una cuenta de servicio dedicada aísla tus operaciones de enriquecimiento, lo que te permite otorgar solo los permisos de lectura y escritura específicos necesarios para estas tareas sin afectar otras cargas de trabajo.

    Para crear una cuenta de servicio, sigue estos pasos:

    Google Cloud CLI

    Para crear una cuenta de servicio, usa el comando gcloud iam service-accounts create:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Método HTTP y URL: 

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    Cuerpo JSON de la solicitud:

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

  2. Otorga los roles de IAM necesarios a nivel de recurso a la cuenta de servicio de ejecución en tus permisos de destino:

    • Editor del catálogo de Dataplex (roles/dataplex.catalogEditor) y Visualizador del catálogo de Dataplex (roles/dataplex.catalogViewer): Permite que el agente inspeccione los metadatos del catálogo, cree entradas de trabajo en etapa de pruebas y publique de forma manual los enriquecimientos aprobados.
    • (Opcional) Aprobador de flujos de trabajo de Dataplex (roles/dataplex.workflowApprover): Solo se requiere si habilitas la publicación automática en tu tarea. Permite que el agente apruebe y publique automáticamente sus propias solicitudes de cambio de metadatos.
    • Visualizador de datos de BigQuery (roles/bigquery.dataViewer): Permite que el agente lea esquemas de tablas, metadatos de columnas y tablas de seguimiento de estadísticas del agente.

    Nota: En las siguientes muestras de código, se otorgan estos roles a nivel de proyecto para facilitar la configuración. Para los sistemas de producción, te recomendamos otorgar estos roles de forma segura a nivel de recurso en tus conjuntos de datos de destino específicos.

    Para otorgar estos roles estándar, sigue estos pasos:

    Para agregar una vinculación de política de IAM a un proyecto, usa el comando gcloud projects add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. Otorga a los usuarios permiso para actuar en nombre de la cuenta de servicio asignándoles el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser):

    Los usuarios que crean las tareas de enriquecimiento en la consola deben tener este permiso para poder especificar y adjuntar esta cuenta de servicio a la tarea.

    Para otorgar a los usuarios el rol de usuario de cuenta de servicio, sigue estos pasos:

    Para agregar una vinculación de política de IAM a una cuenta de servicio, usa el comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.
    • USER_EMAIL: Es la dirección de correo electrónico del usuario.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. Permite que el agente de servicio interno de Knowledge Catalog actúe en nombre de esta cuenta de servicio otorgándole el rol de Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator):

    Esto permite que el servicio de Knowledge Catalog subyacente asuma la identidad de esta cuenta de servicio dedicada y sus permisos restringidos cuando ejecuta las operaciones de enriquecimiento en segundo plano en tu nombre.

    Para autorizar al agente a asumir la identidad de la cuenta de servicio, sigue estos pasos:

    Para agregar una vinculación de política de IAM a una cuenta de servicio, usa el comando gcloud iam service-accounts add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.
    • TARGET_PROJECT_NUMBER: el número de tu proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

Otorga los roles de IAM necesarios a los usuarios

Para asegurarte de que tu equipo pueda administrar los flujos de trabajo de enriquecimiento y revisar las propuestas generadas por IA, otorga los roles de IAM adecuados a tus usuarios. Para obtener instrucciones sobre cómo otorgar estos roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Los administradores de flujos de trabajo (como los administradores de datos) que crean, configuran y supervisan tareas requieren los siguientes roles:

  • Editor de DataScan de Dataplex (roles/dataplex.dataScanEditor) o Editor de Dataplex (roles/dataplex.editor): Permite que los usuarios creen, modifiquen, activen y cancelen tareas de enriquecimiento.
  • Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la cuenta de servicio administrada por el cliente: es necesario para adjuntar la cuenta de servicio como la identidad de ejecución de la tarea.

Los revisores de cambios (como los propietarios de dominios o los expertos en la materia) que inspeccionan, aprueban y publican propuestas de metadatos generados por IA en el catálogo necesitan los siguientes roles:

  • Editor del catálogo de Dataplex (roles/dataplex.catalogEditor) y Visualizador del catálogo de Dataplex (roles/dataplex.catalogViewer): Se requieren para abrir solicitudes de cambio, inspeccionar diferencias de propuestas en paralelo y editar descripciones intercaladas.
  • Aprobador de flujos de trabajo de Dataplex (roles/dataplex.workflowApprover): Es obligatorio para aprobar y publicar solicitudes de cambio en el catálogo en vivo.
  • Visualizador de DataScan de Dataplex (roles/dataplex.dataScanViewer) o Visualizador de Dataplex (roles/dataplex.viewer): Es necesario para revisar las puntuaciones de confianza por propuesta, el diagnóstico de fallas de las pruebas y los cuadros de evaluación posteriores.

Configura proveedores de autenticación de terceros

Cuando conectes el agente de enriquecimiento a fuentes de conocimiento de terceros (como Microsoft SharePoint, Atlassian Confluence o GitHub), debes configurar un proveedor de autenticación con el servicio de identidad del agente de Google Cloud.

Agent Identity actúa como un administrador de credenciales de seguridad seguro que encripta tus tokens de terceros dentro de tu proyecto, lo que garantiza que los operadores humanos nunca tengan que controlar secretos del cliente sin procesar durante la ejecución de tareas.

Para obtener instrucciones paso a paso sobre cómo generar los tokens necesarios y configurar el proveedor de autenticación para plataformas externas específicas, consulta Configura conectores externos para tareas de enriquecimiento.

Configura los permisos de IAM para los proveedores de autenticación

Para permitir que el agente de enriquecimiento recupere de forma segura las credenciales de tu proveedor de autenticación de forma dinámica durante una ejecución activa, debes otorgar el rol Administrador de identidad del agente (roles/agentidentity.admin) al agente de servicio de Knowledge Catalog administrado (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com). Puedes otorgar este rol a nivel del recurso del proveedor de autenticación o a nivel del proyecto.

Además, el usuario humano que adjunta el proveedor de autenticación a la tarea en la consola deGoogle Cloud debe tener el permiso agentidentity.authProviders.get (incluido en Visualizador de identidad del agente (roles/agentidentity.viewer)) en el proveedor de autenticación.

Prepara buckets de Cloud Storage

Cloud Storage funciona como la capa principal de etapa de pruebas basada en archivos, transferencia de contexto y exportación de artefactos para los flujos de trabajo de enriquecimiento de conocimiento.

Puedes configurar el agente para que transfiera archivos de uno o más buckets de entrada y, así, fundamentar su razonamiento en el conocimiento del dominio de tu empresa. Entre los tipos de contexto admitidos, se incluyen los siguientes:

  • Documentación de dominio y diccionarios de datos: Archivos Markdown, de texto sin formato, PDF, HTML o CSV que contienen definiciones de tablas, glosarios empresariales, procedimientos operativos estándar (SOP), arquitecturas de canalizaciones de datos o lineamientos para asignar nombres a las columnas.

  • Conjuntos de datos de evaluación: Son archivos JSONL o CSV que almacenan consultas de origen y conjuntos de consultas de validación retenidos. Para obtener más información, consulta Formatea conjuntos de datos de evaluación.

  • Secuencias de comandos de transformación y SQL de referencia: Secuencias de comandos de SQL guardadas, definiciones de modelos de dbt o lógica de transformación de ETL que proporcionan indicadores contextuales sobre los patrones de unión de tablas y los cálculos empresariales.

Cuando se configura, el agente de enriquecimiento también puede exportar paquetes estructurados y artefactos de ejecución a un bucket de salida. Entre los artefactos de salida admitidos, se incluyen los siguientes:

  • Informes de evaluación detallados: Cuadros de evaluación integrales que muestran las diferencias de exactitud por consulta, el diagnóstico de fallas de las pruebas y las métricas de distribución de confianza.

Para asegurarte de que el agente de enriquecimiento pueda trabajar fuera del bucket, asegúrate de que tu cuenta de servicio de ejecución tenga los permisos necesarios.

  • Otorga el rol de visualizador de objetos (roles/storage.objectViewer) en los buckets de entrada para que el agente pueda leer los documentos de etapas y los archivos de configuración.
  • (Opcional) Otorga el rol de creador de objetos (roles/storage.objectCreator) en el bucket de salida si deseas que el agente guarde los artefactos de ejecución y los registros de validación.

Para otorgar a la cuenta de servicio acceso a los buckets de Cloud Storage, sigue estos pasos:

Para agregar una vinculación de política de IAM a un bucket de almacenamiento, usa el comando gcloud storage buckets add-iam-policy-binding:

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • CUSTOMER_BUCKET: Es el nombre de tu bucket de Cloud Storage.
  • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
  • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

Formatea conjuntos de datos de evaluación

Los flujos de trabajo de enriquecimiento pueden extraer información automáticamente sin ejemplos. Sin embargo, proporcionar conjuntos de datos de evaluación permite que el agente se pruebe a sí mismo y mejore su exactitud.

Puedes proporcionar dos tipos de conjuntos de datos:

  • Conjunto de selección: Es una lista de preguntas de usuario de ejemplo y las consultas en SQL esperadas. El agente usa esta lista para practicar y escribir mejores resúmenes de tablas.

  • Conjunto de evaluación: Es una lista independiente de preguntas que se usa para calificar el rendimiento del agente. Si el agente tiene un rendimiento deficiente, este conjunto de evaluación evita que se publiquen actualizaciones deficientes en tu catálogo.

Como alternativa, puedes proporcionar un único conjunto de datos consolidado. El servicio de enriquecimiento divide automáticamente los datos en un conjunto de selección y un conjunto de evaluación.

Requisitos del esquema del conjunto de datos

Los conjuntos de datos de evaluación deben tener el formato de archivos JSONL y almacenarse en Cloud Storage. Cada línea del archivo debe contener una pregunta en lenguaje natural vinculada con la consulta en SQL de verdad fundamental esperada.

Asegúrate de que tu archivo coincida con el esquema del conjunto de datos de evaluación prescrito por Gemini Enterprise Agent Platform. En la siguiente tabla, se muestran los campos de formato aceptados:

Nombre del campo Tipo Descripción
display_name STRING Es opcional. Es un identificador o nombre para la solicitud de evaluación.
evaluation_request.prompt.text STRING Es la pregunta en lenguaje natural o la instrucción del usuario.
evaluation_request.golden_response.candidate STRING Identifica la respuesta de referencia. Se define en golden.
evaluation_request.golden_response.text STRING Es la verdad fundamental, la consulta en SQL validada que responde la pregunta. El anotador ejecuta esta consulta en SQL en los datos.

En el siguiente fragmento, se muestra un archivo de evaluación .jsonl válido:

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

Para obtener orientación detallada sobre cómo crear conjuntos de datos de evaluación de alta calidad, consulta la documentación de Gemini Enterprise Agent Platform.

Configura los seguimientos de agentes para el autoaprendizaje

Para permitir que el agente de enriquecimiento analice automáticamente las interacciones del agente de Gemini Enterprise downstream (o las aplicaciones personalizadas de Gemini Enterprise Agent Platform), puedes proporcionarle acceso de lectura a los seguimientos de interacción de tu aplicación de forma opcional.

La transferencia de estos seguimientos permite que el agente realice una extracción de trayectorias. El agente descubre dónde tuvieron dificultades los agentes downstream debido a la falta de contexto, agrupa las preguntas frecuentes de los usuarios en clases de consultas de alto impacto y organiza automáticamente los resúmenes de tablas, la semántica de las columnas y los términos del glosario empresarial exactos que se necesitan para resolver esas brechas.

Según la arquitectura de tu empresa, elige uno de los siguientes dos métodos de configuración:

  • Registro directo con vistas de registro con alcance: Crea una vista de registro restringida solo a la telemetría de la aplicación para otorgar acceso de lectura con privilegios mínimos. (recomendado)
  • Análisis de agentes de BigQuery: Otorga acceso de lectura a un conjunto de datos de BigQuery exportado si tu organización enruta de forma nativa los registros de interacción a un receptor de registros de BigQuery.

Registro directo con vistas de registro con alcance (recomendado)

Cuando se habilita el registro de interacciones para una aplicación, los registros de ejecución se transmiten directamente a Logging. Para seguir el principio de privilegio mínimo, crea una vista de registros dedicada restringida a la aplicación específica y otorga a la cuenta de servicio de ejecución acceso de lectura exclusivamente en esa vista.

  1. Crea una vista de registro con permiso para aislar los registros. Esto garantiza que el servicio de enriquecimiento solo lea la telemetría de aplicaciones configuradas específicas (por ejemplo, filtrando por resource.type="aiplatform.googleapis.com/Agent"), lo que evita el acceso no autorizado a tus registros de Cloud más amplios.

    gcloud CLI

    Para crear una vista de registro con alcance, usa el comando gcloud logging views create:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • YOUR_GEMINI_ENTERPRISE_APP_ID: Es el ID de aplicación de Gemini Enterprise.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.
    • YOUR_GEMINI_ENTERPRISE_APP_ID: Es el ID de aplicación de Gemini Enterprise.

    Método HTTP y URL: 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    Cuerpo JSON de la solicitud:

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.

  2. Después de crear la vista de registro, otorga acceso de lectura a la cuenta de servicio de ejecución. Esto autoriza al trabajo de enriquecimiento a extraer la telemetría de la aplicación que necesita durante la fase de autoaprendizaje.

    Para agregar una vinculación de política de IAM a una vista de registro, usa el comando gcloud logging views add-iam-policy-binding:

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • LOG_VIEW_NAME: el nombre de tu vista de registro
    • SERVICE_ACCOUNT_NAME: Es el nombre de tu cuenta de servicio.
    • TARGET_PROJECT_ID: El ID del proyecto de Google Cloud.

    Ejecuta el siguiente comando:

    Linux, macOS o Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows (PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows (cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

Para obtener más información, consulta Configura vistas de registros en un bucket de registros.

Análisis de agentes de BigQuery

Si tu organización transmite registros de interacción a BigQuery con un receptor de registros de Logging o escribe directamente en las tablas de análisis de agentes de BigQuery, puedes otorgar acceso al conjunto de datos.

Asegúrate de que los registros de interacción estén configurados para transmitirse a un conjunto de datos de BigQuery designado y verifica que a la cuenta de servicio de ejecución se le otorgue el rol de visualizador de datos de BigQuery (roles/bigquery.dataViewer) en ese conjunto de datos específico. Esto permite que el agente lea la telemetría exportada directamente desde BigQuery.

Para obtener más información sobre la exportación de registros, consulta Enruta registros a destinos compatibles.

Habilita la generación de perfiles de datos y las estadísticas de datos

Antes de ejecutar una tarea de enriquecimiento, te recomendamos que habilites la generación de perfiles de datos y las estadísticas de datos de IA en las tablas de destino que usas con frecuencia. La generación de perfiles de datos proporciona características estadísticas, como valores comunes, distribuciones de datos y recuentos nulos, mientras que las estadísticas de datos generan descripciones de tablas de referencia y consultas de ejemplo. Proporcionar estos indicadores ayuda al agente de enriquecimiento a generar propuestas de metadatos más precisas.

¿Qué sigue?