Rastreie um agente

Esta página mostra-lhe como ativar o Cloud Trace no seu agente e ver rastreios para analisar os tempos de resposta das consultas e as operações executadas.

Um rastreio é uma cronologia de pedidos à medida que o agente responde a cada consulta. Por exemplo, o seguinte gráfico de Gantt mostra um exemplo de rastreio de um LangchainAgent:

 

A primeira linha no gráfico de Gantt destina-se ao rastreio. Um rastreio é composto por extensões individuais, que representam uma única unidade de trabalho, como uma chamada de função ou uma interação com um MDG, com a primeira extensão a representar o pedido geral. Cada intervalo fornece detalhes sobre uma operação específica, como o nome da operação, as horas de início e fim, e quaisquer atributos relevantes, no pedido. Por exemplo, o JSON seguinte mostra um único intervalo que representa uma chamada a um modelo de linguagem (conteúdo extenso) (MDL/CE):

  {
    "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": [],
  }

Nota: o formato dos rastreios e dos intervalos depende da opção de instrumentação que escolher. O intervalo de exemplo é experimental e está sujeito a alterações, pelo que não deve confiar que o formato seja estável por agora. Para ver detalhes, consulte as Convenções semânticas para sistemas de IA generativa que estão a ser desenvolvidas no OpenTelemetry.

Para ver detalhes, consulte a documentação do Cloud Trace sobre Rastreios e intervalos e Contexto de rastreio.

Escreva rastreios para um agente

Para escrever rastreios para um agente:

ADK

Para ativar a monitorização para AdkApp, especifique enable_tracing=True quando desenvolver um agente do Agent Development Kit. Por exemplo:

  from vertexai.agent_engines import AdkApp
  from google.adk.agents import Agent

  agent = Agent(
      model=model,
      name=agent_name,
      tools=[get_exchange_rate],
  )

  app = AdkApp(
      agent=agent,          # Required.
      enable_tracing=True,  # Optional.
  )

LangchainAgent

Para ativar a monitorização para LangchainAgent, especifique enable_tracing=True quando desenvolver um agente LangChain. Por 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 a rastreabilidade para LanggraphAgent, especifique enable_tracing=True quando desenvolver um agente LangGraph. Por exemplo:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Para ativar a monitorização para LlamaIndexQueryPipelineAgent, especifique enable_tracing=True quando desenvolver um agente do LlamaIndex. Por 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 a monitorização para agentes personalizados, visite o artigo Monitorização com o OpenTelemetry para ver detalhes.

Isto exporta rastreios para o Cloud Trace no projeto em Configurar o seu Google Cloud projeto.

Veja rastreios de um agente

Pode ver os seus rastreios através do Explorador de rastreios:

1. Para receber as autorizações para ver dados de rastreio na Google Cloud consola ou selecionar um âmbito de rastreio, peça ao seu administrador para lhe conceder a função IAMUtilizador do Cloud Trace(roles/cloudtrace.user) no seu projeto.

2. Aceda ao Trace Explorer na Google Cloud consola:

   Aceda ao explorador de rastreios

3. Selecione o seu Google Cloud projeto (correspondente a PROJECT_ID) na parte superior da página.

Para saber mais, consulte a documentação do Cloud Trace.

Quotas e limites

Alguns valores de atributos podem ser truncados quando atingem os limites de quota. Para mais informações, consulte a quota do Cloud Trace.

Preços

O Cloud Trace tem um nível gratuito. Para mais informações, consulte os preços do Cloud Trace.