リモート Scorer でエージェントのターンをスコアリングする

リモート Scorer シグナルは、LLM ジャッジモデルの代わりに、お客様がホストする HTTP エンドポイントを使用して、完了したエージェントのターンをそれぞれスコアリングします。ターンが終了すると、W&B Weave のエージェントスコアリングワーカーがそのターンを HTTP POST でお客様のエンドポイントに送信し、応答をそのターンのフィードバックとして記録します。結果は、Agents ビューの Signals タブにタグまたは評価として表示されます。このページでは、エージェントのターンを対象とするリモート Scorer について説明します。@weave.op でトレースした Call をスコアリングする場合は、リモート Scorer で Call をスコアリングするを参照してください。リモート Scorer は Python SDK または Weave UI で設定します。TypeScript SDK には RemoteScorer は含まれていません。

エージェントのターンのスコアリングの仕組み

エージェントのターンは、次の順序でスコアリングされます。

ターンが終了します。ルートスパン (親を持たないスパン) が終了すると、Weave はそれを完了したターンとして扱い、weave.genai.turn_ended イベントを発行します。
エージェントスコアリングワーカーが、project 内で weave.genai.turn_ended を対象とする実行中のシグナルを読み込み、各シグナルのフィルターとサンプリング率を適用します。
条件に一致したシグナルの各 RemoteScorer について、ワーカーはターンのスパンからメッセージを含む schema_version: 2 リクエストを構築し、Scorer の認証情報を解決して、エンドポイント URL を許可されたホストと照合したうえで POST を送信します。
ワーカーは応答を検証し、その結果をターンのフィードバックとして書き込みます。タグと評価は Signals タブに表示されます。

Weave がスコアリングするのは完了したターンのみです。個々の LLM スパンやツールスパン、および会話全体は、リモートスコアリングの対象外です。リモート Scorer のシグナルは、UI と SDK のどちらで作成した場合でも、op_names が ["weave.genai.turn_ended"] である Monitor です。ワーカーは、失敗した試行を同じ Idempotency-Key で再試行します。再試行は、最初の試行から 30 秒以内に最大 3 回まで行われます。5xx、408、429 の応答は再試行の対象です。タイムアウトの場合は 30 秒をすべて使い切るため、再試行されません。その他の 4xx 応答も再試行されません。エンドポイントが時間内にターンをスコアリングできない場合は、リクエストをタイムアウトさせずに、すぐに 503 を返してください。これにより Weave が再試行します。Weave はタグと評価を型付きのフィードバック列として保存するため、エージェントのターンのスコアリングには構造化された結果形式が必要です。

リモートスコアリングを有効にする

リモートスコアリングは、組織またはデプロイメントで有効化されるまではオフになっています。また、スコアリングワーカーが Scorer エンドポイントを呼び出すのは、そのホストが許可リストに登録されている場合に限られます。有効化の方法はデプロイメントタイプによって異なります。 Multi-tenant Cloud 組織でリモート Scorer を有効にするには、組織の管理者または請求管理者が次の手順を実行する必要があります。

https://wandb.ai/account-settings/[ORG]/settings を開きます。[ORG] は、ご利用の project を所有する組織に置き換えてください。
Remote scoring タブを選択します。
Enable remote scoring をオンにします。
Allowed hosts で Add host をクリックし、リモート Scorer の呼び出し先となるホストをそれぞれ入力します。リモートスコアリングを有効にした状態で保存するには、ホストを 1 つ以上指定する必要があります。そのホストのすべてのポートを許可する場合は、ポートを空欄のままにします。
Save settings をクリックします。

専用クラウド デプロイメントでのリモートスコアリングの有効化と、許可するホストの設定を W&B に依頼してください。 セルフマネージド W&B Weave を W&B Self-Managed デプロイメントで実行している場合は、各スコアリングワーカー (オンライン評価ワーカー、Call スコアリングワーカー、エージェントスコアリングワーカー) で、extraEnv を使用して次の環境変数を設定します。

