Evaluator SDK

Evaluator SDK는 자체 인프라에서 평가를 실행합니다. 워커가 Failproof AI에 평가를 등록하고, 세션이 완료되면 가져와서 점수를 매긴 뒤 결과를 제출합니다. 모든 통신은 아웃바운드 HTTPS로 이루어지며, 외부에서 워커로 직접 연결하는 일은 없습니다. 호스팅 Python으로 할 수 없는 작업 — LLM 판정자, 모델 호출, 패키지, 시크릿, 네트워크 접근 — 에 활용하세요. 결과는 evaluations 페이지에서 호스팅 결과와 함께 customer 태그로 표시됩니다. 이 SDK는 failproofai-sdk 패키지의 failproofai_sdk.evaluator 모듈에 포함되어 있으며, 트레이싱 SDK를 임포트해도 자동으로 로드되지 않습니다.

pip install failproofai-sdk

평가 작성

from failproofai_sdk.evaluator import ConditionResult, EvalResult, Evaluator, Metric, Score

app = Evaluator(name="customer-production", version="2026.08.1")


@app.eval(
    "tool_efficiency",
    version="1.0.0",
    labels=["tools", "deterministic"],
    when=lambda session: ConditionResult(session.count("tool_use") > 0, "no_tool_calls"),
)
def tool_efficiency(session):
    calls = session.events_of_type("tool_use")
    distinct = {e.payload.get("tool_name") for e in calls if e.payload.get("tool_name")}
    value = len(distinct) / len(calls)
    return EvalResult(
        score=Score(value, passed=value >= 0.7),
        metrics={"tool_call_count": Metric(len(calls), unit="events")},
        reasoning=f"{len(distinct)} distinct tools across {len(calls)} calls",
    )


@app.eval(
    "answer_relevance",
    version="judge-v1",
    labels=["llm_judge", "relevance"],
    when=lambda session: ConditionResult(
        session.count("human_input") > 0 and session.count("model_response") > 0,
        "no_exchange",
    ),
    timeout_seconds=30,
)
async def answer_relevance(session):
    question = session.events_of_type("human_input")[-1].payload.get("response")
    answer = session.events_of_type("model_response")[-1].payload.get("content")
    value, reasoning = await ask_judge(question, answer)  # your LLM call: a 0-1 score and why
    return EvalResult(score=Score(value, passed=value >= 0.7), reasoning=reasoning)


if __name__ == "__main__":
    app.run_from_env()

@app.eval(key, version=...) 은 평가를 등록합니다. key는 결과가 표시될 이름이며, 로직이 변경될 때마다 version을 업데이트하면 각 결과에 생성 당시의 버전이 기록됩니다. 하나의 워커는 최대 100개의 평가를 보유할 수 있습니다.
result_kind 는 별도로 지정하지 않으면 "score" 입니다. "metric" 또는 "assertion" 평가의 경우, metrics 또는 assertions 항목 중 하나의 이름을 key와 동일하게 지정하면 해당 항목이 결과로 사용됩니다.
when 은 세션 적용 여부를 결정합니다. ConditionResult(False, "<reason>") 를 반환하면 해당 세션을 건너뛰고, 이유가 기록됩니다.
평가 함수는 일반 함수 또는 async 함수로 정의할 수 있으며, timeout_seconds 로 실행 시간을 제한할 수 있습니다.
페이로드 키 — 위 예시의 tool_name, response, content — 는 에이전트가 전송하는 값이므로, 실제 세션에서 확인하여 사용하세요.

워커 실행

Administration → Keys 에서 evaluations:run 권한을 가진 키를 생성하고, FAILPROOFAI_EVALUATOR_TOKEN 환경 변수에 설정하세요. 명령어에 직접 입력하지 말고 시크릿 저장소를 통해 설정하는 것을 권장합니다. 그런 다음 워커를 시작합니다:

FAILPROOFAI_EVALUATOR_URL=https://app.befailproof.ai python evaluator.py

