Configurar rastreamento

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

Este documento explica como ativar o Trace para seus agentes e como visualizar e analisar traces no Google Cloud console.

Um trace é uma linha do tempo de solicitações à medida que 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 agentes (ADK, na sigla em inglês):

Exemplo de rastreamento de uma consulta

Um trace é composto de 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 o nome, os horários de início e término, e todos os atributos relevantes, dentro da 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": [],
  }

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

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 multimodais e respostas na documentação do Google Cloud Observability.

Gravar traces para um agente

Para gravar traces para um agente:

ADK

Para ativar o OpenTelemetry para AdkApp, defina as seguintes variáveis de ambiente ao implantar o agente no ambiente de execução do agente:

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 e registros do 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 o registro de comandos de entrada, respostas de saída e IDs de usuário (o campo user.id). A captura desses detalhes facilita a observabilidade do agente e a detecção de anomalias, rastreando o uso e as interações ao longo do tempo.

  • Para usar a ingestão de traces, é 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 Logging. Para mais informações, consulte Visão geral da API Cloud Logging.

LangchainAgent

Para ativar o rastreamento de LangchainAgent, especifique enable_tracing=True ao desenvolver um agente 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 LangGraph. Exemplo:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Para ativar o rastreamento de LlamaIndexQueryPipelineAgent, especifique enable_tracing=True ao desenvolver um agente 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-2.0-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

Personalizado

Para ativar o rastreamento de agentes personalizados, consulte Rastreamento usando o OpenTelemetry para mais detalhes.

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

Visualizar traces de um agente

Para agentes implantados, é possível usar o Google Cloud console do para visualizar traces do agente:

  1. No Google Cloud console, acesse a página Implantações do Agent Platform.

    Acessar "Implantações"

    As instâncias da Agent Platform que fazem parte do projeto selecionado aparecem na lista. É possível usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Clique no nome da instância do Agent Platform.

  3. Clique na guia Traces.

  4. É possível selecionar a visualização de sessão ou a visualização de 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.