環境変数	デフォルト	効果
`WF_SCORING_WORKER_REMOTE_SCORING_ENABLED`	`false`	リモート Scorer への送信リクエストを有効にします。`false` の場合、他の設定に関係なく、リモート Scorer は一切実行されません。
`WF_SCORING_WORKER_REMOTE_HTTP_TIMEOUT_SECONDS`	`30`	Scorer エンドポイントへのリクエストごとのタイムアウトです。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_HOSTS`	空	オペレーターが管理する許可リストです。`host` または `host:port` 形式のエントリをカンマ区切りで指定します。
`WF_SCORING_WORKER_REMOTE_SCORER_VALIDATE_HOSTS`	`true`	許可ホストリストを適用します。この設定に関係なく、プライベートアドレス、ループバックアドレス、クラウドメタデータアドレスは常に拒否されます。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOW_INSECURE_HTTP`	`false`	`http://` で始まるエンドポイント URL を許可します。
`WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS`	空	リモート Scorer からの呼び出しを許可するプライベートアドレスの CIDR ネットワーク (`10.0.0.0/8` など) をカンマ区切りで指定します。

Weave UI にリモートスコアリングの設定と Scorer のオプションを表示するには、W&B サーバーで GORILLA_GATE_WEAVE_REMOTE_SCORING=true も設定してください。 許可ホストのルール スコアリングワーカーは、すべての scorer のエンドポイント URL を以下のルールに照らしてチェックします。scorer が OAuth を使用する場合は、OAuth トークンエンドポイント URL も別途チェックします。

エントリは、ホスト名が完全に一致するホストに一致します。ポートは任意で指定できます。ポートを指定しないエントリでは、そのホストのすべてのポートが許可されます。
*. で始まるエントリは、任意の階層のサブドメインに一致しますが、ドメイン自体には一致しません。たとえば、*.corp.example.com は a.corp.example.com や a.b.corp.example.com には一致しますが、corp.example.com には一致しません。*. に続く接尾辞には 2 つ以上のラベルが必要なため、*.com は拒否されます。ワイルドカードと IP アドレスを組み合わせることはできません。
オペレーターの許可リストと組織の許可リストの両方が存在する場合、URL は両方の条件を満たす必要があります。オペレーターの許可リストが空の場合、追加の制限はかかりません。許可リストが 1 つも存在しない場合、ワーカーはすべてのホストを拒否します。
ループバック、プライベート、内部、およびクラウドメタデータのアドレスは拒否されます。セルフマネージドでは、WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS に指定したネットワーク内のプライベートアドレスは許可されます。
デプロイメントで安全でない HTTP が許可されている場合を除き、HTTPS が必須です。
リダイレクトには追従しません。

scorer エンドポイントを構築する

エンドポイントは、Weave から JSON の POST リクエストを受け入れ、JSON 形式でスコアを返します。リファレンス実装については、サンプルコードを参照してください。

リクエスト

Weave は、スコアリング対象ごとに 1 件の HTTP POST リクエストを、次のヘッダーを付けて Scorer のエンドポイント URL に送信します。

ヘッダー	値
`Content-Type`	`application/json`
`Authorization`	`Bearer [TOKEN]`
`Idempotency-Key`	スコアリング対象、モニターのバージョン、Scorer のバージョンから導出されるキー。
`X-Correlation-ID`	このリクエストの相関 ID。
`X-Weave-Schema-Version`	`1` または `2`。ボディ内の `schema_version` と同じ値です。

Weave は同じスコアリング試行を複数回配信する場合があります。エンドポイントで必要に応じて、Idempotency-Key を使用して重複を排除してください。キーは同じリクエストバージョン内では変わりません。そのため、同じ Call に対する V1 リクエストと V2 リクエストでは、キーが異なります。すべてのリクエストボディには、次のトップレベルフィールドが含まれます。

フィールド	説明
`schema_version`	整数。`1` または `2`。
`scoring_call_id`、`scoring_trace_id`	このスコアリング試行の識別子。
`monitor`	対象を選択したモニターの `name` と `version_digest`。
`scorer`	`name`、`ref`、およびオプションの `config`。`config` は `RemoteScorer` に設定されたマッピングで、変更されずにそのまま渡されます。
`triggered_at`	オプションの ISO 8601 タイムスタンプ。

