Rastrear un agente

En esta página se explica cómo habilitar Cloud Trace en tu agente y ver las trazas para analizar los tiempos de respuesta de las consultas y las operaciones ejecutadas.

Una traza es una cronología de las solicitudes a medida que tu agente responde a cada consulta. Por ejemplo, el siguiente gráfico muestra una traza de muestra de un agente de Agent Development Kit (ADK):

Un rastreo se compone de spans individuales, que representan una sola unidad de trabajo, como una llamada a una función o una interacción con un LLM. El primer span representa la solicitud general. Cada intervalo proporciona detalles sobre una operación específica, como el nombre de la operación, las horas de inicio y finalización, y los atributos relevantes de la solicitud. Por ejemplo, el siguiente JSON muestra un único intervalo que representa una llamada a un modelo de lenguaje extenso (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 rastreos y los spans 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 ahora, no deberías confiar en que el formato sea estable. Para obtener más información, consulta las convenciones semánticas para sistemas de IA generativa que se están desarrollando en OpenTelemetry.

Para obtener más información, consulta la documentación de Cloud Trace sobre trazas e intervalos y contexto de traza.

Escribir trazas de un agente

Para escribir trazas de un agente, haz lo siguiente:

ADK

Para habilitar OpenTelemetry en AdkApp, define las siguientes variables de entorno cuando despliegues el agente en el tiempo de ejecución de Vertex AI Agent Engine:

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
}

Ten en cuenta lo siguiente:

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY habilita los registros y los seguimientos del agente, pero no incluye las peticiones ni los datos de respuesta.

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT permite registrar las peticiones de entrada y las respuestas de salida.

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

• Para usar la ingesta de registros, debes habilitar la API Logging. Para obtener más información, consulta el resumen de la API Cloud Logging.

Nota: Si antes definías la marca enable_tracing, te recomendamos que uses las variables de entorno. Por ejemplo, define GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true en lugar de enable_tracing=true, y define GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false en lugar de enable_tracing=false.

LangchainAgent

Para habilitar el rastreo 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 rastreo 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 los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Para habilitar el rastreo 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 seguimiento de agentes personalizados, consulta los detalles en Seguimiento con OpenTelemetry.

De esta forma, se exportan las trazas a Cloud Trace en el proyecto que se describe en Configurar el proyecto Google Cloud .

Ver las trazas de un agente

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

1. En la Google Cloud consola, ve a la página Vertex AI Agent Engine.
   

   Ir a Agent Engine

   Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puede usar el campo Filtrar para filtrar la lista por la columna que haya especificado.

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

3. Haz clic en la pestaña Traces (Trazas).

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

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

Cuotas y límites

Es posible que algunos valores de atributos se trunquen cuando alcancen los límites de cuota. Para obtener más información, consulta la página Cuota de Cloud Trace.

Precios

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