Cómo registrar un agente

Para trabajar con Cloud Logging en los agentes cuando se implementan, usa uno de los siguientes métodos:

• stdout / stderr: De forma predeterminada (sin configuración adicional), los registros escritos en stdout y stderr se enrutarán a los IDs de registro reasoning_engine_stdout y reasoning_engine_stderr, respectivamente. La limitación es que deben ser de texto.
• Registro de Python: El registrador de Python integrado se puede integrar a Cloud Logging. En comparación con la escritura en stdout o stderr, esta opción admite registros estructurados y requiere una configuración mínima.
• Cliente de Cloud Logging: Los usuarios pueden escribir registros estructurados y tienen control total sobre el registrador (p.ej., configurar el logName y el tipo de recurso).

Cómo escribir registros para un agente

Cuando escribas registros para un agente, determina lo siguiente:

• severity: p.ej., info, warn, error
• Carga útil: Es el contenido del registro (p. ej., texto o JSON).
• Campos adicionales: Para correlacionar entre registros (p. ej., seguimiento/intervalo, etiquetas, rótulos).

Por ejemplo, para registrar la entrada de cada consulta cuando desarrollas un agente, haz lo siguiente:

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
        )

Registro de 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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

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

Cliente de 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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

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

Cuando el agente se implemente y se consulte, generará entradas de registro. Por ejemplo, el código

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

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

generará una entrada de registro similar a la siguiente:

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

Registro de 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"
}

Cliente de 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"
}

Cómo ver los registros de un agente

Puedes ver tus entradas de registro con el Explorador de registros:

1. Ve al Explorador de registros en la consola de Google Cloud:

   Ir al Explorador de registros

2. Selecciona tu Google Cloud proyecto (que corresponde a PROJECT_ID) en la parte superior de la página.

3. En Tipo de recurso, selecciona Motor de razonamiento Vertex AI.

Crea consultas

Puedes usar el Explorador de registros para compilar consultas de forma incremental. Por lo general, las consultas se compilan en función de las siguientes consideraciones:

• timeline: Para buscar entradas de registro relevantes según el tiempo
• alcance: Para buscar entradas de registro relevantes según los atributos canónicos.
  • resource: Separarlo de otros tipos de recursos en tu proyecto
    • type: Aparece como "Vertex AI Reasoning Engine" en el Explorador de registros y como "aiplatform.googleapis.com/ReasoningEngine" en la entrada de registro.
    • labels: Para la ubicación (LOCATION), el proyecto PROJECT_ID y el recurso RESOURCE_ID.
  • logName: Es el registro al que pertenece la entrada de registro:
    • Las entradas de registro en el tiempo de compilación tienen el ID de registro reasoning_engine_build.
    • Las entradas de registro de stdout y stderr tienen los IDs de registro reasoning_engine_stdout y reasoning_engine_stderr, respectivamente.
    • Las entradas de registro del cliente de Cloud Logging o de Python tendrán IDs de registro personalizados según tu código en Cómo escribir registros para un agente.
  • trace y span: Para los registros cuando se hace un seguimiento de las consultas.
  • severity: Para la gravedad de la entrada de registro.
  • insertId: Es el identificador único de una entrada de registro.
• labels: Es un mapa de pares clave-valor que proporciona información adicional sobre la entrada de registro. Las etiquetas pueden ser definidas por el usuario o por el sistema, y son útiles para categorizar los registros y facilitar su búsqueda en el Explorador de registros.
• payload: Es el contenido de la entrada de registro.

El siguiente es un ejemplo de una consulta para todos los registros INFO de un agente implementado con RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Puedes verlo en el Explorador de registros en

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

donde la consulta se codificó correctamente como URL y los otros parámetros son los siguientes:

• DURATION: por ejemplo, PT30M para los últimos 30 minutos (o PT10M para los últimos 10 minutos)
• PROJECT_ID: El Google Cloud proyecto.

Para obtener más información, consulta Compila y guarda consultas con el lenguaje de consulta de Logging.

Nota: El Explorador de registros no admite operaciones agregadas, como contar la cantidad de entradas de registro que contienen un patrón específico. Para ver consultas más avanzadas que abarcan operaciones agregadas y mucho más, consulta Cómo consultar registros de un agente.

Consulta los registros de un agente

Para un enfoque programático de consulta de registros, existen dos opciones comunes:

• Lenguaje de consulta estructurado (SQL). Análisis de registros te permite consultar vistas de registros o vistas de estadísticas.
  • Las vistas de registro tienen un esquema fijo que corresponde a las entradas de registro.
  • Las vistas de Analytics tienen un esquema que se basa en los resultados de una consulta en SQL.

• Python. Llama a la API de Cloud Logging a través de la biblioteca cliente de tu lenguaje de programación (Python en este 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))

Cada entry corresponderá a una LogEntry. Para obtener detalles sobre los argumentos de entrada de logger.list_entries, consulta la referencia de la API.

SQL

Vista de registro:

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

Vista de Analytics:

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