Configurar rastreamento

Com o Cloud Trace, é possível analisar a performance dos seus agentes rastreando a linha do tempo de operações de cada consulta. É possível usar rastreamentos para identificar gargalos e entender 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 console do Google Cloud .

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 Agente (ADK, na sigla em inglês):

Exemplo de rastreamento de uma consulta

Um rastreamento é 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. O primeiro período representa 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 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 rastreamentos, você precisa 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.

Gravar rastreamentos 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 tempo 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 rastreamentos 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 mais recentes de IA generativa.

  • O OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT permite a geração de registros de comandos de entrada e respostas de saída.

  • Para usar a ingestão de rastreamentos, ative 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 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

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-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, acesse Rastreamento usando o OpenTelemetry para mais detalhes.

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

Ver traces de um agente

Para agentes implantados, use o console Google Cloud para ver rastreamentos do seu agente:

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

    Acessar "Implantações"

    As instâncias da plataforma do agente 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 sua instância da plataforma de agentes.

  3. Clique na guia Traces.

  4. Você pode selecionar Visualização de sessão ou Visualização de intervalo.

    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.