Pular para o conteúdo principal
Esta página define o vocabulário utilizado pela Observabilidade do FailproofAI. Se algum termo em outro guia parecer desconhecido, ele está definido aqui. Não é necessário ler do início ao fim: faça uma leitura rápida, ou volte quando encontrar uma palavra que queira entender melhor.

​
O modelo de dados

Evento A menor unidade de dados. Um evento registra uma única etapa que seu agente executou: um tool_use, um model_request, um hook_completed, um error, entre outros. Seu agente emite eventos por meio do Python SDK; eles aparecem em tempo real na página Events. Sessão Uma execução do agente, identificada por um session_id. Uma sessão é o conjunto de todos os eventos que compartilham esse id, consolidados em uma única linha na página Sessions e representados como um grafo de execução na página de detalhes. Uma sessão geralmente começa com agent_start e termina com agent_end. Agente Um ator nomeado dentro de uma execução, identificado por um agent_id. Uma execução pode envolver vários agentes: um planejador que cria um sub-agente de sumarização, por exemplo. Sub-agentes possuem um parent_id, que é o que permite ao FailproofAI Observability exibi-los em suas próprias faixas no grafo de execução. Ambiente Um rótulo que indica onde a execução ocorreu: production, staging, dev. Você o define uma vez ao configurar o SDK. Quase todas as páginas do painel permitem filtrar por ambiente. Preenchimento da janela de contexto O percentual da janela de contexto de um modelo que uma resposta consumiu. O FailproofAI Observability registra essa informação nos eventos model_response para os modelos que reconhece, tornando o crescimento de prompts e a compactação iminente visíveis diretamente no fluxo de eventos.

​
Qualidade

Avaliação Uma pontuação de qualidade para uma sessão concluída, produzida por um serviço de pontuação que você executa. As avaliações são opcionais: até que você conecte um avaliador, as sessões são registradas, mas não pontuadas. Cada avaliação pode conter várias pontuações nomeadas (por exemplo, helpfulness, factuality, tool_efficiency), cada uma com uma breve nota de raciocínio. Consulte Evaluation suite. Chave de pontuação O nome de uma dimensão que um avaliador reporta, como helpfulness. Alertas e auditorias podem monitorar uma chave de pontuação específica ao longo do tempo. Avaliador Seu serviço de pontuação. O FailproofAI Observability envia via POST a transcrição de uma execução concluída para ele e armazena as pontuações retornadas. Nenhum avaliador padrão é fornecido; a lógica de pontuação é sua.

​
Encontrando e corrigindo falhas

Hook Uma proteção ou efeito colateral que seu framework de agente executa em torno de uma etapa: uma verificação de segurança de conteúdo, redação de PII, um limite de orçamento. Hooks emitem eventos hook_triggered / hook_completed com um outcome (allow, deny, modify) e possuem sua própria página de observação. Regra de alerta Uma regra que dispara quando uma métrica ultrapassa um limite definido por você: taxa de erros, latência p95, custo de tokens ou uma pontuação de avaliador. Quando uma regra dispara, ela abre um incidente e notifica os canais escolhidos (e-mail, Slack, webhook, painel). Consulte Alerts. Incidente Um problema em aberto criado quando uma regra de alerta dispara. Incidentes possuem um ciclo de vida (reconhecer, atribuir, resolver) e uma linha do tempo de atividade que registra cada ação. Você também pode abrir um manualmente. Auditoria Uma investigação recorrente (de hora em hora a semanal) que analisa seus logs em conjunto nas sessões em busca de padrões de falha para os quais você ainda não escreveu uma regra: clusters de erros, pontuações baixas, outliers de latência, loops de chamadas de ferramentas e execuções que nunca foram concluídas. Enquanto um alerta monitora uma métrica que você já conhece, uma auditoria indica o que você deve analisar a seguir. Consulte Audits. Achado Um resultado classificado e fundamentado em evidências de uma execução de auditoria. Um achado nomeia um padrão, vincula às sessões exatas que o originaram e possui um ciclo de vida de triagem (reconhecer, resolver, silenciar, descartar). O FailproofAI Observability deduplica achados entre execuções, de modo que um padrão conhecido é atualizado em vez de acumulado. O assistente de IA O chat integrado ao painel que responde perguntas sobre seus agentes em linguagem natural, com base nos seus próprios dados. É somente leitura por padrão; qualquer coisa que ele crie (uma consulta salva, um painel) requer aprovação, e ele nunca pode excluir nada. Consulte AI assistant.

​
Executando

Organização (tenant) Um espaço de trabalho isolado. Uma instância do FailproofAI Observability pode hospedar várias organizações, cada uma com seus próprios usuários, chaves e dados. Cada URL do painel é definida sob o slug da sua organização (/<org-slug>/…). Coletor agenteye-collector, o daemon leve que roda em cada máquina de agente, agrupa os eventos que o SDK grava em disco e os envia para o servidor. Chave de API Um token com escopo definido que autentica um cliente no servidor. As chaves possuem permissões granulares (por exemplo, events:add para o coletor, escopos somente leitura para uma chave de painel). Consulte API keys. Servidor O serviço de ingestão e API. Ele ingere eventos, armazena o estado operacional em seus bancos de dados e serve o painel e a CLI. Painel A interface web. Cada página tem escopo definido para uma organização e lê os dados por meio da API do servidor.

​
Próximos passos

  • Overview: como essas peças se encaixam.
  • Observability: as superfícies de observação (Events, Sessions, Models, Tools, Hooks, Errors).