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

# Sandbox agents: 评估 Claude Code、Codex 和 bub

> 使用 niceeval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。

Sandbox agent 会在隔离环境中启动 coding-agent CLI，给它 workspace 和任务，让它自由修改文件、运行命令，然后收集 transcript、diff 和测试结果。

## 内置 sandbox agents

<CardGroup cols={3}>
  <Card title="claude-code" icon="code">
    运行 Anthropic Claude Code CLI，需要 `ANTHROPIC_API_KEY`。
  </Card>

  <Card title="codex" icon="terminal">
    运行 OpenAI Codex CLI，需要 `OPENAI_API_KEY`。
  </Card>

  <Card title="bub" icon="robot">
    运行 bub coding agent，鉴权遵循 bub CLI 自身约定。
  </Card>
</CardGroup>

## 运行内置 agent

```shell theme={null}
export ANTHROPIC_API_KEY=sk-ant-...
npx niceeval exp local fixtures/button --sandbox docker

npx niceeval exp local fixtures/button --runs 10 --early-exit
```

<Note>
  如果 Docker 是默认后端，`--sandbox docker` 可以省略。`--sandbox auto` 会根据环境变量选择云端或 Docker。
</Note>

## agent 环境变量

| Agent         | 必需变量                |
| ------------- | ------------------- |
| `claude-code` | `ANTHROPIC_API_KEY` |
| `codex`       | `OPENAI_API_KEY`    |
| `bub`         | 遵循 bub CLI 鉴权       |

## 工作流程

```text theme={null}
createSandbox
  → git init && git commit
  → adapter.setup?                 # 装 CLI / 写 agent 配置
  → test(t): uploadDirectory(...)   # 写入这条 eval 的起始文件
  → adapter.send(input, ctx)
  → test(t): runCommand(...)        # 手工运行验证命令
  → collectGeneratedFiles()         # git diff HEAD
  → sandbox.stop()
```

起始文件和验证命令都写在 `test(t)` 中。agent 执行阶段只能看到你已经写进 sandbox 的文件。

## 自定义 sandbox agent

```ts theme={null}
import { defineSandboxAgent } from "niceeval/adapter";

export default defineSandboxAgent({
  name: "my-agent",
  async send(input, ctx) {
    await ctx.sandbox.runCommand("my-agent", ["run", input.text]);
    const transcript = await ctx.sandbox.readFile("transcript.jsonl");
    return {
      status: "completed",
      events: parseTranscript(transcript),
    };
  },
});
```

## `ctx.model` 与 `ctx.flags`

CLI 传入的模型和自定义 flags 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。

## 在 experiment 中使用自定义 agent

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

export default defineExperiment({
  agent: myAgent,
  runs: 3,
});
```

<Warning>
  不要在 core runner 里写 agent-specific 分支。差异行为应该放进 adapter。
</Warning>