Tracing einrichten

Mit Cloud Trace können Sie die Leistung Ihrer KI-Agenten analysieren, indem Sie die Zeitachse der Vorgänge für jede Abfrage verfolgen. Mit 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 Agenten aktivieren und Traces in der Google Cloud Console aufrufen und analysieren.

Ein Trace ist eine Zeitleiste der Anfragen, während Ihr KI-Agent auf die einzelnen Abfragen antwortet. Das folgende Diagramm zeigt beispielsweise einen Beispiel-Trace von einem Agenten des Agent Development Kit (ADK):

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, die Start- und Endzeit sowie alle relevanten Attribute innerhalb der Anfrage. Das folgende JSON-Beispiel zeigt einen einzelnen Span, 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": [],
  }

Hinweis: Das Format der Traces und Spans hängt von der gewählten Instrumentierungsoption ab. Der Beispiel-Span ist experimentell und kann sich ändern. Sie sollten sich also vorerst nicht darauf verlassen, dass das Format stabil ist. Weitere Informationen finden Sie in den semantischen Konventionen für generative KI-Systeme, die in OpenTelemetry entwickelt werden.

Weitere Informationen finden Sie in der Cloud Trace-Dokumentation zu 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 KI-Agenten schreiben

So schreiben Sie Traces für einen KI-Agenten:

ADK

Wenn Sie OpenTelemetry für AdkApp aktivieren möchten, legen Sie die folgenden Umgebungsvariablen fest, wenn Sie den Agenten in Agent Runtime bereitstellen:

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 Traces, Logs und Messwerte des KI-Agenten (siehe Messwerte für einen KI-Agenten ansehen), enthält aber keine Prompts 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 aktiviert das Logging von Eingabe-Prompts, Ausgabeantworten und Nutzer-IDs (Feld user.id). Durch das Erfassen dieser Details werden die Beobachtbarkeit von KI-Agenten und die Anomalieerkennung erleichtert, da Nutzung und Interaktionen im Zeitverlauf verfolgt werden können.

  Hinweis: Achten Sie darauf, dass Sie die erforderlichen Endnutzereinwilligungen, Hinweise für Endnutzer und Datenverarbeitungsrichtlinien für die Erhebung dieser Informationen haben.
  Wichtig: Das Logging von user.id ist enthalten, wenn Sie die Option „Logging von Prompt-Eingaben und Antwortausgaben aktivieren“ auswählen. Dies gilt ab dem 22. Mai 2026 mit der Agent Development Kit-Version 2.1. Wenn Sie sich vor dem 22. Mai angemeldet haben, enthält Ihr Logging nicht user.id. Sie müssen Ihre Agents noch einmal bereitstellen und die Einstellung noch einmal aktivieren, damit sie wirksam wird.

• Wenn Sie die Trace-Aufnahme verwenden möchten, müssen Sie die Telemetry API aktivieren. Weitere Informationen finden Sie unter Telemetry (OTLP) API – Übersicht.

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

Hinweis: Wenn Sie zuvor das Flag enable_tracing festgelegt haben, empfehlen wir, stattdessen die Umgebungsvariablen zu verwenden. Legen Sie beispielsweise GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true anstelle von enable_tracing=true und GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false anstelle von enable_tracing=false fest.

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-Agenten entwickeln. Beispiel:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Wenn Sie das Tracing für LlamaIndexQueryPipelineAgent aktivieren möchten, geben Sie enable_tracing=True an, wenn Sie einen LlamaIndex-Agenten 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-3.5-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

Benutzerdefiniert

Informationen zum Aktivieren des Tracing für benutzerdefinierte KI-Agenten 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 KI-Agenten ansehen

Für bereitgestellte Agenten können Sie die Google Cloud Console verwenden, um Traces für Ihren Agenten anzusehen:

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 Span-Ansicht 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.