Esta página se ha traducido con Cloud Translation API.

Instrumentar aplicaciones ADK con OpenTelemetry

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

Las aplicaciones que usan ADK también pueden recoger peticiones y respuestas multimodales. En este documento se describe cómo recoger peticiones de texto y respuestas. Si quieres recoger datos multimodales, debes realizar una configuración adicional. Para obtener más información, consulta Recoger y ver peticiones y respuestas multimodales.

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

Monitoriza el consumo de recursos de las herramientas invocadas por el agente.
Hacer un seguimiento de los fallos de validación específicos de la aplicación, las infracciones de las reglas de negocio o los mecanismos de recuperación de errores personalizados.
Monitoriza las puntuaciones de calidad de las respuestas de los agentes en función de los criterios específicos de tu dominio.

Instrumentar tu aplicación de IA generativa para recoger telemetría

Para instrumentar tu agente de IA de forma que recoja datos de registro, métricas y trazas, haz lo siguiente:

Instala los paquetes de OpenTelemetry.
Configura tu entorno de ADK.

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

Instalar paquetes de OpenTelemetry

Añade 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 registro y de métricas se envían a tu proyecto de Google Cloud mediante la API Cloud Logging o la API Cloud Monitoring. Las bibliotecas opentelemetry-exporter-gcp-logging y opentelemetry-exporter-gcp-monitoring invocan endpoints de esas APIs.

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

Los datos de la traza se almacenan en un formato que suele ser coherente con los archivos proto definidos por el protocolo OTLP 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 de almacenarse. Para obtener más información sobre el formato de almacenamiento, consulta Esquema de datos de traza.

Configurar el entorno de ADK

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

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

En el archivo opentelemetry.env, define 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 añadas la siguiente variable de entorno al 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 de los atributos.
- Evita que se adjunte información personal identificable (IPI) a los intervalos como atributos.

Descargar y ejecutar la aplicación de ejemplo

Este código de ejemplo implementa un agente de IA generativa creado con ADK. El agente se instrumenta con OpenTelemetry y se configura para enviar métricas, trazas y registros a tu Google Cloud proyecto. La telemetría enviada a tu proyecto incluye peticiones y respuestas de IA generativa.

Perfil de agente de 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 ha creado con el Agent Development Kit y accede a una base de datos mediante SQLDatabaseToolkit. La base de datos está vacía al principio.

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Si ejecutas el ejemplo en Cloud Shell, en Google Cloud resources o en un entorno de desarrollo local, los permisos que se indican en esta sección serán suficientes. En las aplicaciones de producción, normalmente una cuenta de servicio proporciona las credenciales para escribir datos de registro, métricas y trazas.

Para obtener los permisos que necesitas para que la aplicación de ejemplo escriba datos de registro, métricas y trazas, pide a tu administrador que te conceda los siguientes roles de IAM en tu proyecto:
- Escritor de trazas de telemetría de Cloud (roles/telemetry.tracesWriter)
- Escritor de registros (roles/logging.logWriter)
- Editor de las métricas de monitorización (roles/monitoring.metricWriter)
- Usuario de Vertex AI (roles/aiplatform.user)

Inicia la aplicación

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

En Cloud Shell, ejecuta el siguiente comando:

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

Ve al directorio de ejemplo:

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

Crea un entorno virtual y ejecuta el ejemplo:

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

Para interactuar con el agente, selecciona la URL que se muestra en el resultado del paso anterior.
Despliega Seleccionar un agente y selecciona sql_agent en 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, como el sql_agent tiene el perfil 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 el equipo en el que se ejecuta la aplicación.

A continuación, se muestra un ejemplo de interacción entre sql_agent y el usuario:

Visualización de la interacción con sql_agent.

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 petición.

Salir de la aplicación

Para salir de la aplicación, introduce Ctrl-C en la shell que se ha usado para iniciarla.

Ver las trazas, las métricas y los registros

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

Antes de empezar

Para obtener los permisos que necesitas para ver tus datos de registro, métricas y trazas, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

Visualizador de registros (roles/logging.viewer)
Lector de monitorización (roles/monitoring.viewer)
Usuario de Cloud Trace (roles/cloudtrace.user)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Ver telemetría

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

En la Google Cloud consola, ve a la página Explorador de trazas:
Ir a Explorador de trazas

También puedes acceder a esta página mediante la barra de búsqueda.
En la barra de herramientas, seleccione Añadir filtro, Nombre del intervalo y, a continuación, call_llm.

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

Si nunca has usado Cloud Trace, Google Cloud Observability necesita crear una base de datos para almacenar tus datos de traza. La creación de la base de datos puede tardar unos minutos y, durante ese periodo, no se podrán ver los datos de la traza.
Para consultar los datos de los intervalos y los registros, selecciona un intervalo en la tabla Intervalos.

Se abrirá la página Detalles. En esta página se muestra el rastreo asociado y sus spans. En la tabla de la página se muestra información detallada sobre el intervalo que ha seleccionado. Esta información incluye lo siguiente:
- La pestaña Entradas/Salidas muestra los eventos de los agentes de IA generativa. Para obtener más información sobre estos eventos, consulte Ver eventos de IA generativa.
  
  En la siguiente captura de pantalla se muestra un rastreo en el que un intervalo tiene el nombre call_llm. Ese intervalo invoca el modelo de lenguaje extenso (LLM) que impulsa este agente. En este ejemplo, es Gemini. El intervalo de Gemini incluye eventos de IA generativa:
- En la pestaña Registros y eventos se muestran las entradas de registro y los eventos asociados al intervalo. Si quieres 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, en la ejecución de muestra, la carga útil 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 se ha instrumentado para enviar datos de métricas a tu proyecto de Google Cloud , pero no genera ninguna métrica.

Instrumentar aplicaciones ADK con OpenTelemetry Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Instrumentar tu aplicación de IA generativa para recoger telemetría

Instalar paquetes de OpenTelemetry

Configurar el entorno de ADK

Descargar y ejecutar la aplicación de ejemplo

Perfil de agente de ADK

Antes de empezar

Inicia la aplicación

Interactúa con el agente

Salir de la aplicación

Ver las trazas, las métricas y los registros

Antes de empezar

Ver telemetría

Instrumentar aplicaciones ADK con OpenTelemetry