Instrumenta un agente de LangGraph ReAct 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 opciones 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 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 ReAct de LangGraph también pueden recopilar instrucciones y respuestas multimodales. En este documento, se describe cómo recopilar instrucciones de texto y respuestas. Si deseas recopilar datos multimodales, se requiere una 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 datos de telemetría

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

  1. Instala paquetes de OpenTelemetry
  2. Configura OpenTelemetry para recopilar y enviar telemetría
  3. Realiza 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:

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-otlp-proto-grpc'

Los datos de registro, métricas y seguimientos se envían a Google Cloud con la API de Telemetry (OTLP), que implementa el protocolo 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, en general, es coherente con los archivos proto definidos por el protocolo 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 del almacenamiento. Para obtener más información sobre el formato de almacenamiento, consulta Esquema para datos de seguimiento.

Configura OpenTelemetry para recopilar y enviar telemetría

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

Para ver la muestra completa, selecciona el logotipo de GitHub en la barra de herramientas de la muestra.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # 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(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Realiza 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, selecciona el logotipo de GitHub en la barra de herramientas de la muestra.

# 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 tu aplicación.

Para obtener más información sobre cómo agregar intervalos y métricas personalizados, consulta Agrega seguimientos y métricas 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 proyecto deGoogle Cloud .

Personificación del agente de LangGraph

El agente de LangGraph se define como un experto en SQL que tiene acceso completo a una base de datos efímera de SQLite. 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. Instala Google Cloud CLI.

  2. Configura gcloud CLI para usar tu identidad federada.

    Para obtener más información, consulta Accede a gcloud CLI con tu identidad federada.

  3. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  4. Crea o selecciona un proyecto de Google Cloud .

    Roles necesarios para seleccionar o crear un proyecto

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

    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu proyecto de Google Cloud .

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

  6. Habilita las APIs de Vertex AI, Service Usage, Telemetría, Cloud Logging, Cloud Monitoring y Cloud Trace, si aún no están habilitadas:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles. 

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

  7. Para obtener los permisos que necesitas para que la aplicación de ejemplo escriba datos de registros, métricas y seguimientos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    Estos permisos son suficientes si ejecutas la muestra en Cloud Shell, en recursos de Google Cloud o en un entorno de desarrollo local.

  8. Asegúrate de especificar un proyecto de cuota. La API de Vertex AI (aiplatform.googleapis.com) requiere que se especifique un proyecto de cuota. Para obtener más información, consulta Configura el proyecto de cuota. Por ejemplo, el siguiente comando puede establecer un proyecto de cuota.

    gcloud config set billing/quota_project PROJECT_ID

Ejecuta la muestra

Para ejecutar la muestra, haz lo siguiente:

  1. En Cloud Shell, clona el repositorio:

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git

  2. Ve al directorio de muestra:

    cd opentelemetry-samples/python/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
# Set the location to one that supports gemini-3.5-flash
export GOOGLE_CLOUD_REGION=global

    Si prefieres usar un modelo diferente, edita main.py. Asegúrate de que tu modelo admita la ubicación que especifiques. Para obtener información sobre los modelos, consulta Modelos de Google.

  4. Crea un entorno virtual y ejecuta la muestra:

    uv run 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 el mensaje Habla con el agente de SQL >> y, luego, presiona Intro.

    Luego, las acciones que realiza el agente se muestran en tu 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: 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 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 los datos de registros, métricas y seguimientos, 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 a través de roles personalizados o cualquier otro rol predefinido.

Visualiza 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, selecciona Nombre del intervalo y, luego, selecciona invoke agent.

    En la sección Ejecuta la muestra, se incluyó un ejemplo de ejecución en el que se envían dos instrucciones a la aplicación. A continuación, se muestra la página Explorador de Trace después de filtrar los datos:

    Visualización de intervalos de seguimiento.

    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 hay datos de seguimiento disponibles para ver.

  3. Para explorar los datos de intervalos y 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 del 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 Visualiza 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 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 quieres 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: {
    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 se instrumenta para enviar datos de métricas a tu proyecto de Google Cloud , pero no genera ninguna métrica.