Executar avaliações off-line

Prévia: avaliação de agentes na Gemini Enterprise Agent Platform

Esse recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço e aos Termos específicos de serviço de IA generativa. Esse recurso permite que os clientes avaliem os agentes de IA. Por isso, os Termos específicos de serviço "Serviços de IA agêntica" se aplicam. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Com a avaliação off-line, é possível medir a performance, a segurança e a qualidade dos seus agentes analisando dados históricos capturados durante o desenvolvimento ou a produção. É possível avaliar rastreamentos individuais (caminhos de execução única) ou sessões completas (históricos de conversas com várias interações) em relação a um conjunto de métricas predefinidas ou personalizadas.

Traces x sessões

• Rastreamento:um registro imutável e factual do comportamento do agente, incluindo entradas, respostas e chamadas de ferramentas do modelo. Um rastreamento representa um único caminho de execução.
• Sessão:abrange toda a interação multiturno entre um usuário e um agente. Use sessões para avaliar a retenção de contexto e o fluxo de conversa ao longo do tempo.

Antes de começar

Para garantir que você tenha os dados e o ambiente necessários para a avaliação off-line, faça o seguinte:

• Verifique se você tem um Agent Runtime funcional implantado com o Cloud Trace ativado.
• Configure um bucket do Cloud Storage para armazenar os resultados da avaliação. Você só precisa informar esse caminho uma vez. Ele será preenchido automaticamente em execuções futuras.
• Se você planeja usar o SDK da Agent Platform para avaliação, inicialize o cliente conforme descrito em Avaliar seus agentes.

Requisitos de telemetria

A avaliação off-line exige que seu agente exporte indicadores específicos do OpenTelemetry para fornecer o contexto necessário para a avaliação. Esses requisitos são idênticos aos dos monitores on-line:

1. Período de invocação do agente: precisa incluir os seguintes atributos:

   • gen_ai.agent.name: o identificador do agente.
   • gen_ai.agent.description: uma breve descrição da finalidade do agente.
   • gen_ai.conversation.id: um identificador exclusivo da sessão de conversa específica.

2. Eventos de inferência: o evento gen_ai.client.inference.operation.details precisa capturar:

   • gen_ai.input.messages: os comandos enviados ao agente.
   • gen_ai.output.messages: as respostas geradas pelo agente.
   • gen_ai.system_instructions: os comandos do sistema subjacente.
   • gen_ai.tool.definitions: metadados sobre as ferramentas disponíveis para o agente.

Se você estiver usando o Kit de Desenvolvimento de Agente, ative esses recursos de telemetria definindo as seguintes variáveis de ambiente:

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Gravação de mídia no Cloud Storage

Se o agente usar dados multimodais, como imagens ou documentos grandes, recomendamos gravar as entradas e saídas em um bucket do Cloud Storage em vez de incorporá-las diretamente em intervalos de rastreamento. Configure as seguintes variáveis de ambiente para ativar isso:

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

Para mais informações, consulte Coletar comandos e respostas multimodais.

Criar uma avaliação com base no registro

1. No console do Google Cloud , navegue até a página Agent Platform > Agentes > Avaliação.

   Acessar "Avaliação"

2. Clique em Nova avaliação.

3. Selecione a guia Rastreamentos ou Sessões com base na sua meta de avaliação.

4. Use o ícone de filtro e o seletor de período para filtrar dados (por exemplo, por Versão ou "Últimas duas semanas") e selecione os IDs específicos que você quer avaliar.

5. Clique em Continuar.

6. (Opcional) No campo Nome da avaliação, insira um nome para a avaliação ou use o padrão pré-preenchido.

7. No campo Caminho dos dados particulares de saída, insira o URI do bucket do Cloud Storage. Depois do primeiro uso, esse caminho é preenchido automaticamente para execuções futuras.

8. Por padrão, todas as quatro métricas principais são adicionadas. Você pode adicionar ou remover métricas conforme necessário.

9. Clique em Avaliar agente.

Avaliar um único rastreamento ou sessão

É possível acionar avaliações diretamente ao inspecionar caminhos de execução individuais:

1. No console Google Cloud , navegue até a página Agent Platform > Agentes.
2. No menu de navegação à esquerda, selecione Implantações.
3. Selecione seu agente.

   Acessar "Implantações"

4. Selecione a guia Rastreamentos.
5. Clique em Visualização da sessão ou Visualização do rastreamento para inspecionar o caminho de execução.
6. Selecione uma linha específica na tabela para abrir o painel de detalhes.
7. Selecione a guia Avaliação.
8. Se o rastreamento ou a sessão não tiver sido avaliada, clique em Avaliar para executar uma avaliação ad hoc.

Visualizar os resultados da avaliação

Depois que a avaliação for concluída, analise os resultados para identificar lacunas de desempenho e problemas sistêmicos:

• Ver resultados de uma execução:no Google Cloud console, acesse a página Agent Platform > Agentes > Avaliação e selecione a guia Avaliações. Clique no nome de uma avaliação para conferir o relatório detalhado.

  Acessar "Avaliação"

• Detalhar traces:em um relatório de resultados, clique em qualquer linha para navegar diretamente até o trace associado e inspecionar o raciocínio (justificativas) por trás das pontuações.

Para mais informações, consulte Analisar os resultados da avaliação.