Instrumenta aplicaciones del ADK con OpenTelemetry

En este documento, se explica cómo instrumentar un agente de IA que se creó con el framework del Kit de desarrollo de agentes (ADK). El framework del ADK incluye la instrumentación de OpenTelemetry que recopila datos de telemetría de las acciones clave del agente. Cuando habilitas la instrumentación integrada, esta envía información, como instrucciones de texto y respuestas del agente, a tu Google Cloud proyecto. En este documento, se describen los cambios necesarios y se proporciona un vínculo a una aplicación de muestra.

Las aplicaciones que usan el ADK también pueden recopilar instrucciones y respuestas multimodales. En este documento, se describe cómo recopilar instrucciones y respuestas de texto. Si deseas recopilar datos multimodales, se requiere una configuración adicional. Para obtener más información, consulta Recopila y visualiza instrucciones y respuestas multimodales.

Es posible que la observabilidad predeterminada que proporciona el ADK no sea suficiente para el caso de uso de tu aplicación. Puedes agregar bibliotecas de instrumentación adicionales con OpenTelemetry para capturar datos de telemetría de otras partes de tu app o tu propia instrumentación personalizada para capturar datos específicos de la aplicación y obtener una observabilidad más detallada. Por ejemplo, en tu aplicación, puedes escribir código de instrumentación para hacer lo siguiente:

• Realizar un seguimiento del consumo de recursos de las herramientas invocadas por el agente
• Realizar un seguimiento de las fallas de validación específicas de la aplicación, las infracciones de reglas empresariales o los mecanismos personalizados de recuperación de errores
• Realizar un seguimiento de las puntuaciones de calidad de las respuestas del agente según tus criterios específicos del dominio

Nota: En este documento, se supone que usas un framework del ADK con la versión 1.17.0 o posterior.

Instrumenta tu aplicación de IA generativa para recopilar datos de telemetría

Para instrumentar tu agente de IA para recopilar datos de registro, métricas y seguimientos, haz lo siguiente:

1. Instala los paquetes de OpenTelemetry.
2. Configura tu entorno del ADK.

En el resto de esta sección, se describen los pasos anteriores.

Instala los paquetes de OpenTelemetry

Agrega los siguientes paquetes de instrumentación y exportador de OpenTelemetry:

uv add 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Los datos de registro se envían a tu Google Cloud proyecto con la API de Cloud Logging o la API de Cloud Monitoring. La biblioteca opentelemetry-exporter-gcp-logging invoca extremos en la API de Cloud Logging.

No se recopilan datos de métricas. Por lo general, las aplicaciones que no usan una solución basada en el recopilador incluyen la opentelemetry-exporter-gcp-monitoring biblioteca. Esta biblioteca invoca extremos en la API de Cloud Monitoring.

Los datos de seguimiento se envían a Google Cloud con la API de Telemetry (OTLP), que implementa el protocolo de línea de OpenTelemetry. La biblioteca opentelemetry-exporter-otlp-proto-grpc invoca el extremo de API de Telemetry (OTLP).

Tus datos de seguimiento se almacenan en un formato que suele ser coherente con los archivos proto definidos por el protocolo de línea de OpenTelemetry. Sin embargo, los campos se pueden convertir de un tipo de datos específico de OpenTelemetry a un tipo de datos JSON antes del almacenamiento. Para obtener más información sobre el formato de almacenamiento, consulta Esquema para datos de seguimiento.

Configura tu entorno del ADK

Las versiones 1.17.0 y posteriores del framework del ADK incluyen compatibilidad integrada con OpenTelemetry y el envío de datos de telemetría de OpenTelemetry a Google Cloud Observability. Para habilitar esta opción, configura tu entorno del ADK:

• Si ejecutas tu aplicación con el comando adk web, incluye la marca --otel_to_cloud.

• En tu archivo opentelemetry.env, establece las siguientes variables de entorno:

  OTEL_SERVICE_NAME='adk-sql-agent'
  OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'
  

• Configura OpenTelemetry para usar las convenciones semánticas más recientes para la IA generativa.

  OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
  

