Index

Avaliações e registros

Santiago Cardona Atualizado por Santiago Cardona

Turn.io se integra ao Maxim para fornecer monitoramento e avaliação em tempo real de suas jornadas baseadas em IA. Uma vez conectado, cada interação de IA em suas jornadas é automaticamente rastreada e enviada ao Maxim, onde você pode revisar logs, executar avaliações e melhorar seus agentes de IA ao longo do tempo.

O que são logs de IA?

Os logs de IA capturam todas as interações entre seus usuários e os blocos de IA em suas jornadas. Cada log registra o que o usuário disse, como a IA respondeu e os detalhes subjacentes, como qual modelo foi usado e quanto tempo demorou. Isso lhe dá visibilidade total sobre o desempenho de seus agentes de IA na produção.

No Maxim, os registros são organizados como:

  • Traces — Interações individuais de IA (uma única pergunta e resposta).
  • Sessões — Conversas completas em vários turnos que agrupam traces relacionados.

O que são Avaliações de IA?

As avaliações permitem que você avalie automaticamente a qualidade de suas respostas de IA. Em vez de ler manualmente cada conversa, você pode configurar avaliadores que pontuam as respostas por questões como parcialidade, clareza, relevância, tom ou segurança.

O Maxim oferece suporte a avaliações automatizadas que são executadas continuamente em seus registros, para que você possa detectar problemas de qualidade antecipadamente e rastrear melhorias ao longo do tempo. Você pode saber mais sobre como configurar avaliações no Guia de avaliação do Maxim.

Pré-requisitos

Antes de começar, você precisará de:

  1. Uma conta Maxim. Inscreva-se caso ainda não tenha uma.
  2. Sua chave de API do Maxim e o ID do repositório — ambos encontrados no painel do Maxim.

Conecte o Maxim ao Turn.io

Etapa 1: inscreva-se no Maxim

Primeiro, você precisa se inscrever no Maxim. Basta clicar no botão abaixo para se inscrever:

Etapa 2: Crie um repositório

Os repositórios são onde os logs ficam. Na navegação principal, clique em Logs:

E então crie um novo repositório. As configurações padrão estão corretas.

Etapa 3: Obtenha seu ID do repositório

No repositório que você acabou de criar, encontre o botão (...) e clique em Copiar ID. É mais ou menos assim: cmkys49u1027tnsmqkw22tjqg.

Copiar & cole isso em algum lugar, você precisará dele mais tarde neste processo.

Etapa 4: Obtenha sua chave de API

Você pode encontrá-la no painel do Maxim em Configurações.

Copie e cole em algum lugar, você precisará dela na próxima etapa.

Etapa 5: No Turn.io, integre com Maxim

Vá para Apps > AI e encontre o aplicativo Maxim.

Clique em instalar e cole o ID do repositório e a chave de API em sua configuração:

Etapa 6: Salvar

Depois de verificarmos se está tudo bem, clique em Salvar.

E pronto! 🎉 A partir de agora, Turn.io enviará automaticamente logs de IA para Maxim. Se você já usa IA em Journeys e as pessoas estão usando suas jornadas, você deverá começar a vê-las aparecer no Maxim em alguns minutos.

Pronto!

Depois que a integração estiver ativa, cada interação de IA em suas jornadas (geração de texto, classificação, conversas com agentes de IA) será automaticamente registrada em seu repositório Maxim.

A partir daí, você pode:

  • Navegar pelos registros para ver exatamente o que seus agentes de IA estão dizendo aos usuários.
  • Configurar avaliações para pontuar automaticamente a qualidade da resposta usando LLM como juiz ou humano revise.
  • Execute simulações para testar e iterar seus prompts antes de implantar alterações.

Para saber mais sobre como aproveitar ao máximo o Maxim, visite a documentação do Maxim ou continue lendo.

Onde encontrar seu logs
  1. Abra seu Repositório no painel do Maxim.
  2. Clique na guia Registros . Você verá uma tabela de todas as interações de IA ingeridas.

Cada linha na tabela mostra um resumo de um rastreamento:

Coluna

O que é mostra

Carimbo de data/hora

Quando a interação de IA aconteceu

Nome

Nome do rastreamento, definido como seu bloco de jornada (por exemplo, "Agente de IA" ou "Texto Geração").

Entrada

A mensagem ou prompt do usuário

Saída

A IA resposta

Modelo