__main__ 블록 없이 사용할 경우, python -m failproofai_sdk.evaluator evaluator:app 으로도 동일하게 실행할 수 있습니다.

변수	기본값	설명
`FAILPROOFAI_EVALUATOR_URL`	필수	Failproof AI 주소: Cloud의 경우 `https://app.befailproof.ai`. 루프백을 가리키지 않는 한 HTTPS 사용
`FAILPROOFAI_EVALUATOR_TOKEN`	필수	`evaluations:run` 권한을 가진 키
`FAILPROOFAI_EVALUATOR_WORKER_ID`	`<hostname>-<pid>`	이 워커의 이름
`FAILPROOFAI_EVALUATOR_CONCURRENCY`	`1`	동시에 점수를 매길 세션 수
`FAILPROOFAI_EVALUATOR_REQUEST_TIMEOUT_SECONDS`	`30`	Failproof AI에 대한 각 요청의 타임아웃
`FAILPROOFAI_EVALUATOR_DRAIN_TIMEOUT_SECONDS`	`60`	워커 종료 시 진행 중인 작업을 기다리는 시간
`FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP`	`false`	루프백이 아닌 URL에 대한 평문 HTTP 허용 — 아래 경고 참조
`FAILPROOFAI_EVALUATOR_MODULE`	없음	`python -m failproofai_sdk.evaluator` 에 사용할 `module:attribute`

FAILPROOFAI_EVALUATOR_ALLOW_INSECURE_HTTP 를 사용하면 모든 데이터가 평문으로 전송됩니다. 워커는 모든 요청의 Authorization: Bearer 헤더에 FAILPROOFAI_EVALUATOR_TOKEN 을 포함하며, 가져오는 트랜스크립트는 세션 자체입니다. 따라서 경로상의 누구든 토큰과 내용을 모두 읽을 수 있으며, 탈취된 토큰은 교체 전까지 평가 실행에 악용될 수 있습니다. 격리된 개발 네트워크에서만 사용하세요. 그 외 모든 환경에서는 URL이 HTTPS여야 하며, 루프백은 플래그 없이 사용할 수 있습니다.

결과 타입

타입	필드
`Score`	`value` (0~1), `passed`, `unit` (기본값 `ratio`), `display_value`, `description`
`Metric`	`value`, `unit`, `display_value`, `description`
`Assertion`	`passed`, `description`
`EvalResult`	`score`, `metrics`, `assertions`, `reasoning`, `summary`, `labels`
`ConditionResult`	`applicable`, `reason_code`

EvalResult 는 score, metric, assertion 중 최소 하나 이상, 최대 25개까지 고유한 키로 포함해야 합니다.

세션

필드 또는 메서드	반환값
`session_id`, `agent_id`, `environment`	세션의 식별 정보
`started_at`, `ended_at`	세션 시작 및 종료 시각
`event_count`, `events`	전체 이벤트 목록 (순서 유지)
`count(event_type)`	해당 타입의 이벤트 수
`events_of_type(event_type)`	해당 타입의 이벤트 목록 (순서 유지)

각 이벤트는 id, ts, event_type, payload 를 포함합니다.

레거시 Evaluator

이전 Evaluator SDK — Failproof AI가 EVALUATOR_ENDPOINT 로 호출하고, /evaluate 엔드포인트에서 응답하며 JobPending 방식으로 폴링되는 HTTP 서비스 — 는 지원이 종료되었습니다. 새로운 평가는 이 워커 방식으로 구축하세요. 레거시 서비스를 운영 중인 셀프 호스팅 인스턴스의 운영자는 전환 기간 동안 기존 방식을 유지할 수 있습니다.

Connect your agents

Reference

평가 작성

워커 실행

결과 타입

세션

레거시 Evaluator

​평가 작성

​워커 실행

​결과 타입

​세션

​레거시 Evaluator

평가 작성

워커 실행

결과 타입

세션

레거시 Evaluator