Instrumenta un agente de LangGraph ReAct con OpenTelemetry

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En este documento, se describen los pasos para instrumentar un agente de LangGraph ReAct con OpenTelemetry, lo que permite recopilar telemetría del agente. Las instrucciones del usuario, las respuestas y las opciones del agente se incluyen en la telemetría como atributos adjuntos a los tramos. Las respuestas del agente también se incluyen en las entradas de registro correlacionadas 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.

Las aplicaciones que usan un agente de LangGraph ReAct 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.

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

Para instrumentar tu aplicación de IA generativa y recopilar datos de registros, métricas y seguimiento, haz lo siguiente:

1. Instala los paquetes de OpenTelemetry
2. Configura OpenTelemetry para recopilar y enviar telemetría
3. Haz un seguimiento de la invocación del agente de IA generativa

Instala los paquetes de OpenTelemetry

Agrega 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 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 a través de 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, 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 OpenTelemetry para recopilar y enviar telemetría

Dentro del código de inicialización de tu agente de LangGraph, configura OpenTelemetry para capturar y enviar telemetría a tu proyecto Google Cloud :

Para ver la muestra completa, haz clic en Más y, luego, 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()

Haz un seguimiento de la invocación del agente de IA generativa

Para hacer un seguimiento de la ejecución de la invocación del agente de LangGraph, crea un intervalo personalizado alrededor de la invocación del agente:

Para ver la muestra completa, haz clic en Más y, luego, 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)

Es posible que desees incluir el código anterior en lugares clave del código de tu aplicación.

Para obtener más información sobre cómo agregar métricas y intervalos personalizados, consulta Agrega métricas y seguimientos personalizados a tu app.

Ejecuta la muestra

Esta muestra es un agente de LangGraph instrumentado con OpenTelemetry para enviar registros y seguimientos con instrucciones y respuestas de IA generativa, y métricas a tu proyecto deGoogle Cloud .

Personalidad del 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, con SQLDatabaseToolkit.

Antes de comenzar

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.

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

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

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, 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 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.

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

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

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

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

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, 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 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.

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

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

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

   • Escritor de registros 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)

Ejecuta la 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 muestra:

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

3. Configure 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 la muestra:

   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, ingresa un valor en la instrucción Habla con el agente de SQL >> y, luego, presiona Intro.

   Luego, las acciones que realiza el agente se muestran en Cloud Shell.

   A continuación, se ilustran 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: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   🤖 Agent: I have created the weather table.
   👤 User: Add altitude to the table.
   🤖 Agent
   
   ALTER TABLE weather ADD COLUMN altitude REAL;
   
   

6. Para salir, ingresa Ctrl-C.

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.

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:

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

Ver telemetría

Para ver los eventos de IA generativa, usa la página Explorador de seguimiento:

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, invoke agent.

   La sección Ejecutar muestra incluía un ejemplo de ejecución en el que se enviaban dos instrucciones a la aplicación. En la siguiente imagen, se ilustra la página del Explorador de registros 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 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 invoke_agent. Ese intervalo invoca a 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, 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, 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: {
         message: {
           role: "model"
           content: [
             0: {
               text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
     
               CREATE TABLE weather (
                   date DATE,
                   location VARCHAR(255),
                   temperature REAL,
                   humidity REAL,
                   precipitation REAL
               );
               "
             }
           ]
         }
       index: 0
       }
     ...
     }
     

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