LangGraph ReAct-Agent mit OpenTelemetry instrumentieren

In diesem Dokument werden die Schritte zur Instrumentierung eines LangGraph ReAct-Agents mit OpenTelemetry beschrieben, um Telemetriedaten vom Agenten zu erfassen. Nutzeraufforderungen, Agentantworten und Auswahlmöglichkeiten sind in der Telemetrie als Attribute enthalten, die an Spans angehängt sind. Die Antworten von Kundenservicemitarbeitern sind auch in den Logeinträgen enthalten, die mit Spannen mit generativen KI-Ereignissen korreliert sind. Die Anleitung in diesem Dokument gilt, wenn der Kundenservicemitarbeiter ChatVertexAI von Langchain verwendet, um ein Gemini-Modell aufzurufen.

Ihre GenAI-Anwendung für die Erfassung von Telemetriedaten instrumentieren

So instrumentieren Sie Ihre Anwendung für generative KI, um Protokoll-, Messwert- und Trace-Daten zu erfassen:

1. OpenTelemetry-Pakete installieren
2. OpenTelemetry zum Erfassen und Senden von Telemetrie konfigurieren
3. Aufruf des generativen KI-Agenten erfassen

OpenTelemetry-Pakete installieren

Fügen Sie die folgenden OpenTelemetry-Instrumentierungs- und Exporter-Pakete hinzu:

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

Log- und Messwertdaten werden mithilfe der Cloud Logging API oder der Cloud Monitoring API an Ihr Google Cloud Projekt gesendet. Die Bibliotheken opentelemetry-exporter-gcp-logging und opentelemetry-exporter-gcp-monitoring rufen Endpunkte in diesen APIs auf.

Trace-Daten werden über die Telemetry (OTLP) API, die das OTLP-Format unterstützt, an Google Cloud gesendet. Über diesen Endpunkt empfangene Daten werden ebenfalls im OTLP-Format gespeichert. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetry (OTLP) API-Endpunkt auf.

OpenTelemetry für die Erfassung und das Senden von Telemetriedaten konfigurieren

Konfigurieren Sie OpenTelemetry im Initialisierungscode Ihres LangGraph-Agents so, dass Telemetriedaten erfasst und an Ihr Google Cloud -Projekt gesendet werden:

Wenn Sie sich das vollständige Beispiel ansehen möchten, klicken Sie auf das Dreipunkt-Menü more_vert Mehr und wählen Sie dann Auf GitHub ansehen aus.

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

Aufruf des generativen KI-Agents protokollieren

Wenn Sie die Ausführung der LangGraph-Agent-Aufrufs erfassen möchten, erstellen Sie eine benutzerdefinierte Span um den Agent-Aufruf herum:

Wenn Sie sich das vollständige Beispiel ansehen möchten, klicken Sie auf das Dreipunkt-Menü more_vert Mehr und wählen Sie dann Auf GitHub ansehen aus.

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

Sie können den Code an wichtigen Stellen in Ihrem Anwendungscode einfügen.

Weitere Informationen zum Hinzufügen benutzerdefinierter SPANs und Messwerte finden Sie unter Benutzerdefinierte Traces und Messwerte in Ihre Anwendung hinzufügen.

Beispiel ausführen

Dieses Beispiel ist ein LangGraph-Agent, der mit OpenTelemetry instrumentiert ist, um Traces und Logs mit Prompts und Antworten von generativer KI sowie Messwerte an IhrGoogle Cloud -Projekt zu senden.

LangGraph-Kundenservicemitarbeiter-Identität

Der LangGraph-Agent wird als SQL-Experte definiert, der vollen Zugriff auf eine sitzungsspezifische SQLite-Datenbank hat. Der Agent wird mit dem vordefinierten ReAct-Agenten von LangGraph implementiert und greift mit dem SQLDatabaseToolkit auf die Datenbank zu, die anfangs leer ist.

Hinweise

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. Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendungen Protokoll-, Mess- und Ablaufdaten schreiben können:

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Log-Autor (roles/logging.logWriter)
   • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
   • Vertex AI-Nutzer (roles/aiplatform.user)