Weave は、値のないオプションフィールドを null として送信せず、省略します。また、バージョン番号を変更せずにオプションフィールドを追加する場合があるため、認識できないフィールドは無視してください。リクエストボディと応答ボディのサイズ上限はそれぞれ 1 MiB で、内容は JSON テキストのみです。画像、オーディオ、動画が含まれることはありません。これらの制限を超える対象は送信されないため、スコアリングも行われません。1 件のリクエストに含まれる対象は 1 つです。エージェントのターンのリクエストには、2 つのバージョン番号が含まれます。トップレベルの schema_version は範囲のバージョンで、エージェントのターンの場合は 2 です。スコアリング対象のデータは scoring_target に格納されます。これは次の 3 つのフィールドを持つタグ付き共用体です。

type: 対象の種類です。ターンの場合は agent_turn です。コントラクトでは call も定義されていますが、エージェントのターンのスコアリングで送信されることはありません。
schema_version: そのタイプのペイロードのバージョンです。範囲のバージョンとは別にカウントされます。agent_turn のペイロードのペイロードバージョンは 1 です。
payload: そのタイプのデータです。

まず範囲のバージョンを確認し、次に scoring_target.type と scoring_target.schema_version の組み合わせを確認して、ペイロードのスコアリング方法を決定します。エンドポイントで処理しない組み合わせ (エージェントのターンのみをスコアリングする場合の call など) には 4xx を返します。ペイロードバージョン 1 の agent_turn ペイロードには、次のフィールドがあります。

フィールド	説明
`event_type`	`weave.genai.turn_ended`。
`project_id`	project。`[YOUR-TEAM]/[YOUR-PROJECT]` の形式です。
`trace_id`, `span_id`	ターンのルートスパンの識別子です。
`span_name`	スパン名です。例: `invoke_agent sample-support-agent`。
`operation_name`	GenAI の操作名です。例: `invoke_agent`。トレースに記録されていない場合は `null` です。
`started_at`, `ended_at`	ISO 8601 形式のタイムスタンプです。
`conversation`	`id` と `name`。トレースに記録されていない項目は `null` になります。
`agent`	`name`、`version`、`description`。トレースに記録されていない項目は `null` になります。
`status`	`code`、`message`、`error_type`。`code` は `UNSET`、`OK`、`ERROR` のいずれかです。`message` と `error_type` は、トレースに記録されていない場合は `null` です。
`messages`	`system_instructions`、`input`、`output`。いずれもリストで、ターンにその種類のメッセージがない場合は `[]` になります。

明示的なステータスを持たずに終了したターンは、status.code が UNSET の状態で届きます。UNSET は正常に完了したターンとして扱い、ERROR を失敗のシグナルとして扱ってください。input と output の各メッセージには、role、content、finish_reason があります。content は通常はプレーンテキストですが、メッセージにツール呼び出しなどの構造化コンテンツが含まれる場合は、パーツの配列を JSON エンコードした文字列になります。

