Configurar a geração de registros

O registro é essencial para entender e depurar o comportamento dos agentes. Ao implantar um agente no ambiente de execução de agentes, é possível usar o Cloud Logging para monitorar atividade, monitorar a execução e otimizar o desempenho. Este documento descreve os métodos para gravar e visualizar registros dos agentes.

Para trabalhar com Cloud Logging em agentes quando eles são implantados no ambiente de execução de agentes, use um dos seguintes métodos:

stdout ou stderr: por padrão (sem nenhuma configuração adicional), os registros gravados em stdout e stderr serão encaminhados para os IDs de registro reasoning_engine_stdout e reasoning_engine_stderr, respectivamente. A limitação é que eles precisam ser de texto.
Registro do Python: o logger integrado do Python pode ser integrado ao Cloud Logging. Em comparação com a gravação em stdout ou stderr, isso oferece suporte a registros estruturados e exige configuração mínima.
Cliente do Cloud Logging: os usuários podem gravar registros estruturados e têm controle total sobre o logger (como definir o logName e o tipo de recurso).

Gravar registros de um agente

Ao gravar registros de um agente, determine o seguinte:

severity: como info, warn, error
payload: o conteúdo do registro (como texto ou JSON)
additional fields: para correlação entre registros (como trace/span, tags, rótulos)

Por exemplo, para registrar a entrada de cada consulta ao desenvolver um agente:

stdout ou 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 do 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 do 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 o agente é implantado e consultado, ele gera entradas de registro. Por exemplo, o código a seguir:

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

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

gera uma entrada de registro semelhante a esta:

stdout ou 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 do 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 do 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"
}

Visualizar registros de um agente

É possível visualizar as entradas de registro usando a Análise de registros:

Para receber permissão para visualizar registros no Análise de registros, peça ao administrador para conceder a você o papel de visualizador de registros (roles/logging.viewer) no seu projeto.
Acesse o Análise de registros no Google Cloud console:

Acessar a Análise de registros
Selecione seu Google Cloud projeto (correspondente a PROJECT_ID) na parte de cima da página.
Em Tipo de recurso, selecione Mecanismo de raciocínio da plataforma de agentes do Gemini Enterprise.

Para agentes baseados no Kit de desenvolvimento de agentes, também é possível visualizar os registros do agente em o Google Cloud console usando o painel do ambiente de execução de agentes.

Consultas de tempo de execução

É possível filtrar registros no Cloud Logging por cada operação compatível de um agente implantado. Para fazer isso, filtre os registros com base no endpoint REST subjacente para cada consulta de operação:

POST /api/reasoning_engine: para consultas feitas a métodos síncronos e assíncronos.
POST /api/stream_reasoning_engine: para consultas feitas a métodos de streaming e streaming assíncrono.
POST /api/bidi_reasoning_engine: para consultas feitas a métodos de streaming bidirecional.

As consultas de tempo de execução são encaminhadas para os endpoints REST, dependendo do campo api_mode na lista de operações compatíveis de um agente implantado.

Como criar consultas

É possível usar a Análise de registros para criar consultas de forma incremental. As consultas são geralmente criadas com base nas seguintes considerações:

timeline: para pesquisar entradas de registro relevantes com base no tempo
escopo: para pesquisar entradas de registro relevantes com base em atributos canônicos
- resource: separe-o de outros tipos de recursos no seu projeto.
  - type: aparece como "Mecanismo de raciocínio da plataforma de agentes do Gemini Enterprise" na Análise de registros e "aiplatform.googleapis.com/ReasoningEngine" na entrada de registro.
  - labels: para o local (LOCATION), o projeto PROJECT_ID e o recurso RESOURCE_ID.
- logName: o registro a que a entrada de registro pertence:
  - As entradas de registro no momento da criação têm o ID de registro reasoning_engine_build.
  - As entradas de registro para stdout e stderr têm o ID de registro reasoning_engine_stdout e reasoning_engine_stderr, respectivamente.
  - As entradas de registro do registro do Python ou do cliente do Cloud Logging terão IDs de registro personalizados com base no código em Gravar registros de um agente.
- trace e span: para os registros ao rastrear consultas.
- severity: para a gravidade da entrada de registro.
- insertId: o identificador exclusivo de uma entrada de registro.
labels: um mapa de pares de chave-valor que fornece informações adicionais sobre a entrada de registro. Os rótulos podem ser definidos pelo usuário ou pelo sistema e são úteis para categorizar registros e facilitar a pesquisa deles na Análise de registros.
payload: o conteúdo da entrada de registro.

Confira a seguir um exemplo de consulta para todos os INFO registros de um agente implantado com RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

É possível visualizar no Análise de registros em

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

em que a consulta foi codificada por URL de maneira adequada e os outros parâmetros são os seguintes:

DURATION: por exemplo, PT30M para os últimos 30 minutos (ou PT10M para os últimos 10 minutos) e
PROJECT_ID: o Google Cloud projeto.

Para mais detalhes, acesse Criar e salvar consultas usando a linguagem de consulta do Logging.

Consultar registros de um agente

Para uma abordagem programática para consultar registros, há duas opções comuns:

Structured Query Language (SQL). A Análise de dados de registros permite consultar visualizações de registros ou visualizações de análise.
- As visualizações de registros têm um esquema fixo que corresponde às entradas de registro.
- As visualizações de análise têm um esquema baseado nos resultados de uma consulta SQL.
Python. Chame a API Cloud Logging pela biblioteca de cliente da linguagem de programação (Python, neste 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 vai corresponder a um LogEntry. Para detalhes sobre os argumentos de entrada para logger.list_entries, acesse a referência da API.

SQL

Visualização de registros:

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

Visualização de análise:

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

Configurar a geração de registros Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gravar registros de um agente

stdout ou stderr

Registro do Python

Cliente do Cloud Logging

stdout ou stderr

Registro do Python

Cliente do Cloud Logging

Visualizar registros de um agente

Consultas de tempo de execução

Como criar consultas

Consultar registros de um agente

Python

SQL

Configurar a geração de registros