Rastreie um agente

Esta página mostra 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 gráfico seguinte mostra um exemplo de rastreio de um agente do Agent Development Kit (ADK):

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 um pedido 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 o OpenTelemetry para o AdkApp, defina as seguintes variáveis de ambiente quando implementar o agente no tempo de execução do Vertex AI Agent Engine:

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

Tenha em conta o seguinte:

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY ativa os rastreios e os registos do agente, mas não inclui comandos nem dados de respostas.

• A diretiva OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ativa o registo de comandos de entrada e respostas de saída.

• Para usar o carregamento de rastreios, tem de ativar a API Telemetry. Para mais informações, consulte o artigo Vista geral da API Telemetry (OTLP)

• Para usar o carregamento de registos, tem de ativar a API Logging. Para mais informações, consulte a vista geral da API Cloud Logging.

Nota: se estava a definir anteriormente a flag enable_tracing, recomendamos que use 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 rastreio 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 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 Configure o seu Google Cloud projeto.

Veja rastreios de um agente

Para agentes implementados, pode usar a Google Cloud consola para ver rastreios do seu agente:

1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.
   

   Aceda ao motor do agente

   As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

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

3. Clique no separador Rastreios.

4. Pode selecionar Vista de sessão ou Vista de intervalo.

   Clique numa sessão ou num intervalo para inspecionar os detalhes do rastreio, incluindo um gráfico acíclico dirigido (DAG) dos respetivos intervalos, entradas e saídas, e atributos de metadados.

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.