• Configura OpenTelemetry para adjuntar mensajes como eventos.

  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'
  

  Nota: No establezcas el valor de esta variable en true. Cuando usas las convenciones semánticas más recientes, establecer el valor de esta variable en true genera una configuración no válida. Por lo tanto, no se recopilan datos de registro ni de seguimiento.

  Para obtener más información sobre los valores enumerados permitidos, consulta genai/types.py.

• Te recomendamos que también agregues la siguiente variable de entorno a tu archivo opentelemetry.env:

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
  

  Esta variable de entorno hace lo siguiente:

  • Impide que la instrumentación del ADK adjunte atributos de intervalo que superen el límite de tamaño del atributo.
  • Impide que la información de identificación personal (PII) se adjunte a los intervalos como atributos.

• Es posible que debas establecer otras variables de entorno. Por ejemplo, si realizas la implementación en Gemini Enterprise Agent Platform, también debes establecer la siguiente variable de entorno:

  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
  

Descarga y ejecuta la aplicación de muestra

Este código de muestra implementa un agente de IA generativa que se compila con el ADK. El agente está instrumentado con OpenTelemetry y configurado para enviar métricas, seguimientos y registros a tu Google Cloud proyecto. Los datos de telemetría enviados a tu proyecto incluyen instrucciones y respuestas de IA generativa.

Persona del agente del ADK

El agente de IA generativa se define como un experto en SQL que tiene acceso completo a una base de datos SQLite efímera. El agente se compila con el Kit de desarrollo de agentes y accede a una base de datos con el SQLDatabaseToolkit. Inicialmente, la base de datos está vacía.

Antes de comenzar

Accede a tu Google Cloud cuenta de. 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.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Seleccionar un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén información para otorgar roles.

Nota: Si no planeas conservar los recursos que creas en este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Después de completar estos pasos, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto que estás creando.

• Selecciona el Google Cloud proyecto que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita las APIs de Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring y Cloud Trace:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el serviceusage.services.enable permiso. Obtén información para otorgar roles.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Seleccionar un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén información para otorgar roles.

Nota: Si no planeas conservar los recursos que creas en este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Después de completar estos pasos, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto que estás creando.

• Selecciona el Google Cloud proyecto que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita las APIs de Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring y Cloud Trace:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el serviceusage.services.enable permiso. Obtén información para otorgar roles.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. Para obtener los permisos que necesitas para que la aplicación de muestra escriba datos de registro, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

   • Escritor de seguimientos de telemetría de Cloud (roles/telemetry.tracesWriter)
   • Escritor de registros (roles/logging.logWriter)
   • Escritor de métricas de Monitoring (roles/monitoring.metricWriter)
   • Usuario de Vertex AI (roles/aiplatform.user)

   Estos permisos son suficientes si ejecutas la muestra en el Cloud Shell, en Google Cloud recursos o en un entorno de desarrollo local.

   Importante: Por lo general, las aplicaciones de producción dependen de una cuenta de servicio para proporcionar las credenciales necesarias para escribir datos de registro, métricas y seguimientos. En esos casos, otorga los roles anteriores a la cuenta de servicio.

2. Asegúrate de especificar un proyecto de cuota. La API de Vertex AI (aiplatform.googleapis.com) requiere que se especifique un proyecto de cuota. Para obtener más información, consulta Configura el proyecto de cuota. Por ejemplo, el siguiente comando puede establecer un proyecto de cuota.

   gcloud config set billing/quota_project PROJECT_ID

Inicia la aplicación

Para iniciar la aplicación de muestra, haz lo siguiente:

1. En Cloud Shell, clona el repositorio:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. Ve al directorio de muestra:

   cd opentelemetry-samples/python/adk-sql-agent
   

   La muestra contiene un archivo .env que establece dos variables de entorno. Una variable controla qué extremos usa el SDK. La otra variable establece una ubicación.

   Si prefieres usar un modelo diferente, edita main.py. Asegúrate de que el modelo que selecciones admita la ubicación especificada en el archivo .env. Para obtener información sobre los modelos, consulta Modelos de Google.

3. Crea un entorno virtual y ejecuta la muestra:

   uv run --env-file opentelemetry.env adk web --otel_to_cloud
   

   La aplicación muestra un mensaje similar al siguiente:

   Appplication startup complete
   Uvicorn running on http://127.0.0.1:8080
   

