Evaluator SDK

​

Configurar um avaliador

pip install failproofai-sdk uvicorn

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"},
    )

export EVALUATOR_TOKEN=<shared-token>
uvicorn evaluator:app --host 0.0.0.0 --port 8080

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 usado pelo avaliador. Para o Cloud gerenciado, entre em contato com support@befailproof.ai para configurar a conexão.
3. Execute uma avaliação e confirme que as pontuações aparecem no Failproof AI.

• Dashboard
• CLI

Abra uma sessão concluída em Observe → Sessions e selecione Run evaluation se ela não foi 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 medições de latência, custo, tokens e outros valores numéricos.Comece com uma 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.Quando os resultados individuais parecerem corretos, use o dashboard de avaliação para comparar essas pontuações ao longo do tempo e entre agentes ou ambientes.Um gráfico saudável deve usar nomes de pontuação estáveis; alterar uma chave cria uma série separada.

fp evals --since 1h --score tool_reliability:0..1
fp evals --since 24h --aggregate

​

Tipos do SDK

​

Decoradores e rotas

​

Retornar trabalho assíncrono

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,
    )

​

Campos de requisição e resposta

​

Configurações do operador do servidor

​

Segurança e operações

• Coloque o avaliador atrás de HTTPS quando o tráfego cruzar um limite de rede não confiável.
• Configure um bearer token não vazio e mantenha-o idêntico em ambos os serviços.
• Não registre em log o token nem prompts sensíveis completos dos payloads das requisições.
• Torne os handlers síncronos idempotentes; novas tentativas 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.