配置 Environment

选择 provider 和传入 Environment 参数是两件事：provider 决定任务由哪一种 Environment 实现执行，参数决定该 Environment 如何创建和运行。建议只设置需要改变的字段，其余字段交给 provider 默认值或适用的 Recipe 补齐。 Environment 参数必须在公开 schema 中声明，可通过 agentcompass config docs env <provider-id> 查看。未声明字段（包括拼写错误和所有 provider 专属参数）统一报“未知参数”错误。出站访问通过通用网络策略配置，再由适配器在内部生成对应的原生 API 选项。所有 provider 共用一份 schema。Provider ID 只选择实现及其支持的能力，不会增加公开参数。setup 包含 image、workdir、build_timeout_seconds 和 os；evaluation_setup 为独立 verifier 使用相同结构。资源、网络和环境变量字段也全部通用。Host 凭证通过适配器已有的环境变量或 SDK 配置提供，不属于任务执行设置。

Recipe 默认由 AgentCompass 自动匹配。常规评测不需要设置或改写 Recipe；只有 Benchmark 文档明确要求替代 Recipe、排查匹配问题或加载团队自定义逻辑时，才需要手动配置。

选择 provider 与配置入口

下列入口都能提供 Environment 参数。选择哪一种，取决于这些值只用于当前评测，还是需要在其他运行或程序中复用：

入口	配置方式	适用场景
`agentcompass run`	使用 `--env <provider-id>` 选择 provider，使用 `--env-params '<json>'` 传入参数。	只为当前评测临时设置。
配置文件	在 `environments.<provider-id>` 下保存该 provider 的默认参数；具体使用哪个 provider，仍由 `run`、`launch` 或 SDK 选择。	在多次评测中复用默认值。
Python SDK：单评测	在 `run_evaluation()` 中使用 `environment="<provider-id>"` 选择 provider，并通过 `environment_params={...}` 传入参数。	从 Python 程序发起单评测请求。
`agentcompass launch`	在编排文件的 `environment` 中，用 `id` 选择 provider，并将参数写在 `id` 旁边。	用 YAML 或 JSON 编排一个或多个评测请求。
Python SDK：多评测	在 `OrchestrationSpec` 的 `defaults.environment` 或 `requests[].environment` 中使用与编排文件相同的结构。	从 Python 程序发起多评测请求。

`agentcompass run`

使用 --env <id> 选择 provider；省略时默认使用 host_process。运行 agentcompass list env 可以查看当前安装中可用的 provider ID。 --env-params 接收一个 JSON 对象，用于设置本次评测的 Environment 参数；同名字段会覆盖配置文件中的值：

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --env-params '{"setup":{"image":"python:3.13-slim"},"resources":{"cpu":2,"memory_mb":6144}}'

配置文件

可复用的 provider 参数直接写在 environments.<id> 下，不要增加 params 包装层：

environments:
  docker:
    setup:
      image: python:3.13-slim
    resources:
      cpu: 2
      memory_mb: 6144

运行时选择同一个 provider 并加载文件：

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --config config.yaml

Python SDK 单评测

SDK 使用 Python 字典传递参数，不需要把它们转换成 JSON 字符串：

from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    model="your-model",
    environment="docker",
    environment_params={
        "resources": {
            "cpu": 2,
            "memory_mb": 6144,
        },
    },
)

`agentcompass launch` 与 SDK 多评测

在 launch 编排中，id 选择 provider，其他字段直接写在 environment 下：

defaults:
  environment:
    id: docker
    resources:
      cpu: 2
      memory_mb: 6144

编排文件中的每个评测请求都可以在自己的 environment 中覆盖这些默认值。Python SDK 的 OrchestrationSpec 使用相同的字段结构。完整说明见 agentcompass launch 的映射规则和 Python SDK 的多评测请求。

如果一个编排混用多个 provider，不要把某个 provider 的专属参数放在 defaults.environment 中。请求即使覆盖了 environment.id，仍会继承并合并 defaults.environment 的其他字段。此时应把专属参数写入各自的 requests[].environment。

嵌套字段怎么写

Provider 参数既可以是字符串、数字或布尔值，也可以是对象和列表。参数参考中的 resources.cpu 表示“resources 对象里的 cpu 字段”，不是名为 resources.cpu 的扁平键。下面四种写法等价，都会为 Daytona 设置 2 个 vCPU 和 6 GiB 内存。 CLI 使用 JSON 对象：

--env daytona \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'

配置文件保留 YAML 的嵌套结构：

environments:
  daytona:
    resources:
      cpu: 2
      memory_mb: 6144

Python SDK 使用嵌套字典：