4. Para interactuar con el agente, selecciona la URL que se muestra en el resultado del paso anterior.

5. Expande Seleccionar una app y selecciona sql_agent de la lista de agentes.

   Nota: Esta aplicación requiere el uso compartido de recursos entre dominios (CORS). Si ingresas una instrucción y se bloquea CORS, la aplicación muestra el mensaje Failed to create session y la línea de comandos muestra que se rechazaron los comandos, POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   Para habilitar CORS, agrega lo siguiente al comando que ejecuta la muestra:
   

   --allow_origins="regex:.*"

Interactúa con el agente

Para interactuar con el agente, hazle una pregunta o dale un comando. Por ejemplo, puedes hacer la siguiente pregunta:

What can you do for me ?

Del mismo modo, como sql_agent tiene la persona de un experto en SQL, puedes pedirle que cree tablas para tus aplicaciones y que escriba consultas para operar en las tablas creadas. El agente solo puede crear una base de datos efímera respaldada por un archivo .db que se crea en la máquina que ejecuta la aplicación.

En la siguiente imagen, se muestra una interacción de muestra entre sql_agent y el usuario:

Las acciones que realizan los agentes de IA generativa no son deterministas, por lo que es posible que veas una respuesta diferente para la misma instrucción.

Salir de la app

Para salir de la aplicación, ingresa Ctrl-C en el shell que se usó para iniciarla.

Visualiza los seguimientos, las métricas y los registros

En esta sección, se describe cómo puedes ver los eventos de IA generativa.

Antes de comenzar

Para obtener los permisos que necesitas para ver tus datos de registro, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Visor de registros (roles/logging.viewer)
• Visualizador de Monitoring (roles/monitoring.viewer)
• Usuario de Cloud Trace (roles/cloudtrace.user)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Visualiza los datos de telemetría

Para ver los eventos de IA generativa creados por la aplicación, usa la página Explorador de seguimiento:

1. En la Google Cloud consola de, ve a la Explorador de seguimiento página:

   Ve al Explorador de seguimiento

   También puedes usar la barra de búsqueda para encontrar esta página.

2. En la barra de herramientas, selecciona Agregar filtro, selecciona Nombre del intervalo y, luego, selecciona call_llm.

   En la siguiente imagen, se muestra la página Explorador de seguimiento después de filtrar los datos:

   

   Si nunca usaste Cloud Trace, Google Cloud Observability debe crear una base de datos para almacenar tus datos de seguimiento. La creación de la base de datos puede tardar unos minutos y, durante ese período, no hay datos de seguimiento disponibles para ver.

3. Para explorar tus datos de intervalo y registro, selecciona un intervalo en la tabla Intervalos.

   Se abrirá la página Detalles. En esta página, se muestra el seguimiento asociado y sus intervalos. En la tabla de la página, se muestra información detallada del intervalo que seleccionaste. Esta información incluye lo siguiente:

   • En la pestaña Entradas/Salidas , se muestran eventos para agentes de IA generativa. Para obtener más información sobre estos eventos, consulta Visualiza eventos de IA generativa.

     En la siguiente captura de pantalla, se muestra un seguimiento, en el que un intervalo tiene el nombre call_llm. Ese intervalo invoca el LLM (modelo de lenguaje grande) que potencia este agente. Para esta muestra, es Gemini. El intervalo de Gemini incluye eventos de IA generativa:

     

   • En la pestaña Registros y eventos , se enumeran las entradas de registro y los eventos asociados con el intervalo. Si deseas ver los datos de registro en el Explorador de registros, en la barra de herramientas de esta pestaña, selecciona Ver registros.

     Los datos de registro incluyen la respuesta de sql_agent. Por ejemplo, para la ejecución de muestra, la carga útil de JSON incluye el siguiente contenido:

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "parts": [
             0: {
               "text": "Now I can create the table."
             }
             1: {1}
             ],
           "role": "model"
         }
       },
       ...
     }
     

La muestra está instrumentada para enviar datos de métricas a tu Google Cloud proyecto, pero no genera ninguna métrica.