Logs, rastreamentos e monitoramento

Um cliente relata que um agente prometeu atualizar o endereço de entrega, mas nada mudou. Ler a resposta final informa o que o agente disse. Não informa se o agente verificou permissão, contatou o sistema de pedidos ou recebeu um erro. Monitoramento significa observar o comportamento do sistema ao longo do tempo para que esses problemas possam ser detectados e investigados em vez de permanecerem como reclamações isoladas.

Pense em um restaurante. O cliente vê a refeição chegar, mas o restaurante precisa saber quando o pedido foi feito, quando a cozinha o recebeu e se um ingrediente estava indisponível. Um agente também tem várias etapas entre a solicitação e o resultado. Um monitoramento útil conecta essas etapas sem transformar o caderno do restaurante em uma cópia desnecessária da vida privada de cada cliente.

Uma linha de log registra um evento; um rastreamento conecta a jornada #

Um log é um registro de eventos. Uma linha de log, ou registro de evento, pode dizer que uma busca de documento foi concluída, que uma ferramenta falhou ou que uma resposta foi entregue. Bons eventos registram quando algo aconteceu, qual etapa o produziu e se teve sucesso. Uma ferramenta é uma função conectada que o agente pode solicitar, como uma consulta de pedido. “Chamada de ferramenta concluída” precisa ter um significado claro: receber uma resposta não significa necessariamente concluir a ação de negócio.

Um rastreamento agrupa eventos e tempos relacionados para uma solicitação, permitindo seguir toda a jornada. Cada parte crada é frequentemente chamada de span. Uma referência de solicitação compartilhada conecta as partes mesmo quando sistemas diferentes as manipulam. Ela deve ser uma referência opaca, não um endereço de e‑mail ou outro detalhe pessoal. Um rastreamento explica a sequência e onde o tempo foi gasto; ainda precisa de interpretação para explicar por que o resultado foi errado.

Recuperação significa encontrar material relevante, como um parágrafo de política, para ajudar o agente a responder. Um modelo é o sistema que interpreta a solicitação e produz linguagem ou solicita ações. Algumas perguntas não precisam de recuperação ou chamada de ferramenta; outras envolvem várias rodadas. O fluxo é um exemplo de ensino, não uma regra que todo agente segue exatamente nessa ordem.

sequenceDiagram
    participant User as User
    participant Agent as Agent
    participant Knowledge as Knowledge search
    participant Tool as Business tool
    User->>Agent: Ask about an order
    Agent->>Knowledge: Retrieve applicable policy
    Knowledge-->>Agent: Return relevant passages
    Agent->>Tool: Request permitted order lookup
    Tool-->>Agent: Return result or error
    Agent-->>User: Explain the supported outcome

Suponha que a busca na política tenha sido bem‑sucedida e o modelo tenha solicitado a ferramenta correta, mas o sistema de negócio tenha rejeitado a ação. Essa evidência aponta para um lugar diferente de um agente que nunca solicitou a ferramenta. Se a ferramenta teve sucesso mas o agente relatou falha, a interpretação final pode ser o problema. Sem registros conectados, as equipes costumam reescrever prompts para corrigir falhas que pertencem a uma configuração de permissão ou a um serviço indisponível.

Decida o que registrar antes de precisar #

Registre o suficiente para responder a perguntas práticas: o que foi solicitado, qual versão o processou, quais etapas foram executadas, quanto tempo levaram, quais resultados foram relatados e o que o usuário recebeu ao final. Uma versão identifica uma configuração específica de instruções, modelo, conhecimento e ferramentas. Sem ela, uma falha antiga pode ser impossível de reproduzir após mudanças na configuração.

Prefira campos estruturados, ou seja, entradas nomeadas como etapa, duração e resultado, em vez de uma frase livre diferente para cada evento. A consistência torna possível agrupar falhas e comparar períodos. Mantenha as categorias de erro compreensíveis: uma recusa de permissão, registro ausente e interrupção temporária de serviço exigem respostas diferentes. Não agrupe tudo em “erro desconhecido” se o sistema de origem fornecer uma distinção segura e útil.

Raramente é necessário acessar o raciocínio interno privado de um modelo para diagnosticar um processo de negócio. Registre entradas observáveis, evidências recuperadas, ações solicitadas e saídas confirmadas dentro da sua política de privacidade. Quando uma explicação for útil, peça um raciocínio conciso voltado ao usuário, baseado em evidências. Isso não deve ser tratado como um relato completo ou autoritário de como o modelo produziu sua resposta.

Trate os dados de monitoramento como sensíveis #

O texto de uma conversa pode conter informações pessoais mesmo quando seu formulário não as solicitou. Resultados de ferramentas podem revelar detalhes de conta, e trechos de documentos podem conter material confidencial de negócio. Minimização de dados significa coletar apenas o que é necessário para um propósito declarado. Decida se os metadados do evento são suficientes antes de armazenar o conteúdo completo. Metadados descrevem um evento, como sua duração ou categoria, em vez de reproduzir sua mensagem.

Use redação, a remoção ou mascaramento de campos sensíveis, antes que os registros cheguem a um sistema de log amplamente acessível. Remover apenas nomes não torna uma conversa anônima: uma combinação distinta de datas, papéis e eventos pode identificar alguém. Restrinja o acesso, defina períodos de retenção e garanta que os procedimentos de exclusão cubram registros copiados. Retenção é o tempo que os dados são mantidos. Veja Privacy: LGPD and GDPR para as responsabilidades mais amplas.

Evidências de produção e exemplos de treinamento são usos diferentes dos dados. Permissão para investigar um incidente não autoriza automaticamente compartilhar sua transcrição com todos os desenvolvedores ou usá‑la para melhorar um modelo. Mantenha casos de teste reutilizáveis livres de detalhes pessoais desnecessários e revise qualquer transferência para outro serviço. Documente quem pode aprovar o acesso e quais registros nunca devem incluir credenciais ou segredos.

Transforme sinais em ação #

Um alerta é uma notificação de que uma condição requer atenção. Alertas úteis descrevem um problema acionável, como um aumento sustentado em buscas de pedidos falhas ou solicitações que deixam de ser concluídas. Eles nomeiam um responsável e vinculam a um procedimento de resposta curto. Alertar a cada frase incomum cria ruído e pode treinar as pessoas a ignorar o sinal que realmente importa.

Revise conversas assim como erros do sistema. Amostre sessões que parecem bem‑sucedidas, sessões abandonadas, escalonamentos e feedback negativo. Leia mensagens circundantes suficientes para entender o objetivo do usuário; uma resposta isolada pode parecer errada quando era uma pergunta de acompanhamento razoável. Use a mesma lista de verificação de revisão entre revisores e distinga uma resposta não suportada de uma recusa justificada. O primeiro precisa de correção; o segundo pode indicar que expectativas ou rotas de escalonamento precisam de esclarecimento.

Relacionado no AIVAX: Um AI gateway armazena a configuração do agente, portanto identifique qual configuração foi usada na interação revisada. O guia Data Collecting descreve um programa separado e opcional para dados elegíveis de busca semântica e reranking. Não é um interruptor de registro de solicitações, e habilitá‑lo não inclui por si só conversas ou chamadas de ferramenta não relacionadas. Revise seus termos independentemente do seu design de monitoramento.

Próximos passos: Transforme a evidência em mudanças controladas em Continuous improvement from real conversations.