Configurare la tracciatura

Cloud Trace ti consente di analizzare le prestazioni dei tuoi agenti tracciando la sequenza temporale delle operazioni per ogni query. Puoi utilizzare le tracce per identificare i colli di bottiglia e comprendere le interazioni con i modelli linguistici di grandi dimensioni (LLM) o gli strumenti.

Questo documento spiega come abilitare Trace per i tuoi agenti e come visualizzare e analizzare le tracce nella Google Cloud console.

Una traccia è una sequenza temporale delle richieste mentre l'agente risponde a ogni query. Ad esempio, il seguente grafico mostra una traccia di esempio di un agente dell'Agent Development Kit (ADK):

Esempio di traccia per una query

Una traccia è composta da singoli intervalli, che rappresentano una singola unità di lavoro, come una chiamata di funzione o un'interazione con un LLM, con il primo intervallo che rappresenta la richiesta complessiva. Ogni intervallo fornisce dettagli su un'operazione specifica, come il nome dell'operazione, gli orari di inizio e fine, e gli attributi pertinenti, all'interno della richiesta. Ad esempio, il seguente JSON mostra un singolo intervallo che rappresenta una chiamata a un modello linguistico di grandi dimensioni (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": [],
  }

Per maggiori dettagli, consulta la documentazione di Cloud Trace su Tracce e intervalli e Contesto della traccia.

Prima di iniziare

Prima di poter raccogliere e scrivere le tracce, devi abilitare API specifiche e installare le dipendenze. Per saperne di più, consulta Raccogliere e visualizzare prompt e risposte multimodali nella documentazione di Google Cloud Observability.

Scrivere tracce per un agente

Per scrivere le tracce per un agente:

ADK

Per abilitare OpenTelemetry per AdkApp, imposta le seguenti variabili di ambiente quando esegui il deployment dell' agente in Agent Runtime:

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

Tieni presente quanto segue:

  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY abilita le tracce e i log dell'agente, ma non include i dati di prompt e risposta.

  • OTEL_SEMCONV_STABILITY_OPT_IN consente di utilizzare le ultime convenzioni semantiche di AI generativa.

  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT abilita il logging dei prompt di input, delle risposte di output e degli ID utente (il campo user.id). L'acquisizione di questi dettagli facilita l'osservabilità dell'agente e il rilevamento delle anomalie monitorando l'utilizzo e le interazioni nel tempo.

  • Per utilizzare l'inserimento delle tracce, devi abilitare l'API Telemetry. Per saperne di più, consulta la panoramica dell'API Telemetry (OTLP).

  • Per utilizzare l'inserimento dei log, devi abilitare l'API Logging. Per saperne di più, consulta la panoramica dell'API Cloud Logging.

LangchainAgent

Per abilitare il tracciamento per LangchainAgent, specifica enable_tracing=True quando sviluppi un agente LangChain. Ad esempio:

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Per abilitare il tracciamento per LanggraphAgent, specifica enable_tracing=True quando sviluppi un agente LangGraph. Ad esempio:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Per abilitare il tracciamento per LlamaIndexQueryPipelineAgent, specifica enable_tracing=True quando sviluppi un agente LlamaIndex. Ad esempio:

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
  )

Personalizzato

Per abilitare il tracciamento per gli agenti personalizzati, consulta Tracciamento utilizzando OpenTelemetry per i dettagli.

In questo modo le tracce vengono esportate in Cloud Trace nel progetto in Configurare il progetto. Google Cloud

Visualizzare le tracce per un agente

Per gli agenti di cui è stato eseguito il deployment, puoi utilizzare la Google Cloud console per visualizzare le tracce del tuo agente:

  1. Nella Google Cloud console, vai alla pagina Deployment di Agent Platform.

    Vai a Deployment

    Le istanze di Agent Platform che fanno parte del progetto selezionato vengono visualizzate nell'elenco. Puoi utilizzare il campo Filtro per filtrare l'elenco in base alla colonna specificata.

  2. Fai clic sul nome dell'istanza di Agent Platform.

  3. Fai clic sulla scheda Tracce.

  4. Puoi selezionare Visualizzazione sessione o Visualizzazione intervallo.

    Fai clic su una sessione o un intervallo per ispezionare i dettagli della traccia, inclusi un grafo diretto aciclico (DAG) dei relativi intervalli, input e output e attributi dei metadati.

Quote e limiti

Alcuni valori degli attributi potrebbero essere troncati quando raggiungono i limiti di quota. Per saperne di più, consulta Quota di Cloud Trace.

Prezzi

Cloud Trace ha un livello senza costi. Per saperne di più, consulta Prezzi di Cloud Trace.