Configurer le traçage

Cloud Trace vous permet d'analyser les performances de vos agents en traçant le calendrier des opérations pour chaque requête. Vous pouvez utiliser des traces pour identifier les goulots d'étranglement et comprendre les interactions avec les grands modèles de langage (LLM) ou les outils.

Ce document explique comment activer le traçage pour vos agents, et comment afficher et analyser les traces dans la console Google Cloud .

Une trace est une chronologie des requêtes à mesure que votre agent répond à chaque requête. Par exemple, le graphique suivant montre un exemple de trace provenant d'un agent Agent Development Kit (ADK) :

Exemple de trace pour une requête

Une trace est composée de spans individuels, qui représentent une unité de travail unique, comme un appel de fonction ou une interaction avec un LLM. Le premier span représente la requête globale. Chaque span fournit des informations sur une opération spécifique, comme son nom, ses heures de début et de fin, ainsi que tous les attributs pertinents de la requête. Par exemple, le JSON suivant montre une seule étendue qui représente un appel à un grand modèle de langage (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": [],
  }

Pour en savoir plus, consultez la documentation Cloud Trace sur les traces et les spans et sur le contexte de trace.

Avant de commencer

Avant de pouvoir collecter et écrire des traces, vous devez activer des API spécifiques et installer des dépendances. Pour en savoir plus, consultez Collecter et afficher les requêtes et réponses multimodales dans la documentation Google Cloud Observability.

Écrire des traces pour un agent

Pour écrire des traces pour un agent :

ADK

Pour activer OpenTelemetry pour AdkApp, définissez les variables d'environnement suivantes lorsque vous déployez l'agent sur 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",
}

Veuillez noter les points suivants :

  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY permet d'activer les traces et les journaux de l'agent, mais n'inclut pas les données de requêtes et de réponses.

  • OTEL_SEMCONV_STABILITY_OPT_IN permet d'utiliser les dernières conventions sémantiques de l'IA générative.

  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT permet de journaliser les prompts d'entrée et les réponses de sortie.

  • Pour utiliser l'ingestion de trace, vous devez activer l'API Telemetry. Pour en savoir plus, consultez Présentation de l'API Telemetry (OTLP).

  • Pour utiliser l'ingestion de journaux, vous devez activer l'API Logging. Pour en savoir plus, consultez la présentation de l'API Cloud Logging.

LangchainAgent

Pour activer le traçage de LangchainAgent, spécifiez enable_tracing=True lorsque vous développez un agent LangChain. Exemple :

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Pour activer le traçage de LanggraphAgent, spécifiez enable_tracing=True lorsque vous développez un agent LangGraph. Exemple :

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Pour activer le traçage pour LlamaIndexQueryPipelineAgent, spécifiez enable_tracing=True lorsque vous développez un agent LlamaIndex. Exemple :

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
  )

Personnalisé

Pour activer le traçage pour les agents personnalisés, consultez Traçage à l'aide d'OpenTelemetry pour en savoir plus.

Cela exportera des traces vers Cloud Trace sous le projet dans Configurer votre projet Google Cloud .

Afficher les traces d'un agent

Pour les agents déployés, vous pouvez utiliser la console Google Cloud pour afficher les traces de votre agent :

  1. Dans la console Google Cloud , accédez à la page Déploiements de la plate-forme d'agent.

    Accéder à la page "Déploiements"

    Les instances de la plate-forme d'agent faisant partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filtrer pour filtrer la liste en fonction de la colonne spécifiée.

  2. Cliquez sur le nom de votre instance Agent Platform.

  3. Cliquez sur l'onglet Traces.

  4. Vous pouvez sélectionner Vue Session ou Vue Span.

    Cliquez sur une session ou un segment pour inspecter les détails de la trace, y compris un graphe orienté acyclique (DAG) de ses segments, ses entrées et sorties, et ses attributs de métadonnées.

Quotas et limites

Certaines valeurs d'attributs peuvent être tronquées lorsqu'elles atteignent les limites de quota. Pour en savoir plus, consultez la page Quota Cloud Trace.

Tarifs

Cloud Trace propose une version sans frais. Pour en savoir plus, consultez la page Tarifs de Cloud Trace.