Ver traces do agente

Antes de começar

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

  • Ativar APIs: verifique se as seguintes APIs estão ativadas para seu projetoGoogle Cloud :
    • API Cloud Trace
    • API Cloud Logging
    • API Telemetry
  • Configure o rastreamento de agentes: o agente precisa ser configurado para enviar dados de rastreamento para Google Cloud. Para instruções sobre como ativar o rastreamento para diferentes tipos de agentes, consulte Configurar o rastreamento.
  • Configurar permissões: para ver traces e registros, você precisa de papéis do IAM que forneçam as permissões necessárias, como os papéis de 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 rastreamento 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 usam loops de raciocínio não determinísticos 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 rastreamentos 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 analisar traces

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

  1. No console Google Cloud , navegue até a página Agent Platform > Registro de agentes.

    Acessar o Agent Registry

  2. Selecione seu agente específico.

  3. Clique na guia Traces.

Com essa interface, é possível inspecionar os detalhes de execução do seu agente etapa por etapa. Um rastreamento é um registro factual e imutável do comportamento do agente, incluindo entradas, respostas e chamadas de ferramentas do modelo. A visualização de rastreamento 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 analisar seus dados de telemetria:

  • Visualização de sessão:agrupa as execuções por sessões de usuários individuais, permitindo analisar conversas multiturno e o comportamento do agente ao longo do tempo.
  • Visualização de rastreamento:concentra-se em rastreamentos de solicitações 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 específica de modelo de fundação, uma solicitação de API ou a execução de uma ferramenta externa.

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

Ao selecionar uma sessão específica na Visualização de sessão, um Painel de detalhes é aberto com um painel de lista no lado esquerdo mostrando todos os traces individuais contidos nessa sessão multiturno. O painel principal agrega todo o contexto da sessão, mostrando a entrada formatada e as mensagens do assistente, além de métricas gerais da sessão, como duração, total de tokens de IA generativa e pontuações de avaliação contínua.

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

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 nessa 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 específicos dessa operação.

Armazenamento de dados e controle de acesso

Para manter a segurança e a conformidade, a Gemini Enterprise Agent Platform separa os metadados operacionais do conteúdo da conversa:

  • Métricas e atributos de execução:a telemetria padrão (como latência, códigos de status e metadados estruturais) é armazenada diretamente nos intervalos de rastreamento.
  • Comandos e respostas:dados potencialmente sensíveis, como comandos do usuário e respostas do modelo, não são armazenados nos intervalos. Em vez disso, eles são encaminhados para o Cloud Storage (recomendado) ou o Cloud Logging, dependendo da configuração da sua organização. O Cloud Storage é recomendado porque oferece suporte a payloads grandes e multimodais sem truncamento e fornece gerenciamento de ciclo de vida refinado. O Cloud Logging é compatível com payloads de texto básicos, mas tem limites de tamanho. Essa separação permite que os administradores implementem controles granulares do Identity and Access Management (IAM) sobre dados sensíveis de conversas.

A interface da Gemini Enterprise Agent Platform entende automaticamente a correlação entre seus intervalos de rastreamento e esses registros de solicitação e resposta armazenados com segurança. Quando você abre uma visualização detalhada de um trace, a plataforma junta esses dados de novo, apresentando uma visualização unificada do comportamento do agente sem comprometer suas regras de governança de dados.

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

A seguir