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 la 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 proyecto de Google Cloud . En este documento, se describen los cambios necesarios y se proporciona un vínculo a una aplicación de ejemplo.

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 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 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, podrías escribir código de instrumentación para hacer lo siguiente:

  • Realizar un seguimiento del consumo de recursos de las herramientas invocadas por el agente
  • Realiza un seguimiento de los errores de validación específicos de la aplicación, los incumplimientos de las reglas comerciales o los mecanismos personalizados de recuperación de errores.
  • Realiza un seguimiento de las calificaciones de calidad de las respuestas del agente según tus criterios específicos del dominio.

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

Para instrumentar tu agente de IA y recopilar datos de registros, métricas y seguimiento, 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 exportación de OpenTelemetry:

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

Los datos de registros y métricas se envían a tu proyecto Google Cloud con la API de Cloud Logging o la API de Cloud Monitoring. Las bibliotecas opentelemetry-exporter-gcp-logging y opentelemetry-exporter-gcp-monitoring invocan extremos en esas APIs.

Los datos de seguimiento se envían a Google Cloud con la API de Telemetry (OTLP), que implementa el protocolo OTLP 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 OTLP de OpenTelemetry. Sin embargo, es posible que los campos se conviertan 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 de los 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 aGoogle Cloud Observability. Para habilitar esta opción, configura tu entorno del ADK:

  • Cuando ejecutes tu aplicación con el comando de la CLI de adk web, incluye la marca --otel_to_cloud.

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

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

  • También te recomendamos que 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:

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

Descarga y ejecuta la aplicación de muestra

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

Arquetipo de 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

  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. Instala Google Cloud CLI.

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

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona 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 permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un Google Cloud proyecto:

      gcloud projects create PROJECT_ID

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

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

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

  7. Habilita las APIs de Vertex AI, 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 permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

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

  8. Instala Google Cloud CLI.

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

  10. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  11. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona 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 permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un Google Cloud proyecto:

      gcloud projects create PROJECT_ID

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

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

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

  13. Habilita las APIs de Vertex AI, 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 permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

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

  14. Si ejecutas la muestra en Cloud Shell, en recursos Google Cloudo en un entorno de desarrollo local, los permisos que se indican en esta sección son suficientes. En el caso de las aplicaciones de producción, por lo general, una cuenta de servicio proporciona las credenciales para escribir datos de registros, métricas y seguimientos.

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

Inicia la aplicación

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

  1. En Cloud Shell, ejecuta el siguiente comando:

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git

  2. Ve al directorio de muestra:

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

  3. Crea un entorno virtual y ejecuta la muestra:

    python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud

    La aplicación muestra un mensaje similar al siguiente:

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

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

  5. Expande Selecciona un agente y selecciona sql_agent de la lista de agentes.

Interactúa con el agente

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

What can you do for me ?

Del mismo modo, dado que sql_agent tiene la personalidad de un experto en SQL, puedes pedirle que cree tablas para tus aplicaciones y 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.

A continuación, se ilustra una interacción de ejemplo entre sql_agent y el usuario:

Es la visualización de la interacción con sql_agent.

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

Salir de la aplicación

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

Visualiza los registros, las métricas y los seguimientos

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 registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

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.

Ver telemetría

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

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

    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, luego Nombre del tramo y, por último, call_llm.

    En la siguiente ilustración, se muestra la página del Explorador de seguimiento después de filtrar los datos:

    Visualización de intervalos de seguimiento.

    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 habrá datos de seguimiento disponibles para ver.

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

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

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

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

      Se muestran 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, selecciona Ver registros en la barra de herramientas de esta pestaña.

      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 proyecto de Google Cloud , pero no genera ninguna métrica.