{
  "schema_version": 2,
  "scoring_target": {
    "type": "agent_turn",
    "schema_version": 1,
    "payload": {
      "event_type": "weave.genai.turn_ended",
      "project_id": "[YOUR-TEAM]/[YOUR-PROJECT]",
      "trace_id": "0af7651916cd43dd8448eb211c80319c",
      "span_id": "b7ad6b7169203331",
      "span_name": "invoke_agent sample-support-agent",
      "operation_name": "invoke_agent",
      "started_at": "2026-06-08T12:00:00+00:00",
      "ended_at": "2026-06-08T12:00:01+00:00",
      "conversation": {
        "id": "conversation-0001",
        "name": "Support session"
      },
      "agent": {
        "name": "sample-support-agent",
        "version": "2026-06-08",
        "description": "Answers support questions"
      },
      "status": {
        "code": "UNSET",
        "message": null,
        "error_type": null
      },
      "messages": {
        "system_instructions": [
          "Answer the user accurately and concisely."
        ],
        "input": [
          {
            "role": "user",
            "content": "What are your support hours?",
            "finish_reason": ""
          }
        ],
        "output": [
          {
            "role": "assistant",
            "content": "Our support team is available Monday through Friday, 9am to 5pm Eastern.",
            "finish_reason": "stop"
          }
        ]
      }
    }
  },
  "scoring_call_id": "018f8d6c-8d5f-7000-8000-000000000005",
  "scoring_trace_id": "018f8d6c-8d5f-7000-8000-000000000006",
  "monitor": {
    "name": "example_remote_scorer_agent_monitor",
    "version_digest": "monitor-version-digest"
  },
  "scorer": {
    "name": "example_remote_scorer",
    "ref": "weave:///[YOUR-TEAM]/[YOUR-PROJECT]/object/example_remote_scorer:scorer-version-digest",
    "config": {
      "example_threshold": 0.8
    }
  },
  "triggered_at": "2026-06-08T12:00:02+00:00"
}

Weave は、ペイロードバージョンを変更せずに、ペイロードにオプションのフィールドを追加します。フィールドの削除、リネーム、または意味の変更は、そのタイプの新しいペイロードバージョンを発行する場合にのみ行います。範囲に対する変更の場合は、新しい範囲バージョンを発行する場合にのみ行います。新しいターゲットタイプは、ペイロードバージョン 1 として V2 共用体に追加されます。

応答

次の 2 つのフィールドを含む JSON オブジェクトを、HTTP 200 で返します。

schema_version: リクエストの schema_version と同じ値の整数。
result: 1 つのスコアオブジェクト、スコアオブジェクトのリスト、または {"scores": [...]} 形式のオブジェクト。

スコアオブジェクトには次のフィールドがあります。

フィールド	必須	説明
`value`	はい	タグ (36 文字以内の string) または評価 (`0.0` から `1.0` までの数値)。
`reason`	いいえ	スコアの理由を説明する string。
`confidence`	いいえ	`0.0` から `1.0` までの数値。

Weave は、200 以外の応答をすべて Scorer の失敗として扱い、その試行のフィードバックは記録しません。また、リダイレクトには従わず、失敗として扱います。エラー応答の本文は解析されません。エンドポイントが受け付けることのないリクエストには 4xx を、一時的な問題には 5xx を返してください。エージェントのターンのリクエストでは、応答の schema_version は 2 になります。次の例は、スコアオブジェクトを 1 つ返します。

{
  "schema_version": 2,
  "result": {
    "value": "concise",
    "reason": "72 characters.",
    "confidence": 0.9
  }
}

Weave は、結果に含まれるタグと理由を正規化してから保存します。詳しくは、Weave がスコアを正規化する方法を参照してください。

Weave からのリクエストを認証する

Weave は Bearer token を使用してエンドポイントに対して認証を行います。リクエストには W&B の認証情報は含まれません。このトークンは、リクエストが Weave から送信されたものであることをエンドポイント側に証明するためのものです。逆方向の証明には使用されません。各 RemoteScorer は、次の 2 つのモードのいずれかを使用します。

モード	Weave の動作	設定する項目
`oauth_client_credentials`	クライアントクレデンシャルグラントを使用して OAuth トークンエンドポイントにトークンをリクエストします。その際、クライアント ID とシークレットを HTTP Basic 認証 (`client_secret_basic`) で送信します。その後、取得したトークンを Scorer エンドポイントに送信します。	トークンエンドポイントの URL、クライアント ID、クライアントシークレットを保持するシークレットの名前、およびスコープ (オプション)。
`static_bearer`	固定のトークンを Scorer エンドポイントに送信します。	トークンを保持するシークレットの名前。

Scorer を登録する前に、project を所有するチームのシークレットストアにクライアントシークレットまたは Bearer token を保存してください。RemoteScorer の設定に保持されるのはシークレット名のみです。実際の値は、スコアリングワーカーがスコアリング時に解決します。

リモート Scorer シグナルを作成する

