Esta página foi traduzida pela API Cloud Translation.

Registar um agente

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

stdout / stderr: por predefinição (sem configuração adicional), os registos escritos em stdout e stderr são encaminhados para os IDs de registo reasoning_engine_stdout e reasoning_engine_stderr, respetivamente. A limitação é que têm de ser texto.
Registo do Python: o registo do Python integrado pode ser integrado com o Cloud Logging. Em comparação com a escrita para stdout ou stderr, esta opção suporta registos estruturados e requer uma configuração mínima.
Cliente do Cloud Logging: os utilizadores podem escrever registos estruturados e têm controlo total sobre o registador (por exemplo, definir o logName e o tipo de recurso).

Escreva registos para um agente

Quando escreve registos para um agente, determine o seguinte:

gravidade: por exemplo, info, warn, error
payload: o conteúdo do registo (por exemplo, texto ou JSON)
campos adicionais: para correlação entre registos (por exemplo, rastreio/intervalo, etiquetas)

Por exemplo, para registar a entrada de cada consulta quando desenvolve 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
        )

Registo 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 é implementado e consultado, gera entradas de registo. 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 registo semelhante à seguinte:

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

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

Veja os registos de um agente

Pode ver as entradas de registo através do Explorador de registos:

Para receber autorização para ver registos no Explorador de registos, peça ao seu administrador para lhe conceder a função de Leitor de registos (roles/logging.viewer) no seu projeto.
Aceda ao Explorador de registos na Google Cloud consola:

Aceda ao Explorador de registos
Selecione o seu Google Cloud projeto (correspondente a PROJECT_ID) na parte superior da página.
Em Tipo de recurso, selecione Motor de raciocínio do Vertex AI Agent Builder.

Para agentes baseados no Agent Development Kit, também pode ver registos do seu agente na Google Cloud consola através do painel de controlo do Vertex AI Agent Engine.

Consultas de tempo de execução

Pode filtrar os registos no Cloud Logging por cada operação suportada de um agente implementado. Para tal, filtre os registos com base no ponto final 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 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 para os pontos finais REST consoante o campo api_mode na lista de operações suportadas de um agente implementado.

Criar consultas

Pode usar o Explorador de registos para criar consultas de forma incremental. As consultas são normalmente criadas com base nas seguintes considerações:

timeline: para pesquisar entradas de registo relevantes com base na hora
scope: para pesquisar entradas de registo relevantes com base em atributos canónicos
- recurso: separe-o de outros tipos de recursos no seu projeto.
  - type: aparece como "Vertex AI Agent Builder Reasoning Engine" no Logs Explorer e "aiplatform.googleapis.com/ReasoningEngine" na entrada do registo.
  - labels: para a localização (LOCATION), o projeto PROJECT_ID e o recurso RESOURCE_ID.
- logName: o registo ao qual a entrada do registo pertence:
  - As entradas do registo no momento da compilação têm o ID do registo reasoning_engine_build.
  - As entradas do registo para stdout e stderr têm o ID do registo reasoning_engine_stdout e reasoning_engine_stderr, respetivamente.
  - As entradas de registo do registo do Python ou do cliente do Cloud Logging vão ter IDs de registo personalizados com base no seu código em Escreva registos para um agente.
- trace e span: para os registos quando rastreia consultas.
- gravidade: para a gravidade da entrada do registo.
- insertId: o identificador exclusivo de uma entrada do registo.
labels: um mapa de pares de chave-valor que fornece informações adicionais sobre a entrada do registo. As etiquetas podem ser definidas pelo utilizador ou pelo sistema e são úteis para categorizar registos e facilitar a respetiva pesquisa no Explorador de registos.
payload: o conteúdo da entrada de registo.

Segue-se um exemplo de uma consulta para todos os registos INFO de um agente implementado com RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Pode vê-lo no Explorador de registos 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

onde a consulta foi devidamente codificada em URL e os outros parâmetros são os seguintes:

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

Para obter detalhes, consulte o artigo Crie e guarde consultas através da linguagem de consulta de registo.

Registos de consultas de um agente

Para uma abordagem programática aos registos de consultas, existem duas opções comuns:

Linguagem de consulta estruturada (SQL). O Log Analytics permite-lhe consultar visualizações de registos ou visualizações de estatísticas.
- As visualizações de registos têm um esquema fixo que corresponde a entradas de registos.
- As visualizações de propriedades do Analytics têm um esquema baseado nos resultados de uma consulta SQL.
Python. Chame a API Cloud Logging através da biblioteca cliente para a 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 corresponde a um LogEntry. Para ver detalhes sobre os argumentos de entrada para logger.list_entries, visite a referência da API.

SQL

Vista de registos:

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

Vista do Analytics:

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

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

Escreva registos para um agente

stdout ou stderr

Registo do Python

Cliente do Cloud Logging

stdout ou stderr

Registo do Python

Cliente do Cloud Logging

Veja os registos de um agente

Consultas de tempo de execução

Criar consultas

Registos de consultas de um agente

Python

SQL

Registar um agente