Instrumenta un agente de ReAct de LangGraph con OpenTelemetry

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

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

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

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

Instala los paquetes de OpenTelemetry

Agrega los siguientes paquetes de instrumentación y exportador de OpenTelemetry:

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

Los datos de registro y métricas se envían a tu Google Cloud proyecto mediante 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 admite el formato OTLP. Los datos recibidos a través de este extremo también se almacenan en el formato OTLP. La biblioteca opentelemetry-exporter-otlp-proto-grpc invoca el extremo de API de Telemetry (OTLP).

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()

Cómo hacer 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)

Te recomendamos que incluyas el código anterior en lugares clave del código de la aplicación.

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

Ejecuta la muestra

Este ejemplo es un agente de LangGraph instrumentado con OpenTelemetry para enviar seguimientos y registros con instrucciones y respuestas de IA generativa, y métricas a tu proyectoGoogle Cloud .

Arquetipo 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 de ReAct precompilado de LangGraph y accede a la base de datos, que inicialmente está vacía, con SQLDatabaseToolkit.

Antes de comenzar

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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

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

  3. Para obtener los permisos que necesitas para que las aplicaciones de ejemplo escriban datos de registro, métricas y seguimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Ejecuta la muestra

Para ejecutar la muestra, haz lo siguiente:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Clona el repositorio:

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

  3. Ve al directorio de muestra:

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

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

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

  6. Para crear una base de datos, ingresa un valor en el mensaje Talk to the SQL agent >> y, luego, presiona Intro.

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

    A continuación, se muestran interacciones de ejemplo 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
);

  7. Para salir, ingresa 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 instrucción.

Visualiza los seguimientos, las métricas y los registros

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 registro, métricas y seguimiento, 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 mediante roles personalizados o cualquier otro rol predefinido.

Cómo ver la 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, Nombre del intervalo y, luego, invoke agent.

    La sección Run sample incluyó una ejecución de ejemplo en la que se envían dos instrucciones a la aplicación. A continuación, se muestra la página del Explorador de seguimientos después de filtrar los datos:

    Visualización de los intervalos de seguimiento.

    Si nunca usaste Cloud Trace, la Observabilidad de Google Cloud 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 hay datos de seguimiento disponibles para ver.

  3. Para explorar tu intervalo y los datos de registro, selecciona un intervalo en la tabla Intervalos.

    Se abrirá la página Detalles. En esta página, se muestra el seguimiento asociado y sus tramos. En la tabla de la página, se muestra información detallada del período que seleccionaste. 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, consulta Cómo ver los eventos de IA generativa.

      En la siguiente captura de pantalla, se ilustra un seguimiento, en el que un intervalo tiene el nombre invoke_agent. Ese intervalo invoca a Gemini. El intervalo de Gemini incluye los siguientes eventos de IA generativa:

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

      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: {
    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 actual está instrumentada para enviar datos de métricas a tu Google Cloud proyecto, pero no genera ninguna métrica.