Diese Seite wurde von der Cloud Translation API übersetzt.

Agent protokollieren

Wenn Sie mit Cloud Logging in Agenten arbeiten möchten, die in der Vertex AI Agent Engine-Laufzeit bereitgestellt werden, verwenden Sie eine der folgenden Methoden:

stdout / stderr: Standardmäßig (ohne zusätzliche Einrichtung) werden Logs, die in stdout und stderr geschrieben werden, an die Log-IDs reasoning_engine_stdout bzw. reasoning_engine_stderr weitergeleitet. Die Einschränkung besteht darin, dass es sich um Text handeln muss.
Python-Logging: Der integrierte Python-Logger kann in Cloud Logging eingebunden werden. Im Vergleich zum Schreiben in stdout oder stderr werden hier strukturierte Logs unterstützt und es ist nur eine minimale Einrichtung erforderlich.
Cloud Logging-Client: Nutzer können strukturierte Logs schreiben und haben die vollständige Kontrolle über den Logger (z.B. Festlegen von logName und Ressourcentyp).

Logs für einen Agenten schreiben

Wenn Sie Logs für einen Agent schreiben, müssen Sie Folgendes festlegen:

severity: z.B. info, warn, error
payload: Der Inhalt des Logs, z. B. Text oder JSON.
Zusätzliche Felder: zum Korrelieren von Logs (z.B. Trace/Span, Tags, Labels)

Wenn Sie beispielsweise die Eingabe jeder Anfrage protokollieren möchten, wenn Sie einen Agenten entwickeln:

stdout oder stderr

from typing import Dict

class MyAgent:

    def set_up(self):
        # No set up required. The logs from stdout and stderr are routed to
        # `reasoning_engine_stdout` and `reasoning_engine_stderr` respectively.
        pass

    def query(self, input: Dict):
        import sys

        print(
            f"input: {input}",
            file=sys.stdout,  # or sys.stderr
        )

Python-Logging

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logging_client.setup_logging(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        import logging
        import json

        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        logging.info( # or .warning(), .error()
            json.dumps(input),
            extra=logging_extras,
        )

Cloud Logging-Client

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logger = self.logging_client.logger(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        self.logger.log_struct(
            input,
            severity="INFO",  # or "DEBUG", "WARNING", "ERROR", "CRITICAL"
            **logging_extras,
        )

Wenn der Agent bereitgestellt und abgefragt wird, werden Logeinträge generiert. Beispiel: Der Code

remote_agent = agent_engines.create(
    MyAgent(),
    requirements=["cloudpickle==3", "google-cloud-logging"],
)

remote_agent.query(input={"hello": "world"})

generiert einen Logeintrag wie den folgenden:

stdout oder stderr

{
  "insertId": "67a3bb3b000cc2df444361ab",
  "textPayload": "input: {'hello': 'world'}",
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID"
    }
  },
  "timestamp": "2025-02-05T19:25:47.836319Z",
  "logName": "projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout",  # or `*_stderr`
  "receiveTimestamp": "2025-02-05T19:25:47.842550772Z"
}

Python-Logging

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-02-05T20:30:19.348067Z",
  "severity": "INFO",
  "labels": {
    "foo": "bar",
    "python_logger": "root",
  },
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Cloud Logging-Client

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-01-30T21:38:50.776813191Z",
  "severity": "INFO",
  "labels": {"foo": "bar"},
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Logs für einen Agent ansehen

Sie können Ihre Logeinträge mit dem Log-Explorer aufrufen:

Bitten Sie Ihren Administrator, Ihnen die Rolle Logs Viewer (roles/logging.viewer) für Ihr Projekt zuzuweisen, um die Berechtigung zum Aufrufen von Logs im Logs Explorer zu erhalten.
Rufen Sie in der Google Cloud Console den Log-Explorer auf:

Zum Log-Explorer
Wählen Sie oben auf der Seite Ihr Google Cloud -Projekt (entsprechend PROJECT_ID) aus.
Wählen Sie unter Ressourcentyp die Option Vertex AI Agent Builder Reasoning Engine aus.

Bei Agenten, die auf dem Agent Development Kit basieren, können Sie sich die Logs für Ihren Agenten auch in der Google Cloud -Konsole über das Vertex AI Agent Engine-Dashboard ansehen.

Laufzeitabfragen

Sie können Logs in Cloud Logging nach jeder unterstützten Operation eines bereitgestellten Agents filtern. Filtern Sie dazu die Logs nach dem zugrunde liegenden REST-Endpunkt für jede Vorgangsanfrage:

POST /api/reasoning_engine: Für Anfragen an synchrone und asynchrone Methoden.
POST /api/stream_reasoning_engine: Für Anfragen an die Methoden streaming und async streaming.
POST /api/bidi_reasoning_engine: Für Anfragen an Bidi-Streaming-Methoden.

Laufzeitabfragen werden je nach dem Feld api_mode in der Liste der unterstützten Vorgänge eines bereitgestellten Agents an die REST-Endpunkte weitergeleitet.

Abfragen erstellen

Mit dem Log-Explorer können Sie Abfragen inkrementell erstellen. Abfragen werden in der Regel auf Grundlage der folgenden Überlegungen erstellt:

Zeitachse: Damit können Sie anhand der Zeit nach relevanten Logeinträgen suchen.
scope: Damit können Sie anhand kanonischer Attribute nach relevanten Logeinträgen suchen.
- Ressource: Trennen Sie sie von anderen Ressourcentypen in Ihrem Projekt.
  - type: Wird im Logs Explorer als „Vertex AI Agent Builder Reasoning Engine“ und im Logeintrag als "aiplatform.googleapis.com/ReasoningEngine" angezeigt.
  - labels: für den Standort (LOCATION), das Projekt PROJECT_ID und die Ressource RESOURCE_ID.
- logName: Das Log, zu dem der Logeintrag gehört:
  - Die Logeinträge zur Build-Zeit haben die Log-ID reasoning_engine_build.
  - Die Logeinträge für stdout und stderr haben die Log-IDs reasoning_engine_stdout bzw. reasoning_engine_stderr.
  - Die Logeinträge aus dem Python-Logging- oder Cloud Logging-Client haben benutzerdefinierte Log-IDs, die auf Ihrem Code unter Logs für einen Agent schreiben basieren.
- trace und span: für die Logs beim Tracing von Abfragen.
- severity: für den Schweregrad des Logeintrags.
- insertId: Die eindeutige Kennung für einen Logeintrag.
labels: Eine Zuordnung von Schlüssel/Wert-Paaren, die zusätzliche Informationen zum Logeintrag enthält. Die Labels können benutzerdefiniert oder systemdefiniert sein. Sie sind nützlich, um Logs zu kategorisieren und die Suche nach ihnen im Log-Explorer zu erleichtern.
payload: der Inhalt des Logeintrags.

Das Folgende ist ein Beispiel für eine Abfrage für alle INFO-Logs eines bereitgestellten Agents mit RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Sie können sie im Log-Explorer unter

https://https://console.cloud.google.com/logs/query;query=severity%3DINFO%0Aresource.labels.reasoning_engine_id%3D%22RESOURCE_ID%22;duration=DURATION?project=PROJECT_ID

Dabei wurde die Abfrage entsprechend URL-codiert und die anderen Parameter sind:

DURATION: z. B. PT30M für die letzten 30 Minuten oder PT10M für die letzten 10 Minuten.
PROJECT_ID: das Google Cloud Projekt.

Weitere Informationen finden Sie unter Abfragen mit der Logging-Abfragesprache erstellen und speichern.

Logs für einen Agent abfragen

Für einen programmatischen Ansatz zum Abfragen von Logs gibt es zwei gängige Optionen:

Structured Query Language (SQL). Mit Loganalysen können Sie Logdatenansichten oder Analytics-Datenansichten abfragen.
- Log-Ansichten haben ein festes Schema, das Logeinträgen entspricht.
- Analyseansichten haben ein Schema, das auf den Ergebnissen einer SQL-Abfrage basiert.
Python Rufen Sie die Cloud Logging API über die Clientbibliothek für Ihre Programmiersprache auf (in diesem Fall Python).

Python

from google.cloud import logging

logging_client = logging.Client(project="PROJECT_ID")
logger = logging_client.logger("LOG_ID")  # E.g. "logging_client"
print("Listing entries for logger {}:".format(logger.name))
for entry in logger.list_entries(
    filter_="resource.labels.reasoning_engine_id=RESOURCE_ID"  # Optional
):
    timestamp = entry.timestamp.isoformat()
    print("* {}: {}".format(timestamp, entry.payload))

Jeder entry entspricht einem LogEntry. Details zu den Eingabeargumenten für logger.list_entries finden Sie in der API-Referenz.

SQL

Logansicht:

SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

Analytics-Datenansicht:

SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`

Agent protokollieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Logs für einen Agenten schreiben

stdout oder stderr

Python-Logging

Cloud Logging-Client

stdout oder stderr

Python-Logging

Cloud Logging-Client

Logs für einen Agent ansehen

Laufzeitabfragen

Abfragen erstellen

Logs für einen Agent abfragen

Python

SQL

Agent protokollieren