> ## 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 Agent 安装 CLI

> 用 ensure 和 installer 检查、安装并复检自定义 coding-agent CLI 的精确版本。

自定义 Sandbox Agent 需要声明 CLI 的名称、版本和安装方式。NiceEval 会先检查 Sandbox 里的 CLI。版本不匹配时，NiceEval 会安装指定版本，然后再检查一次。

## 声明 CLI 身份和安装方式

Node.js CLI 可以使用 `createNpmCliInstaller`。下面的代码把 npm 包 `my-agent@1.0.0` 接入自定义 Adapter：

```ts theme={null}
// agents/my-agent.ts
import {
  completeEvidenceCoverage,
  createNpmCliInstaller,
  defineSandboxAgent,
  resolveAgentBin,
} from "niceeval/adapter";

const { ensure, installer } = createNpmCliInstaller({
  identity: {
    agent: "my-agent",
    version: "1.0.0",
    revision: "1",
  },
  packageName: "my-agent",
  bin: "my-agent",
  progress: {
    checking: "检查 my-agent CLI 1.0.0",
    installing: "安装 my-agent CLI 1.0.0",
    ready: "my-agent CLI 1.0.0 已就绪",
  },
});

export default defineSandboxAgent({
  name: "my-agent",
  evidenceCoverage: completeEvidenceCoverage,
  ensure,
  installers: [installer],

  async setup(sandbox) {
    await sandbox.writeText(".my-agent/config.json", JSON.stringify({ telemetry: true }));
  },

  async send(input, ctx) {
    const bin = await resolveAgentBin(ctx.sandbox, "my-agent");
    const result = await ctx.sandbox.runCommand(bin, ["run", "--json", input.text]);
    if (result.exitCode !== 0) {
      throw new Error(`my-agent 退出码 ${result.exitCode}: ${result.stderr}`);
    }
    return parseTurn(result.stdout);
  },
});
```

`identity.version` 是 CLI 的精确版本。同一版本的安装步骤变化时，同时更新 `identity.revision`。不要在这里使用 `latest`。

`setup` 只写鉴权和运行配置。CLI 安装由 `installer` 负责，因此每个 Attempt 都会先完成版本检查。

## 在实验中运行

把 Agent 和 Sandbox Provider 放进实验：

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

export default defineExperiment({
  agent: myAgent,
  model: "acme-model-v2",
  sandbox: dockerSandbox({ source: { type: "image", image: "debian:bookworm-slim" } }),
});
```

```shell theme={null}
npx niceeval exp my-agent fixtures/button
```

Sandbox 不需要 Node.js 或 npm。`createNpmCliInstaller` 在宿主机上下载 npm 包，再通过 Sandbox 的文件接口安装。Sandbox 如果已有正确版本，NiceEval 会直接使用它。

## 检查安装失败

安装或复检失败时，Attempt 会在 `agent.ensure` 阶段变成 `errored`。终端会给出 Attempt 定位符。

```shell theme={null}
npx niceeval show @<attempt-locator>
```

先检查错误里的包名、版本和目标平台。修正 `identity`、npm 包或安装步骤后，重新运行原命令。

## 选择其他安装模式

`AgentInstaller` 还支持两种模式：

* `sandbox-network` 允许 Sandbox 使用自己的网络安装 CLI。只在题目明确允许这种网络访问时使用。
* `verify-only` 只接受预装的精确版本。检查失败时，Attempt 会直接报错。

这两种模式需要自己提供 `AgentInstaller`。完整字段见 [`defineSandboxAgent` 参考](/docs/zh/reference/define-agent#definesandboxagent)。