シグナルは Weave UI または Python SDK で作成できます。どちらの方法でも、weave.genai.turn_ended を対象とするモニターに関連付けられた RemoteScorer が作成されます。

Weave UI

Agents ビューからシグナルを作成します。

Weave プロジェクトのサイドバーで、Agents をクリックします。
タブバーで Signals をクリックします。
New signal をクリックし、続いて Remote scorer をクリックします。
Remote scorer ドロワーでは、Scored by が Remote scorer に設定されています。次のフィールドを設定します。
- Scorer name: Signals 表の Scorer 列に表示される名前です。最大 128 文字まで指定できます。
- Scoring endpoint URL: Weave が POST リクエストを送信する URL です。
- Authentication: Static bearer または OAuth client credentials を選択します。Static bearer の場合は、Bearer token secret name を選択または入力します。OAuth の場合は、Token endpoint URL、Client ID、Client secret name、および必要に応じて Scope を入力します。シークレット関連のフィールドには、シークレットの値ではなく、チームのシークレット名を指定します。
- Config (JSON, optional): scorer.config としてエンドポイントに渡される JSON オブジェクトです。
- Only score turns matching (オプション): Advanced を展開してフィルターを追加し、シグナルによるスコア付けの対象となるターンを絞り込みます。エージェント名、エージェントのバージョン、操作名、ツール名、ステータスコードなどで絞り込めます。すべてのターンをスコア付けする場合は、空欄のままにします。複数のフィルターを指定すると、AND 条件で組み合わされます。
- Sample rate (オプション): Advanced を展開し、条件に一致するターンのうち、シグナルがスコア付けする割合を設定します。
Create signal をクリックします。

リモート Scorer のフォームには、タグや評価のフィールドはありません。返す内容はエンドポイント側で決まり、Signals 表にはエンドポイントから受け取ったタグと評価が表示されます。Scorer 列では、リモート Scorer のシグナルに webhook アイコンが表示されます。

Python SDK

RemoteScorer をパブリッシュしてから、Monitor を有効化します。この Monitor では、scorers にパブリッシュした Scorer を指定し、op_names で weave.genai.turn_ended を対象に設定します。

import weave
from weave.flow.monitor import Monitor
from weave.scorers.remote_scorer import RemoteScorer, StaticBearerAuthConfig

weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")

scorer = RemoteScorer(
    name="policy_remote_scorer",
    endpoint_url="https://scoring.example.com/weave/score",
    config={"threshold": 0.9},  # scorer.config としてエンドポイントに送信されます
    auth_config=StaticBearerAuthConfig(
        mode="static_bearer",
        bearer_secret_name="WEAVE_REMOTE_SCORER_BEARER_TOKEN",
    ),
)
weave.publish(scorer, name="policy_remote_scorer")

monitor = Monitor(
    name="policy_remote_signal",
    scorers=[scorer],
    op_names=["weave.genai.turn_ended"],  # 完了したエージェントのターンをスコアリングします
    sampling_rate=1.0,
)
monitor.activate()

OAuth クライアント認証情報を使用する場合は、代わりに OAuthClientCredentialsConfig を auth_config に渡します。

サンプルコード

weave リポジトリの examples/remote_scorer ディレクトリは、このコントラクトのリファレンス実装であり、サンプルコードの正式なソースです。このサンプルでは、1 つのエンドポイントで V1 Call リクエスト、V2 Call リクエスト、V2 エージェントターンリクエストを受け入れます。エージェントターンでは、次のファイルを使用します。

remote_scorer_app.py: GET /health と POST /score を備えた FastAPI アプリです。
auth.py: REMOTE_SCORER_DEV_BEARER_TOKEN 環境変数と照合する、開発専用の Bearer token チェックです。
scoring_logic.py: extract_scoring_target でどちらかの範囲をアンラップし、ターンの最後の出力メッセージをスコアリングします。
sample_request_v2_agent_turn.json: V2 エージェントターンリクエストの完全な例です。
register_remote_scorer.py --agent-turn: RemoteScorer をパブリッシュし、完了したエージェントターンを対象とするモニターを有効化します。
trigger_test_agent_turn.py: weave.conversation.log_turn を使用して 1 つのターンをログします。

