Configurar rastreamento

Com o Cloud Trace, é possível analisar o desempenho dos seus agentes rastreando a linha do tempo das operações de cada consulta. É possível usar traces para identificar gargalos e entender interações com modelos de linguagem grandes (LLMs) ou ferramentas.

Neste documento, explicamos como ativar o Trace para seus agentes e como visualizar e analisar traces no console do Google Cloud .

Um trace é uma linha do tempo de solicitações conforme o agente responde a cada consulta. Por exemplo, o gráfico a seguir mostra um trace de amostra de um agente do Kit de Desenvolvimento de Agente (ADK):

Um trace é composto por períodos individuais, que representam uma única unidade de trabalho, como uma chamada de função ou uma interação com um LLM, com o primeiro período representando a solicitação geral. Cada período fornece detalhes sobre uma operação específica, como nome, horários de início e término e todos os atributos relevantes na solicitação. Por exemplo, o JSON a seguir mostra um único período que representa uma chamada para um modelo de linguagem grande (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": [],
  }

Observação : o formato dos traces e períodos depende da opção de instrumentação escolhida. O período de exemplo é experimental e está sujeito a mudanças. Portanto, não confie na estabilidade do formato por enquanto. Para mais detalhes, consulte as Convenções semânticas para sistemas de IA generativa em desenvolvimento no OpenTelemetry.

Para mais detalhes, consulte a documentação do Cloud Trace sobre Traces e períodos e Contexto de traces.

Antes de começar

Antes de coletar e gravar traces, é necessário ativar APIs específicas e instalar dependências. Para mais informações, consulte Coletar e visualizar comandos e respostas multimodais na documentação do Google Cloud Observability.

Escrever traces para um agente

Para gravar traces de um agente:

ADK

Para ativar o OpenTelemetry para AdkApp, defina as seguintes variáveis de ambiente ao implantar o agente no 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",
}

Observe o seguinte:

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY ativa os traces, registros e métricas do agente (consulte Ver métricas de um agente), mas não inclui comandos e dados de resposta.

• OTEL_SEMCONV_STABILITY_OPT_IN permite o uso das convenções semânticas de IA generativa mais recentes.

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ativa a geração de registros de comandos de entrada, respostas de saída e IDs do usuário (o campo user.id). A captura desses detalhes facilita a observabilidade do agente e a detecção de anomalias ao rastrear o uso e as interações ao longo do tempo.

  Observação: verifique se você tem os consentimentos do usuário, avisos de consentimento e políticas de tratamento de dados necessários dos usuários finais para coletar essas informações.
  Importante: a geração de registros de user.id será incluída ao ativar a opção "Ativar a geração de registros de entradas de comandos e saídas de respostas" a partir de 22 de maio de 2026, com o Kit de Desenvolvimento de Agente versão 2.1. Se você tiver ativado o recurso antes de 22 de maio, sua geração de registros não incluirá user.id. Será necessário reimplantar os agentes e ativar novamente para que essa configuração entre em vigor.

• Para usar a ingestão de trace, é necessário ativar a API Telemetry. Para mais informações, consulte Visão geral da API Telemetry (OTLP).

• Para usar a ingestão de registros, é necessário ativar a API Cloud Logging. Para mais informações, consulte Visão geral da API Cloud Logging.

Observação: se você já definiu a flag enable_tracing, recomendamos usar as variáveis de ambiente. Por exemplo, defina GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true em vez de enable_tracing=true e defina GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false em vez de enable_tracing=false.

LangchainAgent

Para ativar o rastreamento de LangchainAgent, especifique enable_tracing=True ao desenvolver um agente do LangChain. Exemplo:

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Para ativar o rastreamento de LanggraphAgent, especifique enable_tracing=True ao desenvolver um agente do LangGraph. Exemplo:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para ativar o rastreamento de LlamaIndexQueryPipelineAgent, especifique enable_tracing=True ao desenvolver um agente do LlamaIndex. Exemplo:

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
  )

Personalizado

Para ativar o trace para agentes personalizados, acesse Trace usando o OpenTelemetry para mais detalhes.

Isso exporta traces para o Cloud Trace no projeto em Configurar seu projeto do Google Cloud .

Ver traces de um agente

Para agentes implantados, use o console do Google Cloud para conferir os traces do seu agente:

1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.
   

   Acessar "Implantações"

   As instâncias da Agent Platform que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

2. Clique no nome da instância da Plataforma de Agentes.

3. Clique na guia Traces.

4. Selecione Visualização da sessão ou Visualização do período.

   Clique em uma sessão ou período para inspecionar os detalhes do trace, incluindo um gráfico acíclico dirigido (DAG) dos períodos, entradas e saídas e atributos de metadados.

Cotas e limites

Alguns valores de atributo podem ser truncados quando atingem os limites de cota. Para mais informações, consulte Cota do Cloud Trace.

Preços

O Cloud Trace tem um nível sem custo financeiro. Para mais informações, consulte Preços do Cloud Trace.