> ## 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.

# 写实验：用 defineExperiment 固定运行配置

> 学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。

Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、哪些 feature flags、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 agent 或运行配置。

## 最小实验

```ts theme={null}
// experiments/local.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../agents/web-agent.ts";

export default defineExperiment({
  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
});
```

`agent` 放的是已经配置好的 agent 实例。被测系统的 URL、鉴权、协议细节通常传给 adapter 工厂；运行器不会单独保存一个 `agentConfig` 字段。

## 传 model 和 flags

```ts theme={null}
// experiments/concise.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../agents/web-agent.ts";

export default defineExperiment({
  description: "简洁 prompt 变体",
  agent: webAgent({
    baseUrl: "https://staging.example.com",
    apiKey: process.env.STAGING_AGENT_API_KEY,
  }),
  model: "gpt-5.4",
  flags: {
    promptVariant: "concise",
    webResearch: false,
  },
  runs: 3,
  earlyExit: true,
  budget: 5,
});
```

`model` 会作为 `ctx.model` 传给 adapter；应用接口支持模型选择时，adapter 把它放进请求体、header 或 CLI 参数即可。

`flags` 会作为 `ctx.flags` 传给 adapter，也会作为 `t.flags` 出现在 eval 里。它适合表达 experiment 维度的 feature 开关，例如 prompt 版本、工具集、检索开关。真正按 flag 切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。

```ts theme={null}
// agents/web-agent.ts
async send(input, ctx) {
  await fetch(`${baseUrl}/api/turn`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      message: input.text,
      model: ctx.model,
      flags: ctx.flags,
    }),
    signal: ctx.signal,
  });
}
```

## 一组实验怎么写

一个实验文件是一格配置。要比较多个模型、agent 或 flags，就把多个文件放进同一个文件夹：

```text theme={null}
experiments/
  prompt-variants/
    baseline.ts
    concise.ts
    with-retrieval.ts
```

```bash theme={null}
npx niceeval exp prompt-variants
```

这样报告会按同一组展示，差异也能在 Git 里 review。

## 常用字段

| 字段                | 用途                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------ |
| `agent`           | 选择并配置 adapter；必填                                                                     |
| `model`           | 单个模型名，经 `ctx.model` 透传                                                               |
| `reasoningEffort` | 单个推理努力程度（如 `"high"`），经 `ctx.reasoningEffort` / `t.reasoningEffort` 透传，归属与 `model` 一致 |
| `flags`           | 任意 JSON 对象，经 `ctx.flags` / `t.flags` 透传                                              |
| `runs`            | 每个 eval × 配置最多跑几次                                                                    |
| `earlyExit`       | 多次运行里通过一次就提前停止                                                                       |
| `evals`           | 限定这一格配置跑哪些 eval                                                                      |
| `timeoutMs`       | 单个 attempt 的超时                                                                       |
| `budget`          | 这一格配置的预算上限                                                                           |
| `maxConcurrency`  | 这一格配置的并发上限                                                                           |
| `sandbox`         | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()`                             |

跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/concepts/adapter)。