Esta página se ha traducido con Cloud Translation API.

Registrar un agente

Para trabajar con Cloud Logging en agentes cuando se despliegan en el tiempo 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 dirigirá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 de Python integrado 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 (por ejemplo, pueden definir el logName y el tipo de recurso).

Escribir registros de un agente

Cuando escribas registros de un agente, determina lo siguiente:

Gravedad: por ejemplo, info, warn o error.
Carga útil: el contenido del registro (por ejemplo, texto o JSON).
Campos adicionales: para correlacionar registros (por ejemplo, trazas o intervalos, etiquetas)

Por ejemplo, para registrar la entrada de cada consulta al desarrollar 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("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 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"})

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

Ver 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, pide a tu administrador que te conceda el rol Lector de registros (roles/logging.viewer) en tu proyecto.
Ve a Explorador de registros en la consola de Google Cloud :

Ir a Explorador de registros
Selecciona tu Google Cloud proyecto (correspondiente 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 Agent Development Kit, también puedes ver los registros de tu agente en la Google Cloud consola mediante el panel de control de Vertex AI Agent Engine.

Consultas de tiempo de ejecución

Puedes filtrar los registros de Cloud Logging por cada operación admitida de un agente implementado. Para ello, filtra los registros en función del endpoint 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 realicen a los métodos streaming y streaming asíncrono.
POST /api/bidi_reasoning_engine: Para las consultas que se hacen a los métodos de streaming bidireccional.

Las consultas de tiempo de ejecución se dirigen a los endpoints REST en función del campo api_mode de la lista de operaciones admitidas de un agente implementado.

Crear consultas

Puedes usar el Explorador de registros para crear consultas de forma incremental. Las consultas se suelen crear en función de los siguientes aspectos:

Cronología: para buscar entradas de registro relevantes en función de la hora
scope: para buscar entradas de registro relevantes en función de los atributos canónicos.
- Recurso: sepáralo de otros tipos de recursos de tu proyecto.
  - type: se muestra como "Vertex AI Agent Builder Reasoning Engine" 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 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 de python logging o del cliente de Cloud Logging tendrán IDs de registro personalizados basados en tu código en Escribir registros de un agente.
- trace y span: para los registros cuando se rastrean consultas.
- severity: gravedad de la entrada de registro.
- insertId 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 clasificar los registros y facilitar su búsqueda en el Explorador de registros.
Carga útil: el contenido de la entrada de registro.

A continuación se muestra un ejemplo de consulta de 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 ha codificado como URL correctamente y los demás parámetros son los siguientes:

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

Para obtener más información, consulta el artículo Crear y guardar consultas con el lenguaje de consultas de registro.

Consultar los registros de un agente

Si quieres consultar los registros de forma programática, tienes dos opciones habituales:

Lenguaje de consulta estructurado (SQL). Analíticas de registros te permite consultar vistas de registros o vistas de analíticas.
- Las vistas de registro tienen un esquema fijo que corresponde a las entradas de registro.
- Las vistas de Analytics tienen un esquema basado en los resultados de una consulta de SQL.
Python. Llama a la API Cloud Logging a través de la biblioteca de cliente de tu lenguaje de programación (en este caso, 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))

Cada entry se corresponderá con un LogEntry. Para obtener información 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`

Registrar un agente Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Escribir registros de un agente

stdout o stderr

Registro de Python

Cliente de Cloud Logging

stdout o stderr

Registro de Python

Cliente de Cloud Logging

Ver los registros de un agente

Consultas de tiempo de ejecución

Crear consultas

Consultar los registros de un agente

Python

SQL

Registrar un agente