from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="<benchmark>",
    harness="<harness>",
    model="<model>",
    environment="daytona",
    environment_params={"resources": {"cpu": 2, "memory_mb": 6144}},
)

launch 编排将参数与 id 写在同一层，参数内部仍可嵌套：

defaults:
  environment:
    id: daytona
    resources:
      cpu: 2
      memory_mb: 6144

对象按字段递归合并，标量和列表则由后面的值整体替换。例如，配置文件已经设置 resources.cpu: 2 和 resources.memory_mb: 6144，本次请求只传入 {"resources":{"memory_mb":8192}} 时，结果是 2 个 vCPU 和 8192 MiB 内存。不要额外增加 params 包装层，也不要把字段路径写成 {"resources.cpu":2}。嵌套字段、单位和可用值以相应 provider 的参数参考为准。

分清字段归属

Environment 参数由两类字段组成：

字段类别	字段或示例	说明
共享 setup 字段	`setup.image`、`setup.workdir`、`setup.build_timeout_seconds`、`setup.os`	描述与 provider 无关的启动要求。provider 会把支持的字段映射到 adapter，但不会把 workdir 当作 Benchmark workspace。
共享网络字段	`network_policy`、`run_network_policy`、`verifier_network_policy`	分别设置基础策略、agent 运行策略和验证策略；后两项未设置时继承基础策略。provider 必须支持所选模式，详见网络策略。
provider 字段	凭证、资源、调度位置和生命周期等	由所选 provider 定义。字段名、单位和默认值不能在不同 provider 之间直接照搬。

无论使用哪种入口，共享 setup 字段、共享网络字段和 provider 字段都写在同一层，不需要再增加 params。例如，在配置文件中，它们都直接写在 environments.docker 下。

查看字段与配置结果

查询当前安装版本中某个 provider 的专属字段、类型和默认值：

agentcompass config docs env docker

查看内置默认值与配置文件合并后的结果：

agentcompass config show \
  --env docker \
  --config config.yaml

config show 只展示内置值和配置文件的合并结果，不包含本次运行额外传入的 CLI、SDK 或编排字段，也不会展示 Recipe 在任务开始前补充的最终 Environment 设置。命令的完整行为见 agentcompass config。

Environment 参数如何生效

Environment 参数不是一次性从某一个入口读取，而是按以下阶段逐步形成：

阶段	作用
provider 默认值与配置文件	形成可复用的基础配置；配置文件中的值覆盖同名内置默认值。`config show` 展示到这一阶段为止的结果。
本次请求的显式参数	`run` CLI、Python SDK 或编排请求中显式传入的字段覆盖配置文件中的同名值。
Recipe	等具体任务确定后，根据 Benchmark、Harness 和 provider 的组合补充或调整镜像、Environment workdir、Benchmark workspace、资源、网络及必要的执行设置。因为这些调整与任务有关，所以不会出现在 `config show` 中。

下面的命令没有设置 Docker 镜像。匹配的 SWE-bench Verified Recipe 会根据样本补充镜像和任务工作区，因此通常只需选择 provider：

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker

如果没有匹配的 Recipe，仍须按照 provider 页面提供其必填字段，例如 Docker 的任务镜像。Recipe 也不是一条“显式参数永远优先”的通用规则：内置 Recipe 通常会保留兼容的显式镜像和资源设置，但仍可能调整 Benchmark 或 Harness 必需的工作区、网络或执行设置。只有确实需要改变默认行为时才传入 Environment 参数。不同 provider 的合法取值以相应 provider 页面和 config docs 输出为准。

评测总超时、并发和 Environment 启动速率属于运行控制。Modal 的 timeout 和 OpenSandbox 的 lifecycle_seconds 等字段只限制单个 sandbox 的存活时间，不等同于评测总超时。

使用 AgentCompass

模块

其他功能

选择 provider 与配置入口

`agentcompass run`

配置文件

Python SDK 单评测

`agentcompass launch` 与 SDK 多评测

嵌套字段怎么写

分清字段归属

查看字段与配置结果

Environment 参数如何生效

相关页面

​选择 provider 与配置入口

​agentcompass run

​配置文件

​Python SDK 单评测

​agentcompass launch 与 SDK 多评测

​嵌套字段怎么写

​分清字段归属

​查看字段与配置结果

​Environment 参数如何生效

​相关页面

选择 provider 与配置入口

`agentcompass run`

配置文件

Python SDK 单评测

`agentcompass launch` 与 SDK 多评测

嵌套字段怎么写

分清字段归属

查看字段与配置结果

Environment 参数如何生效

相关页面