Qual modelo de IA foi usado (por exemplo, gpt-4o, claude-sonnet-4-5-20250514)

Tokens

Total de tokens consumidos (entrada + saída)

Custo

Custo estimado em dólares americanos para a interação

Latência

Quanto tempo a IA levou para responder

Tags

Metadados do Turn.io (nome da jornada, nome do bloco, etc.)

Entenda a hierarquia de log

O Turn.io organiza logs de IA usando uma hierarquia que mapeia como as conversas fluem através de seu jornadas:

  • Sessão — uma conversa completa entre um usuário e seu agente de IA. Todas as interações na mesma sessão de jornada compartilham um ID de sessão.
  • Trace — Uma única "execução" dentro dessa sessão. Por exemplo, se o seu bloco de agente de IA processar uma mensagem do usuário, isso será um rastreamento. Uma conversa multiturno produz vários rastreamentos agrupados na mesma sessão.
  • Geração — Os detalhes reais da chamada LLM: as mensagens enviadas ao modelo, a resposta do modelo, contagens de tokens e parâmetros.
  • Span — Etapas individuais dentro de um rastreamento, como chamadas LLM individuais ou execuções de ferramentas. Esses são os blocos de construção de cada rastreamento.
Detalhar até a geração detalhes

As informações mais úteis (as solicitações e respostas exatas) estão a apenas alguns cliques. Veja como chegar lá:

  1. Na guia Registros , clique em qualquer linha para abrir o painel de detalhes do rastreamento.
  2. Você verá um detalhamento de todos os períodos do rastreamento. Procure o intervalo raiz, que tem o nome do seu bloco de jornada (por exemplo, "Agente de IA" ou "Geração de texto").
  3. Clique no intervalo raiz para expandi-lo. Você verá períodos secundários representando eventos individuais, como chamadas LLM.
  4. Na visualização de detalhes do período, você pode ver os dados de geração: as mensagens de entrada completas (prompt do sistema, histórico de conversas, mensagem do usuário), a saída do modelo, uso de token e latência.

É aqui que você pode verificar exatamente o que seu agente de IA recebeu e como ele respondeu — algo inestimável para depurar comportamentos inesperados.

Sessões: após conversas múltiplas

No WhatsApp, os usuários raramente interagem com seu agente de IA apenas uma vez: eles fazem uma pergunta, obtêm uma resposta, acompanham, esclarecem e continuam a conversa. As sessões no Maxim capturam essas interações multivoltas como uma única unidade coerente, facilitando a revisão do arco completo de uma conversa em vez de reunir traços isolados.

Como o Turn.io mapeia conversas para sessões

Cada interação de IA em uma jornada do Turn.io é executada dentro de um sessão de jornada. Turn.io exporta automaticamente esse ID de sessão para o Maxim como session_id, o que significa:

  • Todos os rastreamentos da mesma jornada são agrupados na mesma sessão.
  • As idas e vindas de um usuário com um bloqueio de agente de IA — cada mensagem do usuário e cada resposta de IA — termina como rastreamentos separados dentro de uma sessão.
  • Quando o o usuário inicia uma nova jornada, uma nova sessão começa.

Esse mapeamento reflete como as conversas realmente acontecem: uma sessão = uma interação contínua entre um usuário e seu agente de IA.

Por que as sessões são importantes

Os rastreamentos individuais informam apenas sobre uma resposta de IA isoladamente. As sessões fornecem o contexto conversacional completo, o que é essencial quando:

  • Desvio de depuração — um agente de IA perde gradualmente o controle do que o usuário deseja. Você só pode ver isso observando a sessão completa, e não um único traço.
  • Avaliando a coerência — A IA permaneceu no tópico e lembrou-se das entradas anteriores do usuário? Avaliações em nível de sessão respondem a isso.
  • Medir o sucesso da tarefa — O usuário realmente alcançou seu objetivo ao final da conversa? Essa é uma pergunta no nível da sessão.
  • Analisar a experiência do usuário — Quando um usuário relata um problema, você deseja ler a conversa toda e não apenas o momento em que as coisas deram errado.
Encontrar e revisar sessões

Para acompanhar uma conversa específica:

  1. Na guia Registros , clique no botão Botão Sessões.
  2. Todos os rastreamentos da mesma sessão de jornada serão agrupados em ordem cronológica. Clique em qualquer sessão que você deseja explorar.
  3. Em seguida, clique em cada traço para ver como a conversa evoluiu (entrada do usuário, resposta da IA, entrada do usuário, resposta da IA), juntamente com detalhes completos de geração em cada etapa.
