Questa pagina è stata tradotta dall'API Cloud Translation.

Registrazione di un agente

Per utilizzare Cloud Logging negli agenti quando vengono sottoposti a deployment nel runtime di Vertex AI Agent Engine, utilizza uno dei seguenti metodi:

stdout / stderr: per impostazione predefinita (senza alcuna configurazione aggiuntiva), i log scritti su stdout e stderr verranno indirizzati rispettivamente agli ID log reasoning_engine_stdout e reasoning_engine_stderr. Il limite è che devono essere di tipo testo.
Logging Python: il logger Python integrato può essere integrato con Cloud Logging. Rispetto alla scrittura su stdout o stderr, questa opzione supporta i log strutturati e richiede una configurazione minima.
Client Cloud Logging: gli utenti possono scrivere log strutturati e hanno il controllo completo del logger (ad esempio, impostando logName e il tipo di risorsa).

Scrivere i log per un agente

Quando scrivi i log per un agente, determina quanto segue:

severity: ad es. info, warn, error
payload: i contenuti del log (ad es. testo o JSON)
campi aggiuntivi: per la correlazione tra i log (ad es. traccia/span, tag, etichette)

Ad esempio, per registrare l'input di ogni query durante lo sviluppo di un agente:

stdout o 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
        )

Logging Python

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

Client Cloud 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.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,
        )

Quando l'agente viene implementato e interrogato, genera voci di log. Ad esempio, il codice

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

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

genera una voce di log simile alla seguente:

stdout o 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"
}

Logging Python

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

Client Cloud 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-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"
}

Visualizzare i log per un agente

Puoi visualizzare le voci di log utilizzando Esplora log:

Per ottenere l'autorizzazione a visualizzare i log in Esplora log, chiedi all'amministratore di concederti il ruolo Visualizzatore log (roles/logging.viewer) sul progetto.
Vai a Esplora log nella console Google Cloud :

Vai a Esplora log
Seleziona il tuo progetto Google Cloud (corrispondente a PROJECT_ID) nella parte superiore della pagina.
In Tipo di risorsa, seleziona Vertex AI Agent Builder Reasoning Engine.

Per gli agenti basati su Agent Development Kit, puoi anche visualizzare i log del tuo agente nella console Google Cloud utilizzando la dashboard di Vertex AI Agent Engine.

Query di runtime

Puoi filtrare i log in Cloud Logging in base a ogni operazione supportata di un agente di deployment. Per farlo, filtra i log in base all'endpoint REST sottostante per ogni query di operazione:

POST /api/reasoning_engine: per le query effettuate con metodi sincroni e asincroni.
POST /api/stream_reasoning_engine: per le query effettuate ai metodi streaming e streaming asincrono.
POST /api/bidi_reasoning_engine: Per le query effettuate ai metodi di streaming bidirezionale.

Le query di runtime vengono indirizzate agli endpoint REST a seconda del campo api_mode nell'elenco delle operazioni supportate di un agente di cui è stato eseguito il deployment.

Creazione di query

Puoi utilizzare Esplora log per creare query in modo incrementale. Le query vengono generalmente create in base alle seguenti considerazioni:

timeline: per cercare voci di log pertinenti in base all'ora
scope: per cercare voci di log pertinenti in base agli attributi canonici
- risorsa: separala dagli altri tipi di risorse nel progetto.
  - type: viene visualizzato come "Vertex AI Agent Builder Reasoning Engine" in Esplora log e "aiplatform.googleapis.com/ReasoningEngine" nella voce di log.
  - labels: per la località (LOCATION), il progetto PROJECT_ID e la risorsa RESOURCE_ID.
- logName: il log a cui appartiene la voce di log:
  - Le voci di log in fase di compilazione hanno l'ID log reasoning_engine_build.
  - Le voci di log per stdout e stderr hanno rispettivamente ID log reasoning_engine_stdout e reasoning_engine_stderr.
  - Le voci di log di python logging o del client Cloud Logging avranno ID log personalizzati in base al codice in Scrivere log per un agente.
- Traccia e intervallo: per i log durante il tracciamento delle query.
- severity: per la gravità della voce di log.
- insertId: l'identificatore univoco di una voce di log.
etichette: una mappa di coppie chiave-valore che fornisce ulteriori informazioni sulla voce di log. Le etichette possono essere definite dall'utente o dal sistema e sono utili per classificare i log e semplificarne la ricerca in Esplora log.
payload: i contenuti della voce di log.

Di seguito è riportato un esempio di query per tutti i log INFO di un agente di cui è stato eseguito il deployment con RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Puoi visualizzarlo in Esplora log all'indirizzo

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

dove la query è stata codificata correttamente in URL e gli altri parametri sono i seguenti:

DURATION: ad esempio PT30M per gli ultimi 30 minuti (o PT10M per gli ultimi 10 minuti) e
PROJECT_ID: il Google Cloud progetto.

Per informazioni dettagliate, consulta Creare e salvare query utilizzando il linguaggio di query di Logging.

Esegui query sui log per un agente

Per un approccio programmatico ai log delle query, esistono due opzioni comuni:

Structured Query Language (SQL). Analisi dei log consente di eseguire query su viste log o viste Analytics.
- Le visualizzazioni log hanno uno schema fisso che corrisponde alle voci di log.
- Le viste Analytics hanno uno schema basato sui risultati di una query SQL.
Python. Chiama l'API Cloud Logging tramite la libreria client per il tuo linguaggio di programmazione (Python in questo caso).

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

Ogni entry corrisponderà a un LogEntry. Per informazioni dettagliate sugli argomenti di input di logger.list_entries, consulta il riferimento API.

SQL

Visualizzazione log:

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

Vista Analytics:

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

Registrazione di un agente Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Scrivere i log per un agente

stdout o stderr

Logging Python

Client Cloud Logging

stdout o stderr

Logging Python

Client Cloud Logging

Visualizzare i log per un agente

Query di runtime

Creazione di query

Esegui query sui log per un agente

Python

SQL

Registrazione di un agente