Instrumentar un agente ReAct de LangGraph con OpenTelemetry

Vista previa

Esta función está sujetas a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En este documento se describen los pasos para instrumentar un agente ReAct de LangGraph con OpenTelemetry, lo que permite recoger datos de telemetría del agente. Las peticiones de los usuarios, las respuestas y las opciones de los agentes se incluyen en la telemetría como atributos asociados a los intervalos. Las respuestas del agente también se incluyen en las entradas de registro que se correlacionan con los intervalos que contienen eventos de IA generativa. Las instrucciones de este documento se aplican cuando el agente usa ChatVertexAI de Langchain para llamar a un modelo de Gemini.

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

Para instrumentar tu aplicación de IA generativa y recoger datos de registro, métricas y trazas, haz lo siguiente:

1. Instalar paquetes de OpenTelemetry
2. Configurar OpenTelemetry para recoger y enviar telemetría
3. Rastrear la invocación del agente de IA generativa

Instalar paquetes de OpenTelemetry

Añade los siguientes paquetes de instrumentación y exportación de OpenTelemetry:

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

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 admite el formato OTLP. Los datos recibidos a través de este endpoint también se almacenan en formato OTLP. La biblioteca opentelemetry-exporter-otlp-proto-grpc invoca el endpoint de la API Telemetry (OTLP).

Configurar OpenTelemetry para recoger y enviar telemetría

En el código de inicialización de tu agente de LangGraph, configura OpenTelemetry para que capture y envíe datos telemétricos 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: "langgraph-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()
    VertexAIInstrumentor().instrument()

Rastrear la invocación del agente de IA generativa

Para monitorizar la ejecución de la invocación del agente de LangGraph, crea un intervalo personalizado en torno a la invocación del agente:

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

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

Puede que quieras incluir el código anterior en lugares clave del código de tu aplicación.

Para obtener más información sobre cómo añadir intervalos y métricas personalizados, consulta Añadir métricas y trazas personalizadas a tu aplicación.

Ejecutar la muestra

Este ejemplo es un agente de LangGraph instrumentado con OpenTelemetry para enviar trazas y registros con peticiones y respuestas de IA generativa, así como métricas a tuGoogle Cloud proyecto.

Perfil de agente de LangGraph

El agente de LangGraph se define como un experto en SQL que tiene acceso completo a una base de datos SQLite efímera. El agente se implementa con el agente ReAct prediseñado de LangGraph y accede a la base de datos, que inicialmente está vacía, mediante SQLDatabaseToolkit.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• 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

1. 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)

Ejecutar muestra

Para ejecutar la muestra, 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 ejemplo:

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

3. Configura las variables de entorno:

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   

4. Crea un entorno virtual y ejecuta el ejemplo:

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   python main.py
   

   La aplicación muestra un mensaje similar al siguiente:

   Starting agent using ephemeral SQLite DB.
   

5. Para crear una base de datos, introduce un valor en la petición Habla con el agente de SQL >> y, a continuación, pulsa Intro.

   Las acciones que realiza el agente se muestran en Cloud Shell.

   A continuación se muestran ejemplos de interacciones entre un usuario y la aplicación:

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation.
   
   Talk to the SQL agent >> Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   👤 User: Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   🤖 Agent
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   

6. Para salir, escribe Ctrl-C.

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.

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 el 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, usa la página Explorador de trazas:

1. 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.

2. En la barra de herramientas, seleccione Añadir filtro, Nombre del intervalo y, a continuación, invoke agent.

   En la sección Ejecutar muestra se incluía un ejemplo de ejecución en el que se enviaban dos peticiones a la aplicación. 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 debe 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.

3. 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 invoke_agent. Ese intervalo invoca a 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 del agente de LangGraph. 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: {
         finish_reason: "stop"
         message: {
           role: "model"
           content: [
             0: {
               text: "I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation."
             }
           ]
         }
       index: 0
       }
     ...
     }
     

La muestra se ha instrumentado para enviar datos de métricas a tu proyecto de Google Cloud , pero no genera ninguna métrica.