Se usó la API de Cloud Translation para traducir esta página.

Cómo registrar un agente

Para trabajar con Cloud Logging en agentes cuando se implementan en el entorno de ejecución de Vertex AI Agent Engine, usa uno de los siguientes métodos:

stdout / 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, 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).

Escribe registros para un agente

Cuando escribas registros para un agente, determina lo siguiente:

gravedad: p.ej., info, warn, error
payload: Es el contenido del registro (p. ej., texto o JSON).
additional fields: Para correlacionar registros (p.ej., seguimiento/intervalo, etiquetas, rótulos)

Por ejemplo, para registrar la entrada de cada búsqueda 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
        )

Logging 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 el agente se implemente y se le realicen consultas, 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"})

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

Logging 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 el 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 consola de Google Cloud :

Ir al Explorador de registros
Selecciona tu proyecto de Google Cloud (que corresponde a PROJECT_ID) en la parte superior de la página.
En Tipo de recurso, selecciona Vertex AI Agent Builder Reasoning Engine.

En el caso de 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 Vertex AI Agent Engine.

Consultas de tiempo de ejecución

Puedes filtrar los registros en Cloud Logging por cada operación compatible de un agente implementado. Para ello, filtra los registros según el extremo de REST subyacente de 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 los métodos de transmisión y transmisión asíncrona.
POST /api/bidi_reasoning_engine: Para las consultas que se realizan a los métodos de transmisión bidireccional.

Las consultas de tiempo de ejecución se enrutan a los extremos de 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 atributos canónicos
- recurso: Sepáralo de otros tipos de recursos en tu proyecto.
  - type: Aparece como "Vertex AI Agent Builder 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 momento de la 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 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 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.

A continuación, se muestra un ejemplo de una consulta para todos los registros de 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 como 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 Compila y guarda consultas con el lenguaje de consulta de Logging.

Registros de consultas 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 análisis.
- Los registros de vistas 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, visita la referencia de la API.

SQL

Vista de registros:

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

Vista de Analytics:

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

Cómo registrar un agente Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Escribe registros para un agente

stdout o stderr

Logging de Python

Cliente de Cloud Logging

stdout o stderr

Logging de Python

Cliente de Cloud Logging

Visualiza los registros de un agente

Consultas de tiempo de ejecución

Crea consultas

Registros de consultas de un agente

Python

SQL

Cómo registrar un agente