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

Instrumentar aplicaciones ADK con OpenTelemetry

En este documento se describe cómo instrumentar un agente de IA creado con el framework del kit de desarrollo de agentes (ADK). Esta instrumentación, que aprovecha OpenTelemetry, te permite recoger las peticiones de los usuarios, las respuestas de los agentes y las opciones de los agentes.

El propio framework del ADK está instrumentado con OpenTelemetry, que registra la telemetría de los pasos clave de la ejecución de tu agente. De esta forma, se proporciona una observabilidad de las aplicaciones valiosa de forma predeterminada. Sin embargo, esta observabilidad puede no ser 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 y recoger datos de registro, métricas y trazas, haz lo siguiente:

Instalar paquetes de OpenTelemetry
Configurar OpenTelemetry para recoger y enviar telemetría
Escribir un punto de entrada personalizado para insertar OpenTelemetry configurado

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 'opentelemetry-instrumentation-google-genai' \
  '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 OpenTelemetry para recoger y enviar telemetría

En el código de inicialización de tu agente del ADK, añade código para configurar OpenTelemetry de forma que capture y envíe telemetría a tu Google Cloud proyecto:

Para ver el ejemplo completo, haz clic en Más y, a continuación, selecciona Ver en GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Escribir un punto de entrada personalizado para usar OpenTelemetry configurado

Para usar OpenTelemetry en la instrumentación, crea un punto de entrada personalizado para tu aplicación ADK. El punto de entrada personalizado debe configurar OpenTelemetry antes de iniciar el agente del ADK.

En la aplicación de ejemplo, el método main actúa como punto de entrada personalizado que inicializa OpenTelemetry y, a continuación, inicia el servidor FastAPI, que te permite interactuar con el agente.

Para ver el ejemplo completo, haz clic en Más y, a continuación, selecciona Ver en GitHub.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Descargar y ejecutar la aplicación de ejemplo

Este código de ejemplo implementa un agente de IA generativa creado con ADK. El agente está instrumentado con OpenTelemetry y configurado 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 (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 (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) python main.py

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, abre un navegador en la dirección que se indica en el 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, puedes 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:

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.

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 encontrar 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 seguimiento asociado y sus intervalos. 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 GenAI 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 de JSON incluye el siguiente contenido:
```
{
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "role": "model",
      "parts": [
        {
          "executable_code": null,
          "inline_data": null,
          "thought": null,
          "video_metadata": null,
          "code_execution_result": null,
          "function_response": null,
          "thought_signature": null,
          "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
          "file_data": null,
          "function_call": null
        }
      ]
    }
  },
  ...
}
```

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 OpenTelemetry para recoger y enviar telemetría

Escribir un punto de entrada personalizado para usar OpenTelemetry configurado

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