Configura el registro

El registro es esencial para comprender y depurar el comportamiento de tus agentes. Cuando implementas un agente en el tiempo de ejecución del agente, puedes usar Cloud Logging para hacer un seguimiento de la actividad, supervisar la ejecución y optimizar el rendimiento. En este documento, se describen los métodos para escribir y ver registros de tus agentes.

Para trabajar con Cloud Logging en agentes cuando se implementan en el tiempo de ejecución del agente, usa uno de los siguientes métodos:

stdout o stderr: De forma predeterminada (sin ninguna 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 texto.
Registro de Python: El registrador integrado de Python se puede integrar con Cloud Logging. En comparación con la escritura en stdout o stderr, esto 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 (por ejemplo, configurar el logName y el tipo de recurso).

Escribe registros para un agente

Cuando escribas registros para un agente, determina lo siguiente:

severity: Como info, warn, error
payload: El contenido del registro (como texto o JSON)
additional fields: Para la correlación entre registros (como seguimiento/intervalo, etiquetas)

Por ejemplo, para registrar la entrada de cada consulta cuando desarrollas 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
        )

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

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

Cuando se implementa y se consulta el agente, se generan entradas de registro. Por ejemplo, el siguiente código:

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

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

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

Visualiza los registros de un agente

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

Para obtener permiso para ver los registros en Explorador de registros, pídele a tu administrador que te otorgue el rol de Visualizador de registros (roles/logging.viewer) en tu proyecto.
Ve al Explorador de registros en la Google Cloud consola:

Ir al Explorador de registros
Selecciona tu Google Cloud proyecto (que corresponde a PROJECT_ID) en la parte superior de la página.
En Tipo de recurso, selecciona Motor de razonamiento de la plataforma del agente de Gemini Enterprise.

Para los agentes basados en el Kit de desarrollo de agentes, también puedes ver los registros de tu agente en la Google Cloud consola con el panel de Tiempo de ejecución del agente.

Consultas de tiempo de ejecución

Puedes filtrar los registros en Cloud Logging por cada operación admitida de un agente implementado. Para ello, filtra los registros según el extremo REST subyacente para cada consulta de operación:

POST /api/reasoning_engine: Para las consultas que se realizan a métodos síncronos y asíncronos.
POST /api/stream_reasoning_engine: Para las consultas que se realizan a métodos de transmisión y transmisión asíncrona.
POST /api/bidi_reasoning_engine: Para las consultas que se realizan a métodos de transmisión bidireccional.

Las consultas de tiempo de ejecución se enrutan a los extremos REST según el campo api_mode en la lista de operaciones admitidas de un agente implementado.

Crea consultas

Puedes usar el Explorador de registros para crear consultas de forma incremental. Las consultas suelen crearse en función de las siguientes consideraciones:

timeline: Para buscar entradas de registro relevantes según la hora
scope: Para buscar entradas de registro relevantes según los atributos canónicos
- resource: Sepáralo de otros tipos de recursos de tu proyecto.
  - type: Aparece como "Motor de razonamiento de la plataforma del agente de Gemini Enterprise" en el Explorador de registros y "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: El registro al que pertenece la entrada de registro:
  - Las entradas de registro en el momento de la compilación tienen el ID de registro reasoning_engine_build.
  - Las entradas de registro para stdout y stderr tienen el ID de registro reasoning_engine_stdout y reasoning_engine_stderr, respectivamente.
  - Las entradas de registro del registro de Python o del cliente de Cloud Logging tendrán IDs de registro personalizados según tu código en Escribe registros para un agente.
- trace y span: Para los registros cuando se rastrean consultas.
- severity: Para la gravedad de la entrada de registro.
- insertId: El identificador único de una entrada de registro.
labels: 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 registros y facilitar su búsqueda en el Explorador de registros.
payload: 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://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 con URL y los demás 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 detalles, visita Crea y guarda consultas con el lenguaje de consultas de Logging.

Consulta registros de un agente

Para un enfoque programático para consultar registros, existen dos opciones comunes:

Lenguaje de consulta estructurado (SQL). Análisis de registros te permite consultar vistas de registros o vistas de análisis.
- Las vistas de registros tienen un esquema fijo que corresponde a las entradas de registro.
- Las vistas de análisis 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 un LogEntry. Para obtener detalles sobre los argumentos de entrada de logger.list_entries, consulta la referencia de la API.

SQL

Vista de registros:

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

Vista de análisis:

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

Configura el registro Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Escribe registros para un agente

stdout o stderr

Registro de Python

Cliente de Cloud Logging

stdout o stderr

Registro de Python

Cliente de Cloud Logging

Visualiza los registros de un agente

Consultas de tiempo de ejecución

Crea consultas

Consulta registros de un agente

Python

SQL

Configura el registro