Filtre os registros para encontrar o que você precisa

Com viagens de alto tráfego, você deseja restringir seus registros. Maxim suporta filtragem usando as tags que Turn.io anexa a cada rastreamento:

Tag

O que ela contém

Use-a para...

journey_name

O nome da jornada que acionou a interação de IA

Filtrar todas as atividades de IA para uma jornada específica

journey_uuid

O ID exclusivo da jornada. Você pode obter isso em sua jornada:

Identificar com precisão uma jornada (útil se os nomes change)

journey_block_name

O nome do bloco de IA específico na jornada

Comparar o desempenho entre diferentes blocos de IA

session_id

A sessão de conversa ID

Acompanhar toda uma conversa do usuário em vários rastreamentos

context_type

O tipo de contexto de avaliação de IA

Filtrar por jornadas de produção ou simulações

Para filtrar seus registros:

  1. Na guia Registros, clique nos controles filtro acima da tabela.
  2. Selecione a tag pela qual deseja filtrar (por exemplo, nome_da_jornada).
  3. Insira o valor correspondente (por exemplo, "Suporte ao cliente Bot").
  4. Você pode combinar vários filtros com a lógica AND/OR para restringir ainda mais. Por exemplo, filtrar por nome_da_jornada E um período específico.
Cenários comuns

"Quero comparar o desempenho de dois blocos de IA" Filtre por journey_block_name para isolar os logs de cada bloco. Compare a latência, o uso de tokens e os custos entre eles.

"Quero ver todas as atividades de IA de uma jornada específica" Filtre por journey_name ou journey_uuid. Isso mostra cada interação de IA acionada por essa jornada, em todos os usuários e sessões.

"Quero monitorar os custos" Classifique a tabela de registros pela coluna Custo para identificar rastreamentos caros. Verifique quais modelos e jornadas estão consumindo mais tokens.

Dicas para trabalhar com logs

Use a guia Visão geral para tendências. Antes de mergulhar em logs individuais, verifique a guia Visão geral em seu repositório. Ele mostra métricas agregadas, como rastreamentos totais, gráficos de latência e taxas de erro ao longo do tempo, úteis para detectar padrões antes de detalhar detalhes.

Configure alertas para erros. Na guia Alertas, configure notificações (Slack, PagerDuty ou Opsgenie) para quando as taxas de erro aumentarem ou a latência exceder um limite. Dessa forma, você não precisa verificar os registros manualmente todos os dias.

Mantenha as tags limpas. As tags que o Turn.io envia são automáticas — você não precisa configurá-las. Mas esteja ciente de que ter uma jornada descritiva e nomes de bloco no Turn.io torna a filtragem no Maxim muito mais fácil. Um bloco denominado "AI Agent" é mais difícil de encontrar do que o "Agente de processamento de reclamações".

Configurar avaliações

Depois que seus registros estiverem fluindo para o Maxim, você poderá configurar avaliações automáticas, verificações de qualidade automatizadas que pontuam continuamente suas respostas de IA conforme elas chegam. Isso significa que você não precisa revisar manualmente cada conversa para detectar problemas.

Você pode adicionar e configurar diferentes tipos de avaliadores no Seção Avaliadores. Escolha aqueles que você considera relevantes para seu caso de uso.

Tipos de avaliadores

Maxim oferece três categorias de avaliadores:

  • Avaliadores de IA (LLM-as-a-Judge) usam um modelo de linguagem para avaliar as respostas de sua IA. Estes são os mais flexíveis e ótimos para verificações de qualidade diferenciadas:
    • Fidelidade — A resposta é baseada no contexto fornecido? Detecta alucinações.
    • Relevância da saída — A resposta realmente responde ao que o usuário perguntou?
    • Toxicidade — A resposta contém conteúdo prejudicial, ofensivo ou impróprio?
    • Clareza — A resposta é fácil de entender?
    • Concisão — A resposta é adequadamente breve, sem perder a importância informações?
    • Sucesso da tarefa — A IA atingiu o objetivo pretendido?
    • Detecção de PII — A resposta expõe inadvertidamente informações pessoais?
    • Preconceito — A resposta mostra preconceito injusto?
  • Avaliadores programáticos usam lógica baseada em regras para verificações determinísticas:
    • Formato validadores (JSON válido, URL válido, e-mail válido, etc.)
    • Correspondência de padrões e análise de conteúdo (contagem de palavras, caracteres especiais)
  • Avaliadores estatísticos comparam resultados com resultados esperados usando métricas como similaridade de cosseno, pontuações BLEU e ROUGE. Eles são úteis se você tiver respostas de referência para comparar.
