Cómo configurar el registro

Cloud Trace te permite analizar el rendimiento de tus agentes haciendo un seguimiento de la cronología de las operaciones para cada consulta. Puedes usar los registros 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 el registro de seguimiento para tus agentes y cómo ver y analizar los registros de seguimiento en la consola de Google Cloud .

Un registro es una línea de tiempo de las solicitudes a medida que tu agente responde a cada consulta. Por ejemplo, en el siguiente gráfico, se muestra un registro de muestra de un agente del Kit de desarrollo de agentes (ADK):

Registro de muestra de una búsqueda

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 los atributos pertinentes 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": [],
  }

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

Antes de comenzar

Antes de recopilar y escribir registros de seguimiento, debes habilitar APIs específicas e instalar dependencias. Para obtener más información, consulta Cómo recopilar y ver instrucciones y respuestas multimodales en la documentación de Google Cloud Observability.

Cómo escribir registros de seguimiento para un agente

Para escribir seguimientos de un agente, haz lo siguiente:

ADK

Para habilitar OpenTelemetry para AdkApp, configura las siguientes variables de entorno cuando implementes el agente en el entorno de ejecución del agente:

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:

LangchainAgent

Para habilitar el seguimiento para 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

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-2.0-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

Personalizado

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

Esta acción exporta seguimientos a Cloud Trace en el proyecto en Configura tu proyecto 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 registros de seguimiento de tu agente:

  1. En la consola de Google Cloud , ve a la página Implementaciones de la Plataforma de agentes.

    Ir a Implementaciones

    En la lista, aparecen las instancias de Agent Platform que forman parte del proyecto seleccionado. 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 los Precios de Cloud Trace.