> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiments: 用运行矩阵比较 agents 和 models

> 使用 niceeval experiments 让同一批 eval 横跨多个 agents、models 和 feature flags，比较 pass rate、成本和延迟。

Experiment 用于比较多组运行配置。典型问题包括：Claude Code 和 Codex 谁在同一批 fixture 上 pass rate 更高？某个 prompt 改动是否降低成本？不同模型的延迟和质量如何取舍？

## 基本形状

**一个实验文件 = 一个配置**（一个 agent × 一个 model）。`model` 是单个字符串，不接受数组。要跨模型 / 跨 agent 对比，就在一个**实验组文件夹**里写多个文件，各钉对照轴之外的一切：

```text theme={null}
experiments/
  compare-models/          # 实验组
    gpt-4o-mini.ts         #   一格:钉 model = gpt-4o-mini
    gpt-4o.ts              #   一格:钉 model = gpt-4o
```

```ts theme={null}
// experiments/compare-models/gpt-4o.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../../agents/web-agent.ts";

export default defineExperiment({
  description: "AI 助手:gpt-4o",
  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
  model: "gpt-4o",   // 单个字符串;另一个模型就复制一份文件改这一行
  runs: 3,
});
```

```bash theme={null}
npx niceeval exp compare-models   # 把同组各 model 并排出报告
```

这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。

## 适合比较什么

* 不同 agent adapters。
* 不同模型。
* 不同 prompts 或 feature flags。
* 不同 sandbox 后端。
* 同一任务的 pass\@N。

## 查看结果

Experiment 输出通常按 `(agent, model, eval)` 维度展示：

```text theme={null}
fixtures/button   claude-code   pass@5 = 4/5 (80%)   mean 34s
fixtures/button   codex         pass@5 = 3/5 (60%)   mean 41s
```

除了 pass rate，还应该看平均耗时、token、成本和失败类型。

## 设计 experiment 的建议

* 保持 eval 集合稳定，避免比较时混入新变量。
* 每个 cell 跑多个 attempts，尤其是非确定性 coding agent。
* 把预算和并发写清楚。
* 对“失败原因”做归类，不只看总分。

## 与普通运行的关系

`npx niceeval exp <实验>` 关注“这一批 eval 在某个配置下是否通过”；实验组关注“多组配置谁更好”。两者使用同一套 eval、agent adapter、scoring 和 artifacts。