Como funcionam as avaliações

As avaliações são executadas automaticamente nos seus logs com base nas regras que você define. Cada avaliador pontua uma dimensão de qualidade específica de suas respostas de IA. Você pode combinar vários avaliadores para obter uma imagem de qualidade abrangente.

O Maxim oferece suporte a avaliações em diferentes níveis de granularidade:

  • Nível de rastreamento — Avalie respostas individuais de IA. Melhor para verificar se uma única resposta foi precisa, relevante ou segura. Este é o ponto de partida mais comum.
  • Nível da sessão — avalie conversas inteiras em várias voltas. Útil para avaliar a qualidade geral da conversa, a coerência e se o objetivo do usuário foi alcançado.
Passo a passo: configurar a avaliação automática em registros
  1. Navegue até a seção Registros no Maxim e abra seu Repositório.
  2. Clique em Gerenciar avaliação no canto superior direito canto.
  3. Clique em Adicionar configuração e escolha o nível de avaliação. Trace é o melhor ponto de partida para a maioria dos casos de uso.
  4.  Selecione os avaliadores que deseja usar.
  5. Mapeie suas variáveis — conecte as entradas do avaliador aos seus dados de registro. Por exemplo, mapeie trace.output para a 'resposta" entrada para que saiba o que pontuar. Para avaliações no nível da sessão, use trace[*].output para fazer referência aos resultados de toda a conversa.
  6. (Opcional) Adicione regras de filtro para restringir quais registros serão avaliados. Você pode filtrar por tipo de modelo, status de erro, tags, latência, uso de token e muito mais. Combine várias condições com a lógica AND/OR.
  7. (Opcional) Defina uma taxa de amostragem para controlar custos. Por exemplo, avalie 20% dos rastreamentos em vez de todos eles. Isso é útil para jornadas de alto tráfego.
  8. Clique em Salvar. Novos logs serão avaliados automaticamente assim que chegarem.
Revisando os resultados da avaliação

Abra qualquer rastreamento nos logs do Maxim e clique na guia Avaliação. Você verá as pontuações de cada avaliador, juntamente com explicações sobre por que a pontuação foi dada (para avaliadores de IA).

Dicas para avaliações eficazes

Comece aos poucos e depois expanda. Comece com 2 a 3 avaliadores que abordem suas maiores preocupações, normalmente Fidelidade, Relevância dos resultados e Toxicidade. Adicione mais quando você se sentir confortável ao ler os resultados.

Use a amostragem para jornadas de alto volume. Se sua jornada lida com milhares de conversas diariamente, avaliar cada rastreamento fica caro. Uma taxa de amostragem de 10 a 20% ainda oferece forte confiança estatística e, ao mesmo tempo, mantém os custos gerenciáveis.

Combine IA e avaliadores programáticos. Os avaliadores de IA são ótimos para qualidade subjetiva, mas os avaliadores programáticos oferecem garantias determinísticas. Por exemplo, se seu agente de IA retornar JSON, adicione um avaliador isValidJSON junto com suas verificações de qualidade.

Filtre ruídos. Use regras de filtro para ignorar a avaliação de rastreamentos de erros ou rastreamentos de usuários de teste. Isso mantém suas métricas de qualidade limpas e focadas nas interações reais do usuário.

Configure alertas. Depois que suas avaliações estiverem em execução, configure alertas no Maxim para notificá-lo quando os índices de qualidade caírem abaixo de um limite. Isso transforma as avaliações de um painel passivo em um sistema de monitoramento ativo.

Para obter referência completa sobre a configuração da avaliação, consulte o Guia de avaliação automática do Maxim.

Simulando conversas

Enquanto você desenvolve ou itera um prompt, antes de enviar suas alterações aos usuários, é muito útil simular conversas usando IA e, em seguida, usar Evals para verificar se suas alterações tiveram um impacto positivo (ou negativo).

Para fazer isso, o Maxim também fornece um recurso de simulação. Você pode ver como configurá-lo aqui: Simular & Teste jornadas de IA.

Esse artigo foi útil?

Agentes

Simule e teste jornadas de IA

Contato