Tracing einrichten

Mit Cloud Trace können Sie die Leistung Ihrer Agenten analysieren, indem Sie den Zeitablauf der Vorgänge für jede Anfrage nachvollziehen. Mithilfe von Traces können Sie Engpässe identifizieren und Interaktionen mit Large Language Models (LLMs) oder Tools nachvollziehen.

In diesem Dokument wird beschrieben, wie Sie Trace für Ihre Agents aktivieren und Traces in der Google Cloud Console ansehen und analysieren.

Ein Trace ist eine Zeitachse von Anfragen, während Ihr Agent auf jede Anfrage reagiert. Das folgende Diagramm zeigt beispielsweise einen Beispiel-Trace von einem Agent aus dem Agent Development Kit (ADK):

Beispiel-Trace für eine Abfrage

Ein Trace besteht aus einzelnen Spans, die eine einzelne Arbeitseinheit darstellen, z. B. einen Funktionsaufruf oder eine Interaktion mit einem LLM. Der erste Span stellt die Gesamtanfrage dar. Jeder Span enthält Details zu einem bestimmten Vorgang, z. B. den Namen des Vorgangs, Start- und Endzeiten sowie alle relevanten Attribute innerhalb der Anfrage. Das folgende JSON-Beispiel zeigt einen einzelnen Bereich, der einen Aufruf eines Large Language Model (LLM) darstellt:

  {
    "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": [],
  }

Weitere Informationen finden Sie in der Cloud Trace-Dokumentation unter Traces und Spans und Trace-Kontext.

Hinweis

Bevor Sie Traces erfassen und schreiben können, müssen Sie bestimmte APIs aktivieren und Abhängigkeiten installieren. Weitere Informationen finden Sie in der Google Cloud Observability-Dokumentation unter Multimodale Prompts und Antworten erfassen und ansehen.

Traces für einen Agent schreiben

So schreiben Sie Traces für einen Agent:

ADK

Wenn Sie OpenTelemetry für AdkApp aktivieren möchten, legen Sie beim Bereitstellen des Agents in der Agent-Laufzeit die folgenden Umgebungsvariablen fest:

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

Wichtige Hinweise:

  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY aktiviert die Agent-Traces und ‑Logs, enthält aber keine Prompt- und Antwortdaten.

  • OTEL_SEMCONV_STABILITY_OPT_IN ermöglicht die Verwendung der neuesten semantischen Konventionen für generative KI.

  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ermöglicht das Logging von Eingabe-Prompts und Ausgaberesponses.

  • Wenn Sie die Erfassung von Traces verwenden möchten, müssen Sie die Telemetry API aktivieren. Weitere Informationen finden Sie unter Telemetry (OTLP) API overview.

  • Wenn Sie die Logaufnahme verwenden möchten, müssen Sie die Logging API aktivieren. Weitere Informationen finden Sie unter Cloud Logging API.

LangchainAgent

Wenn Sie das Tracing für LangchainAgent aktivieren möchten, geben Sie enable_tracing=True an, wenn Sie einen LangChain-Agenten entwickeln. Beispiel:

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Wenn Sie das Tracing für LanggraphAgent aktivieren möchten, geben Sie enable_tracing=True an, wenn Sie einen LangGraph-Agent entwickeln. Beispiel:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Wenn Sie das Tracing für LlamaIndexQueryPipelineAgent aktivieren möchten, geben Sie enable_tracing=True an, wenn Sie einen LlamaIndex-Agent entwickeln. Beispiel:

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
  )

Benutzerdefiniert

Informationen zum Aktivieren von Tracing für benutzerdefinierte Agents finden Sie unter Tracing mit OpenTelemetry.

Dadurch werden Traces unter dem Projekt in Google Cloud -Projekt einrichten in Cloud Trace exportiert.

Traces für einen Agent ansehen

Bei bereitgestellten Agents können Sie in der Google Cloud Console Traces für Ihren Agenten ansehen:

  1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

    Zu Deployments

    Agent Platform-Instanzen, die Teil des ausgewählten Projekts sind, werden in der Liste angezeigt. Mit dem Feld Filter können Sie die Liste nach der angegebenen Spalte filtern.

  2. Klicken Sie auf den Namen Ihrer Agent Platform-Instanz.

  3. Klicken Sie auf den Tab Traces.

  4. Sie können Sitzungsansicht oder Spannenansicht auswählen.

    Klicken Sie auf eine Sitzung oder einen Span, um die Tracedetails zu prüfen, einschließlich eines gerichteten azyklischen Graphen (DAG) der zugehörigen Spans, Ein- und Ausgaben sowie Metadatenattribute.

Kontingente und Limits

Einige Attributwerte werden möglicherweise gekürzt, wenn das Kontingentlimit erreicht wird. Weitere Informationen finden Sie unter Cloud Trace-Kontingent.

Preise

Cloud Trace ist in einer kostenlosen Stufe verfügbar. Weitere Informationen finden Sie unter Cloud Trace-Preise.