Configurare la tracciatura

Cloud Trace ti consente di analizzare le prestazioni degli agenti tracciando la cronologia 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 attivare Trace per gli agenti e come visualizzare e analizzare le tracce nella console Google Cloud .

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

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, l'ora di inizio e di fine dell'operazione e tutti 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": [],
  }

Nota: il formato delle tracce e degli intervalli dipende dall'opzione di strumentazione scelta. Lo span di esempio è sperimentale e soggetto a modifiche, pertanto non devi fare affidamento sulla stabilità del formato per il momento. Per maggiori dettagli, consulta le convenzioni semantiche per i sistemi di AI generativa in fase di sviluppo in OpenTelemetry.

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 tracce, devi abilitare API specifiche e installare le dipendenze. Per ulteriori informazioni, consulta Raccogli e visualizza prompt e risposte multimodali nella documentazione di Google Cloud Observability.

Scrivi tracce per un agente

Per scrivere 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, i log e le metriche dell'agente (consulta Visualizza le metriche per un agente), ma non include i dati dei prompt e delle risposte.

• OTEL_SEMCONV_STABILITY_OPT_IN consente l'utilizzo delle convenzioni semantiche dell'AI generativa più recenti.

• 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 di anomalie monitorando l'utilizzo e le interazioni nel tempo.

  Nota: assicurati di aver implementato le norme sulla gestione dei dati e di aver ottenuto le notifiche e i consensi degli utenti finali necessari per la raccolta di queste informazioni.
  Importante: il logging di user.id è incluso quando attivi l'opzione "Abilita il logging degli input dei prompt e degli output delle risposte" a partire dal 22 maggio 2026, con Agent Development Kit versione 2.1. Se hai eseguito l'attivazione prima del 22 maggio, il logging non include user.id. Per applicare questa impostazione, dovrai rifare il deployment degli agenti e attivare nuovamente l'opzione.

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

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

Nota: se in precedenza hai impostato il flag enable_tracing, ti consigliamo di utilizzare le variabili di ambiente. Ad esempio, imposta GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true anziché enable_tracing=true e imposta GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false anziché enable_tracing=false.

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

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

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-3.5-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 con OpenTelemetry per i dettagli.

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

Visualizza le tracce di un agente

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

1. Nella console Google Cloud , vai alla pagina Deployment della piattaforma agente.
   

   Vai a Deployment

   Nell'elenco vengono visualizzate le istanze di Agent Platform che fanno parte del progetto selezionato. Puoi utilizzare il campo Filtra 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 offre un livello senza costi. Per saperne di più, consulta i prezzi di Cloud Trace.