Evaluator SDK

Evaluator SDKは、独自のインフラ上で評価を実行します。ワーカーはFailproof AIに評価を登録し、セッションが完了するたびにそれを取得してスコアリングし、結果を送信します。すべてアウトバウンドHTTPS経由で行われるため、外部から接続を受け付けません。ホスト型Pythonでは実現できないLLMジャッジ、モデル呼び出し、パッケージ、シークレット、ネットワークアクセスを活用するためにご利用ください。結果は評価ページにホスト型の結果と並んで表示され、customer タグが付きます。 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=...) で評価を登録します。キーは結果のチャート表示に使われます。ロジックを変更したらバージョンも更新してください。各結果にはそれを生成したバージョンが保持されます。1つのワーカーには最大100件の評価を登録できます。
result_kind は特に指定しない限り "score" です。"metric" または "assertion" 評価の場合は、metrics または assertions エントリのいずれか1つにキーと同じ名前を付けてください。そのエントリが結果として扱われます。
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 のURL。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 にはスコア、メトリクス、アサーションのいずれかが少なくとも1つ必要で、最大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 SDK（Failproof AIが EVALUATOR_ENDPOINT でHTTPサービスを呼び出し、/evaluate に応答し、JobPending でポーリングする方式）は廃止されました。新しい評価器はこのワーカーを使用して構築してください。レガシーサービスを稼働中のセルフホスト環境のオペレーターは、移行期間中は引き続き使用できます。

Connect your agents

Reference

評価の作成

ワーカーの起動

結果の型

セッション

レガシー評価器

​評価の作成

​ワーカーの起動

​結果の型

​セッション

​レガシー評価器

評価の作成

ワーカーの起動

結果の型

セッション

レガシー評価器