> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入评委

本页说明如何在 Benchmark 的 `evaluate()` 中接入 LLM 评委或 Agentic 评委。用户侧的参数和行为见[评委总览](https://agent-compass.mintlify.site/zh/user_guide/other_features/judges/overview.md)；本页只讲实现约定。

## 选择评委类型

| 评分需要 | 评委类型 | 评测模式 |
| - | - | - |
| 只比较文本答案，或按评分标准给文本打分 | LLM 评委 | `none` |
| 评委要打开、渲染或执行交付物文件 | Agentic 评委 | `fresh`（推荐）或 `reuse` |

能用 LLM 评委就不要用 Agentic 评委：后者每题需要多次完整 agent 运行，成本和耗时高一个数量级，结果也更难复现。评测模式的生命周期见[评测模式与产物](https://agent-compass.mintlify.site/zh/developer_guide/extensions/benchmark/code_implementation/evaluation_modes.md)。

## 通用约定

* **通过配置 mixin 声明评委参数。** 不要在 Benchmark 配置中自己定义 `judge_model` 等字段，使用 `LLMJudgeConfig` 或 `AgentJudgeConfig`，所有 Benchmark 的参数名、校验和 `${ENV}` 解析就会保持一致。
* **显式配置评委。** 不要默认让被测 Model 给自己评分。`judge_model_spec(req)` 会把缺少的连接字段回退到被测 Model，这只是为了方便试跑；Benchmark 页面应要求用户提供完整、独立的评委配置。
* **区分评委失败与答错。** 评委请求失败、超时或输出无法解析时，返回 FATAL issue（`judge_failed`，输出结构不对时可用 `judge_invalid_output`），不要写入 0 分。分级规则见[结果与聚合](https://agent-compass.mintlify.site/zh/developer_guide/extensions/benchmark/code_implementation/results_and_aggregation.md)。
* **保留判定依据。** 把评委的判定、理由和必要的诊断信息写进结果，方便用户核查单题分数。
* **在 Benchmark 页面写明评委。** 写清评委职责、判定格式、推荐的评委 Model 和修改过的默认值，并链接到通用评委页面，不要重复通用参数说明。

## LLM 评委

### 声明配置

把 `LLMJudgeConfig` 放在配置类基类列表的第一位，并在 `__post_init__` 中调用 `LLMJudgeConfig.__post_init__(self)`，它会先运行基类配置的 `__post_init__`：

```python theme={"system"}
from dataclasses import dataclass

from agentcompass.benchmarks.config import LLMJudgeConfig, RuntimeBenchmarkConfig


@dataclass(slots=True)
class ExampleConfig(LLMJudgeConfig, RuntimeBenchmarkConfig):

    def __post_init__(self) -> None:
        LLMJudgeConfig.__post_init__(self)
```

`LLMJudgeConfig` 提供：

| 成员 | 说明 |
| - | - |
| `judge_model` | 评委 Model 配置。`${ENV}` 引用会被解析，`id` 会被校验。 |
| `judge_model_required` | 类变量，默认 `True`，缺少 `judge_model` 时配置直接报错。只有部分任务或部分运行需要评委时设为 `False`，并在实际判分处检查。 |
| `judge_concurrency` | 默认 `1`。评测单个任务时，runtime 最多允许这么多个 `generate_text` / `generate_with_metadata` 调用同时进行，scorer 不需要自己的信号量。单个任务会请求很多次评委时，重新声明该字段并提高默认值。 |
| `judge_model_spec(req)` | 返回评委的 `ModelSpec`，缺少的连接字段取自被测 Model。 |
| `judge_modalities` | 类变量，默认 `("text",)`：评委 Model 接收的模态，在接入 Benchmark 时确定。 |
| `judge_requirements(req)` | 返回 runner 在推理前探测的评委 Model，每个都是带有所需模态的 `ModelRequirement`；没有 `judge_model` 时为空。评委还用到其他 Model 时重写它。 |

无需自己设置输出上限：调用和 `judge_model.params` 都没有设置时，`generate_text` 和 `generate_with_metadata` 会补上 `max_tokens` `32768`（见[默认 `max_tokens`](https://agent-compass.mintlify.site/zh/user_guide/other_features/judges/llm_judge#默认-max_tokens)）。只有 Benchmark 需要其他上限时才在调用时传入 `max_tokens`，`judge_model.params` 仍会覆盖它。

### 使用内置 scorer

只需比较最终答案时，使用 `LLMJudgeScorer` 和 `evaluate_binary_scorer`。后者负责调用 scorer、校验 `correct` 字段，并把异常映射成 FATAL `judge_failed`：

```python theme={"system"}
from agentcompass.benchmarks.utils.scorers import LLMJudgeScorer
from agentcompass.benchmarks.utils.scorers.base import evaluate_binary_scorer


class ExampleBenchmark(BaseBenchmark):
    evaluation_environment_mode = "none"

    def __init__(self) -> None:
        self._scorer = LLMJudgeScorer()

    async def evaluate(self, task, prepared, result, req, plan, env=None):
        config = self.build_config(req)
        return await evaluate_binary_scorer(
            self._scorer,
            prepared,
            result,
            task_metadata={
                "question": task.question,
                "judge_model": config.judge_model,
                "model_spec": req.model,
            },
        )
```

默认 prompt 是 A/B/C 协议，只有 `A` 计为正确。需要自己的判定规则时，向 `LLMJudgeScorer` 传入 `prompt_template` 和 `response_parser`：模板可使用 `{question}`、`{gold_answer}` 和 `{llm_response}` 三个占位符；解析函数接收评委回复文本、返回 `bool`，无法解析时应抛出异常，不要返回 `False`。

### 自定义评分流程

评分标准、多次采样或多阶段评分无法套用二元 scorer 时，直接调用 `generate_text` 或 `generate_with_metadata`：

```python theme={"system"}
from agentcompass.runtime.llm import generate_text

judge = config.judge_model_spec(req)
reply = await generate_text(judge, messages)
```

* `judge_model.params` 中的 `timeout` 和 `max_retries` 由客户端处理，其余键随请求发送，无需在 scorer 中另外实现超时和重试。
* 用 `asyncio.gather` 并发请求时，runtime 已按 `judge_concurrency` 限流。
* 需要区分截断和正常短回复时，使用 `generate_with_metadata` 并检查 `stop_reason == "length"`。

可参考 ResearchRubrics（逐条评分标准）和 DeepResearch Bench（多阶段评分）的实现。

## Agentic 评委

[`AgentJudgeScorer`](https://github.com/open-compass/AgentCompass/blob/main/src/agentcompass/benchmarks/utils/scorers/agent.py) 在评测 Environment 中启动评委 Harness，负责组装评委请求、切分窗口、并发运行、重判、时限和 `media-inspect`。与 `LLMJudgeScorer` 一样，Benchmark 只提供 prompt 和解析函数。

### 声明配置

`AgentJudgeConfig` 是一个 `LLMJudgeConfig`，一次性提供 `judge_harness`、`judge_harness_params` 和全部 `judge_agent_*` 参数，并统一校验：

```python theme={"system"}
from dataclasses import dataclass
from typing import ClassVar

from agentcompass.benchmarks.config import RuntimeBenchmarkConfig, config_field
from agentcompass.benchmarks.utils.scorers import AgentJudgeConfig
from agentcompass.runtime.modality import MODALITIES


@dataclass(slots=True)
class ExampleConfig(AgentJudgeConfig, RuntimeBenchmarkConfig):
    judge_model_required: ClassVar[bool] = False
    # 评委检查文本、图片、音频和视频
    judge_modalities: ClassVar[tuple[str, ...]] = MODALITIES

    # 需要不同默认值时重新声明字段
    judge_agent_rubric_window: int = config_field(default=16, description="Rubric items judged per judge run.")

    def __post_init__(self) -> None:
        AgentJudgeConfig.__post_init__(self)
```

| 成员 | 说明 |
| - | - |
| `agent_judge_settings()` | 根据参数构造 `AgentJudgeSettings`。 |
| `judge_modalities` | 评委检查的模态，取自 `text`、`image`、`audio`、`video`，没有对应的用户参数。文本和图片经评委 Harness 交给评委 Model，该 Harness 必须支持它们，并会被设置看图参数，`judge_harness_params` 不能与之矛盾；`judge_requirements(req)` 会构建评委请求，因此这两点都在 preflight 中检查。音频和视频经过 `media-inspect`，此时配置要求提供 `judge_agent_media`。 |
| `judge_requirements(req)` | 返回带 `text`、`image` 模态的评委 Model，以及 `media-inspect` 使用的 Model（`judge_agent_media.model`，未设置时为评委 Model），后者带 `text`、`audio`，检查视频时还带用于抽帧回退的 `image`。 |
| `default_judge_harness_params` | 按 Harness ID 给出的评委 Harness 参数，优先级最低：同类型推理 Harness 的参数和 `judge_harness_params` 会按参数覆盖它。默认只有 `openclaw`：`setup_capsule_tag` 为 `node24-v1`，`version` 为 `2026.5.7`，`max_output_tokens` 为 `32768`。需要为某个 Benchmark 修改时重新声明它。 |
| `evaluation_call_limit()` | 返回 `None`：评委运行的并发由 `judge_agent_concurrency` 控制，不再受 `judge_concurrency` 限制。 |

### 预检评委

不要自己探测评委。推理开始前，runner 会从运行 AgentCompass 的机器探测配置的 `judge_requirements(req)` 返回的每个 Model，任何失败（包括端点不可达）都会终止运行，见[模态预检](https://agent-compass.mintlify.site/zh/user_guide/modules/benchmarks/overview.md#modality-preflight)。

### 判分

```python theme={"system"}
import functools

from agentcompass.benchmarks.utils.scorers import (AgentJudgeScorer, JudgeUnit, evaluation_deadline,
                                                   remaining_budget)
from agentcompass.runtime.timeouts import call_with_timeout


async def evaluate(self, task, prepared, result, req, plan, env=None):
    config = self.build_config(req)
    deadline = evaluation_deadline(plan.evaluation_timeout_seconds)
    eval_root = f"/tmp/example_judge_{task.task_id}"

    def build_unit(attempt, index, batch):
        workspace = f"{eval_root}/judge/pass{attempt}_window{index}"
        judgment_path = f"{workspace}/judgment.json"
        prompt = build_prompt(batch, judgment_path, media_rules=scorer.media_instructions())
        return JudgeUnit(unit_id=f"{task.task_id}__judge_{attempt}_{index}",
                         prompt=prompt,
                         workspace=workspace,
                         judgment_path=judgment_path)

    scorer = AgentJudgeScorer(
        config.agent_judge_settings(),
        item_id=lambda item: item["id"],
        build_unit=build_unit,
        parse=parse_window,                          # (outcome, batch) -> {item_id: 判定或失败标记}
        is_judged=lambda verdict: verdict["passed"] is not None,
        window=config.judge_agent_rubric_window,     # 每次评委运行的条目数；0 = 全部条目
        max_retries=config.judge_agent_max_retries,  # 在新会话中重判未判定的条目
    )
    verdicts, passes = await call_with_timeout(
        functools.partial(scorer.score, env, req, plan, rubric, deadline=deadline),
        timeout=remaining_budget(deadline),
        phase="example judging",
    )
```

* **`build_unit(attempt, index, batch)`** 为一个窗口返回 `JudgeUnit`：prompt、评委工作目录和 judgment 文件路径。每个窗口使用独立的目录，重判轮次也不要复用目录。
* **`parse(outcome, batch)`** 把 `JudgeUnitOutcome` 解析为 `{item_id: verdict}`。`outcome.judgment_text` 为空、`outcome.error` 非空或判定缺项时，为对应条目返回失败标记（如 `{"passed": None, "error": ...}`），不要抛异常；`outcome.failure_reason()` 给出失败原因。
* **`is_judged(verdict)`** 区分有效判定和失败标记。未判定的条目会在下一轮重判；最终仍未判定的条目保留第一次的失败标记。
* **时限。** 在 `evaluate()` 开头调用 `evaluation_deadline()`，它比 runtime 的评测超时提前一段余量。把它传给 `scorer.score(..., deadline=deadline)`，每次评委运行都会截断到剩余预算；再用 `call_with_timeout(..., timeout=remaining_budget(deadline))` 包住整个评委步骤兜底；它抛出的 `TimeoutError` 应转换为 `judge_failed`。`call_with_timeout` 只转发位置参数，关键字参数请用 `functools.partial` 绑定。
* **媒体。** 在 prompt 中加入 `scorer.media_instructions()`：它说明 `media-inspect` 的用法，没有配置 `media-inspect` 时返回空字符串。按评委固定的模态只写一版 prompt，不要再写纯文本或无音频的变体。`media-inspect` 无法安装到评测 Environment 时，`scorer.score()` 会抛出异常，该任务的判分失败。`scorer.media_summary()` 返回 `ffmpeg` 是否可用和调用统计，可写入结果用于诊断。
* **安装。** `fresh` Environment 中没有推理阶段安装的内容，因此评委参数没有显式设置 `install_strategy` 时，`preinstalled` 的评委 Harness 会退回 `install_if_missing`。

### 汇总结果

* 任一条目最终仍未判定时，整个任务返回 FATAL `judge_failed`，不给分。
* 交付物缺失是正常结果，应在 prompt 中要求评委把依赖它的条目判为不通过，而不是记为评委失败。
* 为每次评委运行保存一条记录（窗口名、覆盖的条目、错误，以及 `outcome.diagnostics()`），例如 AA-Briefcase-Lite-AC 的 `judge_windows`。需要保留评委 agent 的对话记录时，加入 `outcome.transcript()`：每步一条，包含文本、推理、工具调用和工具输出，内嵌的 base64 媒体替换为其大小。

### 隔离被测身份

成对比较或有参考答案时，用中性的标签和路径呈现证据，不要在 prompt、文件名或目录名中透露哪一侧是被测 Model。GDPval-AC 用 A/B 标签呈现被测产物和固定基线。

## 参考实现

| Benchmark | 说明 |
| - | - |
| BrowseComp、GAIA、HLE | `LLMJudgeScorer` + 内置 A/B/C 协议。 |
| SealQA、xbench-DeepSearch | 自定义 LLM scorer。 |
| ResearchRubrics | 逐条评分标准请求评委，并重新声明 `judge_concurrency`。 |
| DeepResearch Bench | 多阶段评分，多个评委角色。 |
| AA-Briefcase-Lite-AC | Agentic 评委，`fresh` 评测，二元评分项。 |
| GDPval-AC | Agentic 评委，成对比较固定基线，工作区快照支持只重判。 |

## 提交前检查

* 缺少 `judge_model` 时报错清楚，并在推理前暴露（`judge_model_required` 或预检）。
* 评委失败、无法解析和超时都返回 FATAL issue，没有被记为 0 分。
* 用本地测试验证解析函数在空回复、格式错误和缺项时的行为（测试文件放在不提交的根目录 `tests/` 下）。
* 配置设置了 `judge_modalities`，runner 的预检通过 `judge_requirements(req)` 覆盖每个评委 Model，`evaluate()` 使用 `evaluation_deadline()`。
* Benchmark 页面写明评委职责、推荐评委和修改过的默认值，并链接到[评委总览](https://agent-compass.mintlify.site/zh/user_guide/other_features/judges/overview.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.