Cómo configurar el registro

Cloud Trace te permite analizar el rendimiento de tus agentes mediante el seguimiento de la cronología de las operaciones de cada consulta. Puedes usar los seguimientos para identificar cuellos de botella y comprender las interacciones con modelos de lenguaje grandes (LLM) o herramientas.

En este documento, se explica cómo habilitar Trace para tus agentes y cómo ver y analizar los seguimientos en la consola de Google Cloud .

Un seguimiento es un cronograma de solicitudes a medida que tu agente responde a cada consulta. Por ejemplo, en el siguiente gráfico, se muestra un seguimiento de ejemplo de un agente del Kit de desarrollo de agentes (ADK):

Un seguimiento se compone de intervalos individuales, que representan una sola unidad de trabajo, como una llamada a función o una interacción con un LLM, y el primer intervalo representa la solicitud general. Cada intervalo proporciona detalles sobre una operación específica, como el nombre, las horas de inicio y finalización, y cualquier atributo pertinente, dentro de la solicitud. Por ejemplo, el siguiente JSON muestra un solo intervalo que representa una llamada a un modelo de lenguaje grande (LLM):

  {
    "name": "llm",
    "context": {
        "trace_id": "ed7b336d-e71a-46f0-a334-5f2e87cb6cfc",
        "span_id": "ad67332a-38bd-428e-9f62-538ba2fa90d4"
    },
    "span_kind": "LLM",
    "parent_id": "f89ebb7c-10f6-4bf8-8a74-57324d2556ef",
    "start_time": "2023-09-07T12:54:47.597121-06:00",
    "end_time": "2023-09-07T12:54:49.321811-06:00",
    "status_code": "OK",
    "status_message": "",
    "attributes": {
        "llm.input_messages": [
            {
                "message.role": "system",
                "message.content": "You are an expert Q&A system that is trusted around the world.\nAlways answer the query using the provided context information, and not prior knowledge.\nSome rules to follow:\n1. Never directly reference the given context in your answer.\n2. Avoid statements like 'Based on the context, ...' or 'The context information ...' or anything along those lines."
            },
            {
                "message.role": "user",
                "message.content": "Hello?"
            }
        ],
        "output.value": "assistant: Yes I am here",
        "output.mime_type": "text/plain"
    },
    "events": [],
  }

Nota: El formato de los seguimientos y los intervalos depende de la opción de instrumentación que elijas. El intervalo de ejemplo es experimental y está sujeto a cambios, por lo que, por el momento, no debes confiar en que el formato sea estable. Para obtener más detalles, consulta las convenciones semánticas para sistemas de IA generativa que se están desarrollando en OpenTelemetry.

Para obtener más detalles, consulta la documentación de Cloud Trace sobre Seguimientos y intervalos y Contexto de seguimiento.

Antes de comenzar

Antes de recopilar y escribir seguimientos, debes habilitar APIs específicas y, además, instalar dependencias. Para obtener más información, consulta Recopila y visualiza instrucciones y respuestas multimodales en la documentación de Google Cloud Observability.

Escribe seguimientos para un agente

Para escribir seguimientos de un agente, haz lo siguiente:

ADK

Para habilitar OpenTelemetry para AdkApp, establece las siguientes variables de entorno cuando implementes el agente en Agent Runtime:

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
}

Ten en cuenta lo siguiente:

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY habilita los seguimientos, los registros y las métricas del agente (consulta Visualiza las métricas de un agente), pero no incluye los datos de las instrucciones ni de las respuestas.

• OTEL_SEMCONV_STABILITY_OPT_IN habilita el uso de las convenciones semánticas de IA generativa más recientes.

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT habilita el registro de las instrucciones de entrada, las respuestas de salida y los IDs de usuario (el campo user.id). Capturar estos detalles facilita la observabilidad de los agentes y la detección de anomalías, ya que se hace un seguimiento del uso y las interacciones a lo largo del tiempo.

  Nota: Asegúrate de tener los consentimientos, avisos y políticas de manejo de datos necesarios de los usuarios finales para recopilar esta información.
  Importante: El registro de user.id se incluye cuando se habilita la opción "Habilitar el registro de entradas de instrucciones y salidas de respuestas" a partir del 22 de mayo de 2026, con la versión 2.1 del kit de desarrollo de agentes. Si habilitaste la opción antes del 22 de mayo, tu registro no incluye user.id. Deberás volver a implementar tus agentes y habilitar la opción de nuevo para que se aplique este parámetro de configuración.

• Para usar la transferencia de seguimientos, debes habilitar la API de Telemetry. Para obtener más información, consulta la descripción general de la API de Telemetry (OTLP).

• Para usar la transferencia de registros, debes habilitar la API de Cloud Logging. Para obtener más información, consulta Descripción general de la API de Cloud Logging.

Nota: Si antes configurabas la marca enable_tracing, te recomendamos que uses las variables de entorno en su lugar. Por ejemplo, establece GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true en lugar de enable_tracing=true y GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false en lugar de enable_tracing=false.

LangchainAgent

Para habilitar el seguimiento de LangchainAgent, especifica enable_tracing=True cuando desarrolles un agente de LangChain. Por ejemplo:

from vertexai.agent_engines import LangchainAgent

agent = LangchainAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LanggraphAgent

Para habilitar el seguimiento de LanggraphAgent, especifica enable_tracing=True cuando desarrolles un agente de LangGraph. Por ejemplo:

from vertexai.agent_engines import LanggraphAgent

agent = LanggraphAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

Llamaindex

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para habilitar el seguimiento de LlamaIndexQueryPipelineAgent, especifica enable_tracing=True cuando desarrolles un agente de LlamaIndex. Por ejemplo:

from vertexai.preview import reasoning_engines

  def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
      from llama_index.core.query_pipeline import QueryPipeline
      from llama_index.core.tools import FunctionTool
      from llama_index.core.agent import ReActAgent

      llama_index_tools = []
      for tool in runnable_kwargs.get("tools"):
          llama_index_tools.append(FunctionTool.from_defaults(tool))
      agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
      return QueryPipeline(modules = {"agent": agent})

  agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
      model="gemini-3.5-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

Personalizado

Para habilitar el seguimiento de agentes personalizados, consulta Seguimiento con OpenTelemetry para obtener más detalles.

Esta acción exportará seguimientos a Cloud Trace en el proyecto en Configura tu proyecto de Google Cloud .

Visualiza los seguimientos de un agente

En el caso de los agentes implementados, puedes usar la consola de Google Cloud para ver los seguimientos de tu agente:

1. En la consola de Google Cloud , ve a la página Implementaciones de Agent Platform.
   

   Ir a Implementaciones

   Las instancias de Agent Platform que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.

2. Haz clic en el nombre de tu instancia de Agent Platform.

3. Haz clic en la pestaña Seguimientos.

4. Puedes seleccionar Vista de sesión o Vista de intervalo.

   Haz clic en una sesión o un intervalo para inspeccionar los detalles del seguimiento, incluido un grafo acíclico dirigido (DAG) de sus intervalos, entradas y salidas, y atributos de metadatos.

Cuotas y límites

Algunos valores de atributos pueden truncarse cuando alcancen los límites de cuota. Para obtener más información, consulta Cuota de Cloud Trace.

Precios

Cloud Trace tiene un nivel gratuito. Para obtener más información, consulta Precios de Cloud Trace.