Tracer un agent

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page explique comment activer Cloud Trace sur votre agent et afficher les traces pour analyser les temps de réponse aux requêtes et les opérations exécutées.

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

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

Remarque : Le format des traces et des segments dépend de l'option d'instrumentation que vous choisissez. L'exemple de segment est expérimental et peut être modifié. Vous ne devez donc pas vous fier à la stabilité du format pour le moment. Pour en savoir plus, consultez les conventions sémantiques pour les systèmes d'IA générative en cours de développement dans OpenTelemetry.

Pour en savoir plus, consultez la documentation Cloud Trace sur les traces et les segments, ainsi que 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 des invites et des 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 dans l' environnement d'exécution Vertex AI Agent Engine :

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

Veuillez noter les points suivants :

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY active les traces et les journaux de l'agent, mais n'inclut pas les invites ni les données de réponse.

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT active la journalisation des invites d'entrée et des réponses de sortie.

• Pour utiliser l'ingestion de traces, vous devez activer l'API Telemetry. Pour en savoir plus, consultez la 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.

Remarque : Si vous définissiez auparavant l'indicateur enable_tracing, nous vous recommandons d'utiliser les variables d'environnement à la place. Par exemple, définissez GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true au lieu de enable_tracing=true, et GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false au lieu de enable_tracing=false.

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

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour activer le traçage de 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 des agents personnalisés, consultez la page Traçage à l'aide d'OpenTelemetry pour en savoir plus.

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

Afficher les traces d'un agent

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

1. Dans la Google Cloud console, accédez à la page Vertex AI Agent Engine.
   

   Accéder à Agent Engine

   Les instances Agent Engine qui font partie du projet sélectionné apparaissent dans la liste. Vous pouvez utiliser le champ Filter (Filtrer) pour filtrer la liste par colonne spécifiée.

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

3. Cliquez sur l'onglet Traces.

4. Vous pouvez sélectionner Session view (Vue de la session) ou Span view (Vue du segment).

   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 section Quota Cloud Trace.

Tarifs

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