LangGraph ReAct-Agent mit OpenTelemetry instrumentieren

Vorschau

Diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

In diesem Dokument werden die Schritte zum Instrumentieren eines LangGraph ReAct-Agents mit OpenTelemetry beschrieben, um Telemetriedaten vom Agent zu erfassen. Nutzeranfragen, Agent-Antworten und ‑Auswahlen sind in der Telemetrie als Attribute enthalten, die an Spans angehängt sind. Agent-Antworten sind auch in den Logeinträgen enthalten, die mit Spans korreliert sind, die Ereignisse für generative KI enthalten. Die Anleitung in diesem Dokument gilt, wenn der Agent „ChatVertexAI“ von Langchain verwendet, um ein Gemini-Modell aufzurufen.

Mit Anwendungen, die den LangGraph ReAct Agent verwenden, können keine Prompts und Antworten mit multimodalen Daten erfasst werden. Sie können diese Prompts und Antworten sowie die darin enthaltenen multimodalen Daten jedoch erfassen, wenn Sie Ihren KI-Agenten mit dem Agent Development Kit (ADK) erstellen. Weitere Informationen finden Sie unter Multimodale Prompts und Antworten erfassen und ansehen.

Anwendung mit generativer KI für die Erfassung von Telemetriedaten instrumentieren

So instrumentieren Sie Ihre generative KI-Anwendung, um Log-, Messwert- und Trace-Daten zu erfassen:

1. OpenTelemetry-Pakete installieren
2. OpenTelemetry so konfigurieren, dass Telemetriedaten erfasst und gesendet werden
3. Aufruf des Agents für generative KI nachvollziehen

OpenTelemetry-Pakete installieren

Fügen Sie die folgenden OpenTelemetry-Instrumentierungs- und ‑Exporterpakete hinzu:

pip install 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  '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.

Tracedaten werden mit der Telemetry (OTLP) API an Google Cloud gesendet. Diese API implementiert das OpenTelemetry OTLP-Protokoll. Die Bibliothek opentelemetry-exporter-otlp-proto-grpc ruft den Telemetry-API-Endpunkt (OTLP) auf.

Ihre Tracedaten werden in einem Format gespeichert, das im Allgemeinen mit den Protobuf-Dateien übereinstimmt, die vom OpenTelemetry OTLP Protocol definiert werden. Felder können jedoch vor dem Speichern von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert werden. Weitere Informationen zum Speicherformat finden Sie unter Schema für Tracedaten.

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 das vollständige Beispiel sehen möchten, klicken Sie auf  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 nachvollziehen

Um die Ausführung des LangGraph-Agent-Aufrufs nachzuvollziehen, erstellen Sie einen benutzerdefinierten Bereich um den Agent-Aufruf:

Wenn Sie das vollständige Beispiel sehen möchten, klicken Sie auf  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 sollten den vorherigen 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 App einfügen.

Beispiel ausführen

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

LangGraph-Agent-Identität

Der LangGraph-Agent wird als SQL-Experte mit vollem Zugriff auf eine temporäre SQLite-Datenbank definiert. Der Agent wird mit dem vorgefertigten ReAct-Agenten von LangGraph implementiert und greift mit dem SQLDatabaseToolkit auf die Datenbank zu, die anfangs leer ist.

Hinweise

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.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

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 role (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.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

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 role (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. Wenn Sie das Beispiel in Cloud Shell, auf Google Cloud-Ressourcen oder in einer lokalen Entwicklungsumgebung ausführen, reichen die in diesem Abschnitt aufgeführten Berechtigungen aus. Für Produktionsanwendungen werden die Anmeldedaten zum Schreiben von Log-, Messwert- und Tracedaten in der Regel von einem Dienstkonto bereitgestellt.

   Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, damit die Beispielanwendung Log-, Messwert- und Tracedaten schreiben kann:

   • 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. Geben Sie in Cloud Shell den folgenden Befehl ein:

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

2. Gehen Sie zum Beispielverzeichnis:

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

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

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

   In der Anwendung wird eine Meldung ähnlich der folgenden angezeigt:

   Starting agent using ephemeral SQLite DB.
   

5. Geben Sie zum Erstellen einer Datenbank einen Wert in den Prompt Mit dem SQL-Agenten sprechen >> ein und drücken Sie dann die Eingabetaste.

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

   Die folgenden Beispiele veranschaulichen Interaktionen zwischen einem Nutzer und der Anwendung:

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

Die von generativen KI-Agents ausgeführten Aktionen sind nicht deterministisch. Sie erhalten also möglicherweise unterschiedliche Antworten auf denselben Prompt.

Traces, Messwerte und Logs ansehen

In diesem Abschnitt wird beschrieben, wie Sie Ereignisse im Zusammenhang mit generativer KI aufrufen können.

Hinweise

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen zum Aufrufen Ihrer Log-, Messwert- und Tracedaten haben:

• Logbetrachter (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Cloud Trace User (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.

Telemetrie ansehen

So rufen Sie die Ereignisse für generative KI auf:

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 aus, dann Span-Name und schließlich invoke agent.

   Im Abschnitt Beispiel ausführen wurde ein Beispiel für die Ausführung angegeben, bei dem zwei Prompts an die Anwendung gesendet werden. Die folgende Abbildung zeigt die Seite Trace Explorer nach dem Filtern der Daten:

   

   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 Tracedaten verfügbar.

3. Wenn Sie Ihre Spannen- und Logdaten ansehen möchten, wählen Sie in der Tabelle Spannen eine Spanne 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 werden detaillierte Informationen für den ausgewählten Zeitraum angezeigt. Zu diesen Informationen gehören:

   • Auf dem Tab Ein-/Ausgaben werden Ereignisse für generative KI-Agents angezeigt. Weitere Informationen zu diesen Ereignissen

     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 der generativen KI:

     

   • Auf dem Tab Logs und Ereignisse werden Logeinträge und Ereignisse aufgeführt, die mit dem Bereich verknüpft sind. Wenn Sie die Logdaten 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 Beispiel-Lauf enthält die JSON-Nutzlast beispielsweise den folgenden Inhalt:

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

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