Tracing einrichten

Mit Cloud Trace können Sie die Leistung Ihrer Agenten analysieren, indem Sie den Zeitablauf der Vorgänge für jede Anfrage nachverfolgen. 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 ein Zeitablauf von Anfragen, während Ihr Agent auf jede Anfrage reagiert. Das folgende Diagramm zeigt beispielsweise einen Beispiel-Trace von einem Agent Development Kit-Agenten (ADK):

Ein Trace besteht aus einzelnen Spans, die eine einzelne Arbeitseinheit wie einen Funktionsaufruf oder eine Interaktion mit einem LLM darstellen. Der erste Span repräsentiert die Gesamtanfrage. 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": [],
  }

Hinweis :Das Format der Traces und Spans hängt von der gewählten Instrumentierungsoption ab. Der Beispielzeitraum ist experimentell und kann sich ändern. Sie sollten sich daher vorerst nicht auf das Format verlassen. 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 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 die folgenden Umgebungsvariablen fest, wenn Sie den Agent in der Agent-Laufzeitumgebung 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 ermöglicht die Agent-Traces, ‑Logs und ‑Messwerte (siehe Messwerte für einen Agent ansehen), 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, Ausgabereaktionen und Nutzer-IDs (das Feld user.id). Wenn Sie diese Details erfassen, wird die Beobachtbarkeit von Agenten und die Anomalieerkennung erleichtert, da die Nutzung und Interaktionen im Zeitverlauf nachverfolgt werden.

  Hinweis:Achten Sie darauf, dass die erforderlichen Endnutzereinwilligungen, Hinweise für Endnutzer und Datenverarbeitungsrichtlinien für die Erhebung dieser Informationen vorhanden sind.
  Wichtig:Die Protokollierung von user.id ist enthalten, wenn Sie ab dem 22. Mai 2026 mit Agent Development Kit Version 2.1 die Option „Protokollierung von Prompt-Eingaben und Antwortausgaben aktivieren“ auswählen. Wenn Sie die Funktion vor dem 22. Mai aktiviert haben, werden user.id nicht aufgezeichnet. Sie müssen Ihre Agents neu bereitstellen und die Einstellung noch einmal aktivieren, damit sie wirksam wird.

• Wenn Sie die Erfassung von Traces verwenden möchten, müssen Sie die Telemetry API aktivieren. Weitere Informationen finden Sie in der Übersicht zur Telemetry API (OTLP).

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

Hinweis :Wenn Sie das Flag enable_tracing zuvor 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-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

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-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 Agenten können Sie sich 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 Zeitraumansicht 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.