Weave を使わずにエンドポイントをローカルで実行し、V2 エージェントターンリクエストを送信するには、アプリを起動してからサンプルリクエストを送信します。

python3 -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt
export REMOTE_SCORER_DEV_BEARER_TOKEN="dev-token"
uvicorn remote_scorer_app:app --host 127.0.0.1 --port 8000

curl -sS http://127.0.0.1:8000/score \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-contract-check" \
  -H "X-Correlation-ID: local-contract-check" \
  -H "X-Weave-Schema-Version: 2" \
  --data @sample_request_v2_agent_turn.json

このサンプルには Weave 0.53.0 以降が必要です。ローカルで実行した場合に検証されるのは、コントラクトのみです。

シグナルをテストする

テストの前に、許可されたホストに含まれる HTTPS URL でエンドポイントをデプロイし、登録してください。完了したターンを 1 つログしてから、Signals タブを確認します。スコアリングは非同期で実行されるため、結果が表示されるまでにしばらく時間がかかります。

import uuid

from opentelemetry import trace

import weave
from weave.conversation import Message, log_turn

weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")

result = log_turn(
    conversation_id=f"sample-{uuid.uuid4().hex}",
    agent_name="sample-support-agent",
    system_instructions=["Answer the user accurately and concisely."],
    messages=[Message.user("What are your support hours?")],
    output_messages=[
        Message.assistant(
            "Our support team is available Monday through Friday, 9am to 5pm Eastern."
        )
    ],
)

# weave.init はバックグラウンドスレッドからスパンをエクスポートします。短いスクリプトでは、終了前にフラッシュしてください。
trace.get_tracer_provider().force_flush(30_000)
print(result.conversation_id, result.trace_ids)

エンドポイントは、scoring_target.type が agent_turn に設定された V2 リクエストを受信します。Weave はその結果を、該当するターンのフィードバックとして記録します。

トラブルシューティング

症状	確認事項
New signal ドロワーに Remote scorer が表示されない	所有元の組織の Remote scoring 設定、またはデプロイメントの管理者によって、リモートスコアリングが有効になっているか確認します。
エンドポイント URL が拒否される	Scorer のホスト (OAuth の場合はトークンエンドポイントのホストも) が許可ホストに含まれているか確認します。また、ポートの不一致、HTTPS 以外の URL、プライベートアドレスや内部アドレスの使用がないかも確認してください。
エンドポイントが `401` または `403` を返す	シークレット名、OAuth クライアントの認証情報・オーディエンス・スコープ、およびエンドポイント側のトークン検証を確認します。
エージェントのターンに対してエンドポイントが `400` を返す	エンドポイントが範囲のバージョンをチェックしており、ペイロードバージョン `1` の `scoring_target.type` `agent_turn` を受け入れるか確認します。
Signals タブに結果が表示されない	スコアリングは非同期で実行されます。ターンがシグナルのフィルターとサンプリング率の条件を満たしていること、およびターンのルートスパンが終了していることを確認してください。
ターンはシグナルに一致したが、タグや評価が表示されない	スコアリングの試行が失敗した場合、Weave は何も記録しません。エンドポイントのリクエストログで `X-Correlation-ID` ヘッダーを確認してください。エンドポイントがリクエストを受信していない場合は、URL が許可ホストのルールを満たしていないか、シークレットを解決できなかった可能性があります。リクエストを受信している場合は、応答が検証に失敗しています。
`200` 応答が返されたのに結果が表示されない	応答の `schema_version` が `2` であり、`result` が 3 つの構造化形式のいずれかになっているか確認します。

​エージェントのターンのスコアリングの仕組み

​リモートスコアリングを有効にする

​scorer エンドポイントを構築する

​リクエスト

​応答

​Weave からのリクエストを認証する

​リモート Scorer シグナルを作成する

​Weave UI

​Python SDK

​サンプルコード

​シグナルをテストする

​トラブルシューティング