Esta página foi traduzida pela API Cloud Translation.

Como registrar um agente

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

stdout / stderr: por padrão (sem configuração adicional), os registros gravados em stdout e stderr são encaminhados para os IDs de registro reasoning_engine_stdout e reasoning_engine_stderr, respectivamente. A limitação é que eles precisam ser texto.
Geração de registros em 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 requer configuração mínima.
Cliente do Cloud Logging: os usuários podem gravar registros estruturados e têm controle total sobre o logger (por exemplo, definindo o logName e o tipo de recurso).

Gravar registros para um agente

Ao gravar registros para um agente, determine o seguinte:

severity: por exemplo, info, warn, error
payload: o conteúdo do registro (por exemplo, texto ou JSON).
Campos adicionais: para correlação entre registros (por exemplo, rastreamento/intervalo, 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 em 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

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

Ver registros de um agente

É possível ver as entradas de registro usando o Explorador de registros:

Para receber permissão para ver registros no Explorador de registros, peça ao administrador para conceder a você o papel de Leitor de registros (roles/logging.viewer) no seu projeto.
Acesse o Explorador de registros no console do Google Cloud :

Acessar a Análise de registros
Selecione seu projeto Google Cloud (correspondente a PROJECT_ID) na parte de cima da página.
Em Tipo de recurso, selecione Reasoning Engine do Vertex AI Agent Builder.

Para agentes baseados no Kit de Desenvolvimento de Agente, também é possível conferir os registros do agente no console Google Cloud usando o painel do Vertex AI Agent Engine.

Consultas de tempo de execução

É possível filtrar os 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 de 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 aos métodos de streaming e streaming assíncrono.
POST /api/bidi_reasoning_engine: para consultas feitas aos métodos de streaming bidirecional.

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

Como criar consultas

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

timeline: para pesquisar entradas de registro relevantes com base no tempo
scope: 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 "Vertex AI Agent Builder Reasoning Engine" no Explorador 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 build têm o ID reasoning_engine_build.
  - As entradas de registro para stdout e stderr têm 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 seu código em Gravar registros para um agente.
- trace e span: para os registros ao consultar rastreamentos.
- 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 no Explorador de registros.
payload: o conteúdo da entrada de registro.

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

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

É possível conferir no Explorador 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 nos últimos 30 minutos ou PT10M nos últimos 10 minutos.
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 de consulta de registros, há duas opções comuns:

Structured Query Language (SQL). Com a Análise de Dados de Registros, é possível 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 usando a biblioteca de cliente da sua 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 de logger.list_entries, acesse a referência da API.

SQL

Visualização de registros:

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

Vista do Google Analytics:

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

Como registrar um agente Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gravar registros para um agente

stdout ou stderr

Registro em Python

Cliente do Cloud Logging

stdout ou stderr

Registro em Python

Cliente do Cloud Logging

Ver registros de um agente

Consultas de tempo de execução

Como criar consultas

Consultar registros de um agente

Python

SQL

Como registrar um agente