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

# 为你的 Agent 项目设置评估

> 安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条评估用例。

接入应用需要三个文件：一个 **Adapter** 负责调用应用，一个 **Experiment** 固定被测对象和运行次数，一条**评估用例**定义断言。以下步骤提供完整的最短路径，并分别覆盖 Coding Agent 自动接入和人工接入。

## 使用 Coding Agent 接入（推荐）

<Steps>
  <Step title="安装">
    ```text theme={null}
    READ https://niceeval.com/INIT.md and install niceeval for this repo.

    ```
  </Step>

  <Step title="运行测试">
    ```bash theme={null}
    pnpm exec niceeval exp 实验名
    ```
  </Step>

  <Step title="查看结果">
    ```bash theme={null}
    pnpm exec niceeval show         # 终端摘要，适合 Coding Agent 读取
    pnpm exec niceeval view         # 网页查看器，适合人浏览证据
    ```
  </Step>
</Steps>

## 人工接入

```bash theme={null}
pnpm add -D niceeval
pnpm exec niceeval init
```

### Adapter

Adapter 连接 Agent 与 [NiceEval](https://niceeval.com/)。三种接入等级从无侵入连接到修改 Agent 配置，分别提供不同的评估能力，见 [Tier](/docs/zh/explanation/tier)。

```ts theme={null}
// agents/my-agent.ts
import { defineAgent } from "niceeval/adapter";

export default defineAgent({
  name: "my-agent",
  async send(input, ctx) {
    // 示例地址：换成你自己 agent 的真实端点（HTTP、CLI、SDK 都行，只要 send 里能拿到回复文本）
    const r = await fetch("http://localhost:3000/chat", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ message: input.text, model: ctx.model }), // ← experiment.model 经 ctx.model 到这里
      signal: ctx.signal,
    });
    const body = await r.json();
    return {
      status: r.ok ? "completed" : "failed",
      events: [{ type: "message", role: "assistant", text: body.reply }],
    };
  },
});
```

### Experiment

```ts theme={null}
// experiments/my-agent.ts
import { defineExperiment } from "niceeval";
import myAgent from "../agents/my-agent.ts";

export default defineExperiment({
  description: "my-agent 基线",
  model: "gpt-4o",
  agent: myAgent,
  runs: 1,
});
```

### 评估用例

```ts theme={null}
// evals/refund-policy.eval.ts
import { defineEval } from "niceeval";
import { includes } from "niceeval/expect";

export default defineEval({
  description: "退款政策问答",
  async test(t) {
    await t.send("你们的退款政策是什么?");
    t.succeeded();
    t.check(t.reply, includes("30 天"));
  },
});
```

```bash theme={null}
pnpm exec niceeval exp my-agent   # 跑起来
pnpm exec niceeval show         # 在终端读结果；失败项会给出继续下钻的命令
pnpm exec niceeval view         # 需要交互浏览时打开本地查看器
```

到这里第一条评估用例已经跑通。

这个最小 Adapter 只支持**单轮**调用，第二轮不会携带第一轮的历史。多轮会话、工具调用事件（供 `t.calledTool()` 使用）、HITL 和 tracing 都是后续可选能力。按[接入你的 Agent](/docs/zh/tutorials/connect-your-agent)继续扩展时，已有评估用例不需要修改。

## 对照完整项目

第一条评估用例跑通后，再到 [Examples](/docs/zh/examples) 按被测对象选择完整项目。那里提供可运行源码；通用操作步骤在 Tutorials 的对应任务页中。

## 放进 CI

```yaml theme={null}
name: evals
on: [pull_request]
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm exec niceeval exp my-agent
```

<Tip>
  阅读 [编写评估用例](/docs/zh/tutorials/authoring) 和 [评分指南](/docs/zh/tutorials/scoring-guide)，再把示例替换成真实场景。
</Tip>