Agenten erfassen

Auf dieser Seite erfahren Sie, wie Sie Cloud Trace für Ihren Agent aktivieren und Traces ansehen, um Antwortzeiten von Anfragen und ausgeführte Vorgänge zu 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 Development Kit-Agenten (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 Endzeiten sowie alle relevanten Attributen 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 darauf verlassen, dass das Format stabil bleibt. 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.

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 Vertex AI Agent Engine-Laufzeit bereitstellen:

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

Wichtige Hinweise:

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

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT aktiviert 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.

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-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 sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

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 Agent ansehen:

1. Rufen Sie in der Google Cloud Console die Seite Vertex AI Agent Engine auf.
   

   Zu Agent Engine

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

2. Klicken Sie auf den Namen Ihrer Agent Engine-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.