> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# リモート Scorer でエージェントのターンをスコアリングする
> 独自の HTTP エンドポイントを使用して W&B Weave のエージェントのターンをスコアリングし、結果をシグナル タブでタグまたは評価として確認します。
export const GitHubLink = ({url, compact = false}) =>
{compact ? "View source" : <>
GitHub source
}
;
リモート Scorer シグナルは、LLM ジャッジモデルの代わりに、お客様がホストする HTTP エンドポイントを使用して、完了したエージェントのターンをそれぞれスコアリングします。ターンが終了すると、W\&B Weave のエージェントスコアリングワーカーがそのターンを HTTP `POST` でお客様のエンドポイントに送信し、応答をそのターンのフィードバックとして記録します。結果は、[Agents ビュー](/ja/products/wandb/weave/guides/tracking/view-agent-signals)の **Signals** タブにタグまたは評価として表示されます。
このページでは、エージェントのターンを対象とするリモート Scorer について説明します。`@weave.op` でトレースした Call をスコアリングする場合は、[リモート Scorer で Call をスコアリングする](/ja/products/wandb/weave/guides/evaluation/remote-scorers)を参照してください。リモート Scorer は Python SDK または Weave UI で設定します。TypeScript SDK には `RemoteScorer` は含まれていません。
エージェントのターンのスコアリングの仕組み
エージェントのターンは、次の順序でスコアリングされます。
1. ターンが終了します。ルートスパン (親を持たないスパン) が終了すると、Weave はそれを完了したターンとして扱い、`weave.genai.turn_ended` イベントを発行します。
2. エージェントスコアリングワーカーが、project 内で `weave.genai.turn_ended` を対象とする実行中のシグナルを読み込み、各シグナルのフィルターとサンプリング率を適用します。
3. 条件に一致したシグナルの各 `RemoteScorer` について、ワーカーはターンのスパンからメッセージを含む `schema_version: 2` リクエストを構築し、Scorer の認証情報を解決して、エンドポイント URL を許可されたホストと照合したうえで `POST` を送信します。
4. ワーカーは応答を検証し、その結果をターンのフィードバックとして書き込みます。タグと評価は **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 を有効にするには、組織の管理者または請求管理者が次の手順を実行する必要があります。
1. `https://wandb.ai/account-settings/[ORG]/settings` を開きます。`[ORG]` は、ご利用の project を所有する組織に置き換えてください。
2. **Remote scoring** タブを選択します。
3. **Enable remote scoring** をオンにします。
4. **Allowed hosts** で **Add host** をクリックし、リモート Scorer の呼び出し先となるホストをそれぞれ入力します。リモートスコアリングを有効にした状態で保存するには、ホストを 1 つ以上指定する必要があります。そのホストのすべてのポートを許可する場合は、ポートを空欄のままにします。
5. **Save settings** をクリックします。
**専用クラウド**
デプロイメントでのリモートスコアリングの有効化と、許可するホストの設定を W\&B に依頼してください。
**セルフマネージド**
W\&B Weave を [W\&B Self-Managed](/ja/products/wandb/platform/hosting/hosting-options/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 形式でスコアを返します。リファレンス実装については、[サンプルコード](#sample-code)を参照してください。
リクエスト
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 エンコードした文字列になります。
```json lines theme={"system"}
{
"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 つ返します。
```json lines theme={"system"}
{
"schema_version": 2,
"result": {
"value": "concise",
"reason": "72 characters.",
"confidence": 0.9
}
}
```
Weave は、結果に含まれるタグと理由を正規化してから保存します。詳しくは、[Weave がスコアを正規化する方法](/ja/products/wandb/weave/guides/tracking/view-agent-signals#how-weave-normalizes-scores)を参照してください。
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 ビューからシグナルを作成します。
1. Weave プロジェクトのサイドバーで、**Agents** をクリックします。
2. タブバーで **Signals** をクリックします。
3. **New signal** をクリックし、続いて **Remote scorer** をクリックします。
4. **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** を展開し、条件に一致するターンのうち、シグナルがスコア付けする割合を設定します。
5. **Create signal** をクリックします。
リモート Scorer のフォームには、タグや評価のフィールドはありません。返す内容はエンドポイント側で決まり、Signals 表にはエンドポイントから受け取ったタグと評価が表示されます。**Scorer** 列では、リモート Scorer のシグナルに webhook アイコンが表示されます。
Python SDK
`RemoteScorer` をパブリッシュしてから、`Monitor` を有効化します。この `Monitor` では、`scorers` にパブリッシュした Scorer を指定し、`op_names` で `weave.genai.turn_ended` を対象に設定します。
```python lines theme={"system"}
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` に渡します。
サンプルコード
シグナルをテストする
テストの前に、許可されたホストに含まれる HTTPS URL でエンドポイントをデプロイし、登録してください。
完了したターンを 1 つログしてから、**Signals** タブを確認します。スコアリングは非同期で実行されるため、結果が表示されるまでにしばらく時間がかかります。
```python lines theme={"system"}
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 つの構造化形式のいずれかになっているか確認します。 |