> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Evaluator SDK > Crie um serviço que avalia sessões do Failproof AI de forma síncrona ou assíncrona. Um avaliador recebe uma sessão de agente concluída e retorna os indicadores de qualidade que você precisa: pontuações numéricas, uma explicação para cada pontuação e um resumo opcional. O Failproof AI armazena esses resultados junto ao trace e os exibe em gráficos por agentes e ambientes. ## Configurar um avaliador Instale o SDK e o servidor utilizado para executá-lo. ```bash theme={null} pip install failproofai-sdk uvicorn ``` Crie o arquivo `evaluator.py`. Este exemplo verifica se uma sessão contém chamadas de ferramentas com falha. ```python theme={null} import os from failproofai.evaluator import Evaluator, EvalResponse app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) @app.config def config(): return {"inactivity_timeout_secs": 1800} @app.evaluator def evaluate(req): tool_errors = sum( 1 for item in req.events if item.event_type == "tool_result" and item.payload.get("error") ) return EvalResponse( scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, reasoning={"tool_reliability": f"{tool_errors} tool errors"}, ) ``` Defina um token compartilhado, inicie o avaliador e confirme que o endpoint de saúde responde. ```bash theme={null} export EVALUATOR_TOKEN= uvicorn evaluator:app --host 0.0.0.0 --port 8080 ``` Em outro terminal: ```bash theme={null} curl http://127.0.0.1:8080/health ``` ## Conectar o avaliador ao Failproof AI 1. Faça o deploy do avaliador em uma URL HTTPS acessível pelo Failproof AI Cloud. 2. Configure `EVALUATOR_ENDPOINT` com essa URL e defina `EVALUATOR_TOKEN` com o mesmo token utilizado pelo avaliador. Para o Cloud gerenciado, entre em contato com [support@befailproof.ai](mailto:support@befailproof.ai) para configurar a conexão. 3. Execute uma avaliação e confirme que as pontuações aparecem no Failproof AI. Abra uma sessão concluída em **Observe → Sessions** e selecione **Run evaluation** caso ela não tenha sido avaliada automaticamente. Revise o status, as pontuações, o raciocínio e o resumo no painel **Evaluation** da sessão. Use **Observe → Evaluations** para comparar pontuações entre agentes ou ambientes. Use **Observe → Metrics** para latência, custo, tokens e outras medições numéricas. Comece com uma única sessão para confirmar que o avaliador retornou as chaves de pontuação esperadas e um raciocínio útil para aquela execução específica. Uma visualização detalhada de sessão exibindo pontuações de avaliação e raciocínio ao lado do seu trace. Quando os resultados individuais estiverem corretos, use o dashboard de avaliações para comparar essas pontuações ao longo do tempo e entre agentes ou ambientes. Um dashboard de qualidade com gráfico de pontuações do avaliador ao longo do tempo. Um gráfico saudável deve usar nomes de pontuação estáveis; alterar uma chave cria uma série separada. ```bash theme={null} fp evals --since 1h --score tool_reliability:0..1 fp evals --since 24h --aggregate ``` Em uma instância Cloud auto-hospedada, a avaliação automática fica desativada até que `EVALUATOR_ENDPOINT` seja definido no processo do servidor. Reinicie o servidor após alterar as variáveis de ambiente do avaliador. O serviço expõe `GET /health`, `GET /config`, `POST /evaluate` e opcionalmente `GET /evaluate/{job_id}`. Retorne `JobPending` para trabalhos assíncronos e registre `@app.job_lookup` para que o Failproof AI possa fazer polling. Quando um token está configurado, todas as rotas, exceto health, exigem o mesmo bearer token que o Failproof AI envia como `EVALUATOR_TOKEN`. ## Tipos do SDK | Tipo | Campos | | ----------------- | --------------------------------------------------------------------------------------------- | | `AgentEvent` | `id`, `ts`, `event_type`, `payload` | | `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | | `EvalResponse` | `scores`, `reasoning`, `summary` | | `JobPending` | `job_id`, `next_poll_secs` | | `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | ## Decoradores e rotas | Decorador | Rota | Obrigatório | | ----------------- | ------------------------ | ------------------------ | | `@app.evaluator` | `POST /evaluate` | Sim | | `@app.job_lookup` | `GET /evaluate/{job_id}` | Ao retornar `JobPending` | | `@app.config` | `GET /config` | Não | O SDK limita o corpo das requisições de avaliação a 25 MiB. Campos desconhecidos nas requisições são ignorados, mantendo os serviços compatíveis à medida que o contrato de eventos evolui. ## Retornar trabalho assíncrono Use `JobPending` quando a avaliação não puder ser concluída dentro de uma única requisição. O ID do job é opaco para o Failproof AI e deve permanecer resolvível pelo seu serviço até que o resultado seja coletado ou o timeout do servidor expire. ```python theme={null} from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending app = Evaluator(token="shared-secret") @app.evaluator def start(req: EvalRequest) -> JobPending: job_id = enqueue(req) return JobPending(job_id=job_id, next_poll_secs=30) @app.job_lookup def lookup(job_id: str): result = get_result(job_id) if result is None: return JobPending(job_id=job_id, next_poll_secs=30) return EvalResponse( scores=result.scores, reasoning=result.reasoning, summary=result.summary, ) ``` A cadência de polling é selecionada nesta ordem: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs` e, em seguida, `EVALUATOR_POLLING_INTERVAL_SECS` do servidor. Os valores são limitados entre 1 segundo e 1 hora. O limite padrão de polling em tempo real do servidor é de uma hora. ## Campos de requisição e resposta | Campo | Tipo | Observações | | --------------------------------------- | -------------------------- | ------------------------------------------------------------- | | `EvalRequest.schema_version` | `str` | Atualmente `"1"`. | | `session_id`, `agent_id`, `environment` | `str` | Identidade da sessão e ambiente. | | `started_at` | `datetime` | Timestamp do primeiro evento. | | `ended_at` | `datetime \| None` | Presente quando a sessão emitiu um evento de encerramento. | | `events` | `list[AgentEvent]` | Stream de eventos completo e ordenado. | | `AgentEvent.id` | `int` | Identificador da linha do evento no backend. | | `AgentEvent.ts` | `datetime` | Timestamp do evento. | | `AgentEvent.event_type` | `str` | Família do evento, como `tool_use`. | | `AgentEvent.payload` | `dict[str, Any]` | Payload completo do evento. | | `EvalResponse.scores` | `dict[str, float] \| None` | Dimensões numéricas exibidas em gráficos nas avaliações. | | `EvalResponse.reasoning` | `dict[str, str] \| None` | Explicações por pontuação; as chaves devem espelhar `scores`. | | `EvalResponse.summary` | `str \| None` | Narrativa geral da avaliação. | ## Configurações para operadores do servidor A avaliação automática é aplicada a todo o deployment e permanece desativada quando `EVALUATOR_ENDPOINT` não está definido. | Variável | Padrão | Finalidade | | ---------------------------------- | ------------ | ------------------------------------------------------ | | `EVALUATOR_ENDPOINT` | não definido | URL base do serviço avaliador. | | `EVALUATOR_TOKEN` | não definido | Bearer token compartilhado com `Evaluator(token=...)`. | | `EVALUATOR_WORKERS` | `2` | Workers de despacho concorrentes. | | `EVALUATOR_CLAIM_BATCH` | `4` | Sessões reivindicadas por passagem do dispatcher. | | `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadência de polling assíncrono de fallback. | | `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Timeout do avaliador por requisição. | | `EVALUATOR_MAX_ATTEMPTS` | `5` | Tentativas de entrega antes de falha terminal. | | `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadência de atualização para `/config`. | | `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tempo máximo de polling assíncrono em tempo real. | O servidor também pode restringir quais organizações utilizam o avaliador global do deployment. Trate alterações de endpoint, token, retry e controle de organização como configuração de operador e reinicie ou faça rollout do servidor após modificá-las. ## Segurança e operações * Coloque o avaliador atrás de HTTPS quando o tráfego cruzar um limite de rede confiável. * Configure um bearer token não vazio e mantenha-o idêntico em ambos os serviços. * Não registre o token nem prompts sensíveis completos dos payloads de requisição. * Torne os handlers síncronos idempotentes; tentativas de retry podem repetir uma requisição. * Persista o estado de jobs assíncronos fora da memória do processo em produção. * Retorne chaves de pontuação estáveis. Renomear uma chave cria uma nova série no gráfico em vez de alterar a existente. O SDK emite logs de ciclo de vida estruturados como `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` e exceções de handlers. Ele não configura handlers de logging; utilize a configuração de logging da aplicação host.