Ver rastreamentos do agente

Antes de começar

Antes de visualizar os traces do agente, é preciso atender aos seguintes requisitos:

  • Ativar APIs: verifique se as seguintes APIs estão ativadas para seu Google Cloud projeto:
    • API Cloud Trace
    • API Cloud Logging
    • API Telemetry
  • Configurar o trace do agente: o agente precisa ser configurado para enviar dados de trace para Google Cloud. Para instruções sobre como ativar o trace para diferentes tipos de agentes, consulte Configurar o trace.
  • Configurar permissões: para visualizar traces e registros, você precisa de papéis do IAM que forneçam as permissões necessárias, como os papéis Usuário do Cloud Trace (roles/cloudtrace.user) e Leitor de registros (roles/logging.viewer). Para mais informações, consulte Controle de acesso do Cloud Trace e Controle de acesso do Cloud Logging.

O trace distribuído é uma técnica de diagnóstico que acompanha a progressão de uma única solicitação à medida que ela passa por vários serviços e componentes distribuídos na sua arquitetura. Como os agentes de IA generativa empregam loops de raciocínio não deterministas para escolher ferramentas e caminhos de execução de forma dinâmica, as métricas convencionais de ponto no tempo geralmente são insuficientes para depuração. Os traces são essenciais para a observabilidade do agente porque fornecem uma linha do tempo completa e sequencial dessas interações imprevisíveis, permitindo que você veja exatamente por que um agente tomou uma decisão específica.

Como explorar traces

Para acessar dados de execução detalhados de um agente:

  1. No Google Cloud console, acesse a página Plataforma de agentes > Registro de agentes.

    Acessar o registro de agentes

  2. Selecione seu agente específico.

  3. Clique na guia Traces.

Essa interface permite inspecionar os detalhes de execução detalhados do agente. Um trace é um registro factual e imutável do comportamento do agente, incluindo entradas de modelo, respostas e chamadas de ferramentas. A visualização de trace inclui um gráfico acíclico dirigido (DAG) dos períodos, entradas e saídas e atributos de metadados.

A guia "Traces" oferece três visualizações distintas para explorar seus dados de telemetria:

  • Visualização da sessão:agrupa execuções por sessões de usuários individuais, permitindo analisar conversas de várias rodadas e o comportamento do agente ao longo do tempo.
  • Visualização de trace:concentra-se em traces de solicitação individuais de ponta a ponta, representando um único caminho de execução.
  • Visualização de período:fornece uma lista granular de operações individuais (períodos) executadas nos seus traces, como uma chamada de modelo de fundação específica, uma solicitação de API ou uma execução de ferramenta externa.

Visualização de trace único (contexto da sessão)

Quando você seleciona uma sessão específica na Visualização da sessão, um painel de detalhes é aberto com um painel de lista no lado esquerdo mostrando todos os traces individuais contidos nessa sessão de várias rodadas. O painel principal agrega o contexto de toda a sessão, mostrando a entrada formatada e as mensagens do assistente, além de métricas gerais da sessão, como duração, tokens totais de IA generativa e pontuações de avaliação contínua.

Visualização de trace único (trace direto ou contexto de período)

Como alternativa, se você selecionar um trace específico na Visualização de trace ou um período distinto na Visualização de período, o painel de detalhes será aberto diretamente para essa execução específica. Como você está visualizando uma única operação em vez de uma sessão agrupada, o painel de lista à esquerda fica oculto, permitindo uma inspeção imediata e focada da latência, dos atributos e dos possíveis erros dessa operação.

Armazenamento de dados e controle de acesso

Para manter a segurança e a conformidade, a plataforma de agentes do Gemini Enterprise separa os metadados operacionais do conteúdo conversacional real:

  • Métricas e atributos de execução:a telemetria padrão (como latência, códigos de status e metadados estruturais) é armazenada diretamente nos períodos de trace.
  • Solicitações e respostas:dados potencialmente sensíveis, como solicitações do usuário e respostas do modelo, não são armazenados nos períodos. Em vez disso, eles são encaminhados para o Cloud Logging ou o Cloud Storage, dependendo da configuração da sua organização. Isso permite que os administradores implementem controles granulares do Identity and Access Management (IAM) sobre dados conversacionais sensíveis.

A interface da plataforma de agentes do Gemini Enterprise entende automaticamente a correlação subjacente entre os períodos de trace e esses registros de solicitação e resposta armazenados com segurança. Quando você abre uma visualização de detalhes do trace, a plataforma junta esses dados de maneira integrada, apresentando uma visualização unificada do comportamento do agente sem comprometer as regras de governança de dados.

Para mais informações sobre como configurar destinos de armazenamento para dados conversacionais, consulte Coletar e visualizar solicitações e respostas multimodais.

A seguir