Beispiel ausführen

So führen Sie das Beispiel aus:

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. Klonen Sie das Repository:

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

3. Gehen Sie zum Beispielverzeichnis:

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

4. Konfigurieren Sie Umgebungsvariablen:

   # 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. Erstellen Sie eine virtuelle Umgebung und führen Sie das Beispiel aus:

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

   Die Anwendung zeigt eine Meldung ähnlich der folgenden an:

   Starting agent using ephemeral SQLite DB.
   

6. Wenn Sie eine Datenbank erstellen möchten, geben Sie einen Wert in die Aufforderung Mit dem SQL-Agenten sprechen >> ein und drücken Sie dann die Eingabetaste.

   Die vom Kundenservicemitarbeiter ausgeführten Aktionen werden dann in Cloud Shell angezeigt.

   Im Folgenden sind Beispielinteraktionen zwischen einem Nutzer und der Anwendung dargestellt:

   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. Zum Beenden geben Sie Ctrl-C ein.

Die von generativen KI-Agenten ausgeführten Aktionen sind nicht deterministisch. Daher kann es sein, dass Sie für denselben Prompt eine andere Antwort erhalten.

Traces, Messwerte und Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie generative AI-Ereignisse aufrufen.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen Ihrer Protokoll-, Mess- und Ablaufdaten benötigen:

• Logs Viewer (roles/logging.viewer)
• Monitoring-Betrachter (roles/monitoring.viewer)
• Cloud Trace-Nutzer (roles/cloudtrace.user)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Telemetriedaten ansehen

Die Ereignisse für die generative AI finden Sie auf der Seite Trace Explorer:

1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

   Zum Trace Explorer

   Sie können diese Seite auch über die Suchleiste finden.

2. Wählen Sie in der Symbolleiste Filter hinzufügen, Name der Spanne und dann invoke agent aus.

   Im Abschnitt Beispiel ausführen finden Sie eine Beispielausführung, bei der zwei Prompts an die Anwendung gesendet werden. Im Folgenden ist die Seite Trace Explorer nach dem Filtern der Daten zu sehen:

   

   Wenn Sie Cloud Trace noch nie verwendet haben, muss Google Cloud Observability eine Datenbank zum Speichern Ihrer Trace-Daten erstellen. Das Erstellen der Datenbank kann einige Minuten dauern. In dieser Zeit sind keine Trace-Daten verfügbar.

3. Wenn Sie die Daten zu Spans und Protokollen untersuchen möchten, wählen Sie in der Tabelle Spans einen Span aus.

   Die Seite Details wird geöffnet. Auf dieser Seite werden der zugehörige Trace und seine Spans angezeigt. In der Tabelle auf der Seite finden Sie detaillierte Informationen für den ausgewählten Zeitraum. Dazu gehören:

   • Auf dem Tab GenAI werden Ereignisse für generative KI-Agenten angezeigt. Weitere Informationen zu diesen Ereignissen finden Sie unter Generative AI-Ereignisse ansehen.

     Der folgende Screenshot zeigt einen Trace, in dem ein Span den Namen invoke_agent hat. Dieser Bereich ruft Gemini auf. Der Gemini-Span enthält Ereignisse für generative KI:

     

   • Auf dem Tab Protokolle und Ereignisse sind Protokolleinträge und Ereignisse aufgeführt, die mit der Spanne verknüpft sind. Wenn Sie die Protokolldaten im Log-Explorer aufrufen möchten, wählen Sie in der Symbolleiste dieses Tabs Logs ansehen aus.

     Die Protokolldaten enthalten die Antwort des LangGraph-Agents. Für den Beispiellauf enthält die JSON-Nutzlast beispielsweise den folgenden Inhalt:

     {
       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
       }
     ...
     }
     

Das aktuelle Beispiel ist so instrumentiert, dass Messwertdaten an Ihr Google Cloud -Projekt gesendet werden, aber keine Messwerte generiert werden.