> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

Python SDK 与 CLI 使用同一个评测 runtime。根据需要执行的评测请求数量选择入口：

| 请求类型 | 同步入口 | 异步入口 | 对应 CLI |
| - | - | - | - |
| 单评测请求 | `run_evaluation()` | `async_run_evaluation()` | [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run) |
| 多评测请求 | `launch()` | `async_launch()` | [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch) |

## 单评测请求

`run_evaluation()` 执行一个由 [Model](/zh/user_guide/modules/models/overview)、[Benchmark](/zh/user_guide/modules/benchmarks/overview)、[Harness](/zh/user_guide/modules/harnesses/overview) 和 [Environment](/zh/user_guide/modules/environments/overview) 组成的评测请求：

```python theme={"system"}
import os

from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    model=os.environ["MODEL_NAME"],
    environment="docker",
    benchmark_params={"sample_ids": ["astropy__astropy-12907"]},
    model_base_url=os.environ["MODEL_BASE_URL"],
    model_api_key=os.environ["MODEL_API_KEY"],
    model_api_protocol="openai-chat",
    model_params={"temperature": 0},
    task_concurrency=1,
    results_dir="results",
    progress="auto",
)
```

参数均为仅限关键字参数。调用成功后返回包含 `metadata`、`metrics`、`summary` 和 `paths` 的字典；逐任务详情保存在结果目录中。单请求超时或执行失败时，函数会抛出相应异常。

异步应用使用 `await async_run_evaluation(...)`，参数和返回值与同步入口相同。

## 多评测请求

`launch()` 接收一个 `OrchestrationSpec`。其中，每个 `RunRequestSpec` 表示一个具名评测请求，`OrchestrationDefaults` 用于保存所有请求共享的组件和设置：

```python theme={"system"}
import os

from agentcompass import (
    OrchestrationDefaults,
    OrchestrationSpec,
    RunRequestSpec,
    launch,
)

spec = OrchestrationSpec(
    name="terminal-evaluations",
    task_concurrency=4,
    defaults=OrchestrationDefaults(
        harness={"id": "terminus2", "max_turns": 300},
        environment={"id": "docker"},
        model={
            "id": os.environ["MODEL_NAME"],
            "base_url": os.environ["MODEL_BASE_URL"],
            "api_key": os.environ["MODEL_API_KEY"],
            "api_protocol": "openai-chat",
        },
    ),
    requests=[
        RunRequestSpec(
            name="terminal-bench-2-verified",
            benchmark={"id": "terminal_bench_2_verified"},
        ),
        RunRequestSpec(
            name="terminal-bench-2.1",
            benchmark={"id": "terminal_bench_2_1"},
        ),
    ],
)

result = launch(spec, progress="auto")
```

`task_concurrency` 是所有请求共享的实际 attempt 执行并发上限，retry 也使用同一并发池。`launch()` 返回 `OrchestrationResult`，其中 `status` 表示编排状态，`requests` 按请求名称保存各自的状态、结果、错误和输出路径。单个请求失败不会丢失其他请求的结果。

多请求参数分为编排级设置、所有请求共享的默认值和单个请求的覆盖值，分别写入 `OrchestrationSpec`、`OrchestrationDefaults` 和对应的 `RunRequestSpec`。

异步应用使用 `await async_launch(spec, ...)`。编排字段的继承和映射规则见 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。

## 与 CLI 的参数对应关系

CLI 使用命令行字符串；SDK 使用 `snake_case` 关键字和原生 Python 对象。下面先列出 `run`、`launch` 及对应 SDK 入口共享的参数，再分别说明单评测请求和多评测编排的传参方式。

### 共享运行参数

| CLI | Python SDK | 传参形式 |
| - | - | - |
| `--config <path>` | `config_path` | CLI 可重复指定；SDK 接收一个路径或路径序列。`launch()` 仅在接收 `OrchestrationSpec` 时可使用该参数。 |
| `--task-concurrency <n>` | `task_concurrency` | 限制同时执行的实际 attempt 数量，包括 retry；单请求时作用于该请求，多请求时作用于整个编排。 |
| `--results-dir <path>` | `results_dir` | 设置结果根目录。 |
| `--data-dir <path>` | `data_dir` | 设置数据与缓存根目录。 |
| `--timeout-seconds <seconds>` | `timeout_seconds` | 分别限制单个评测请求或整个编排的执行时间；单评测接收整数秒，多评测也可接收小数。 |
| `--provider-limit <provider>=<n>` | `provider_limits` | CLI 可重复指定；SDK 接收 `dict[str, int]`。 |
| `--env-open-qps <provider>=<qps>` | `env_open_qps` | CLI 可重复指定；SDK 接收 `dict[str, float]`。 |
| `--progress auto\|plain\|none` | `progress` | SDK 接收同样的字符串取值。 |
| `--log-level <level>` | `log_level` | 值可为 `DEBUG`、`INFO`、`WARNING`、`ERROR` 或 `CRITICAL`。 |
| `--file-log-level <level>` | `file_log_level` | 取值与 `log_level` 相同。 |
| `--auto-install-dependencies` | `auto_install_dependencies` | SDK 接收布尔值。 |
| 无 | `log_file` | SDK 可指定日志文件路径。 |
| 无 | `on_progress` | SDK 可接收进度事件回调。 |

### 单评测请求的直接参数

| `agentcompass run` | `run_evaluation()` / `async_run_evaluation()` | 传参形式 |
| - | - | - |
| `BENCHMARK` | `benchmark` | Benchmark ID；SDK 中为仅限关键字参数。 |
| `HARNESS` | `harness` | Harness ID；SDK 中为仅限关键字参数。 |
| `MODEL` | `model` | Model ID；SDK 中为仅限关键字参数。 |
| `--benchmark-params <json>` | `benchmark_params` | CLI 接收 JSON 对象；SDK 接收 `dict`。 |
| `--harness-params <json>` | `harness_params` | CLI 接收 JSON 对象；SDK 接收 `dict`。 |
| `--model-base-url <url>` | `model_base_url` | 值直接对应。 |
| `--model-api-key <key>` | `model_api_key` | 值直接对应。 |
| `--model-api-protocol <protocol>` | `model_api_protocol` | SDK 可直接接收协议名称、`auto` 或字符串列表。 |
| `--model-params <json>` | `model_params` | CLI 接收 JSON 对象；SDK 接收 `dict`。 |
| `--env <id>` | `environment` | Environment ID。 |
| `--env-params <json>` | `environment_params` | CLI 接收 JSON 对象；SDK 接收 `dict`。 |
| `--execution-params <json>` | `execution_params` | 公共执行覆盖，在 YAML 上深度合并，包括产物相关预算。 |
| `--max-retries <n>` | `max_retries` | 值直接对应。 |
| `--retry-pattern-list <json>` | `retry_pattern_list` | CLI 接收 JSON 字符串数组；SDK 接收 `list[str]`。 |
| `--recipe <id>` | `enabled_recipes` | CLI 可重复指定 [Recipe](/zh/user_guide/other_features/recipes) ID；SDK 接收字符串列表。 |
| `--recipe-dir <path>` | `recipe_dirs` | CLI 可重复指定；SDK 接收路径序列。 |
| `--run-name <name>` | `run_name` | 值直接对应。 |
| `--run-id <id>` | `run_id` | 为新结果目录指定运行 ID。 |
| `--reuse [run-id]` | `reuse`、`reuse_run_id` | SDK 将是否复用和待复用的运行 ID 分为两个参数。 |
| `--no-checkpoint-resume` | `checkpoint_resume=False` | 不使用 agent 运行后的 checkpoint 继续待执行的 fresh 评测，有效默认值为 `True`。 |
| `--keep-environment` | `keep_environment` | SDK 接收布尔值。 |
| `--enable-analysis` | `enable_analysis` | SDK 接收布尔值。 |
| `--analysis-params <json>` | `analysis_params` | CLI 接收 JSON 对象；SDK 接收 `dict`。 |

参数的含义和默认值见 [`agentcompass run` 参数参考](/zh/user_guide/using_agentcompass/cli/run#参数参考)。

### 多评测请求的编排参数

| `agentcompass launch` | `launch()` / `async_launch()` | 传参形式 |
| - | - | - |
| `ORCHESTRATION_PATH` | `orchestration` | CLI 读取 YAML 或 JSON 文件；SDK 接收 `OrchestrationSpec` 或已解析的 `Orchestration` 对象。 |
| `--cleanup-grace-seconds <seconds>` | `cleanup_grace_seconds` | 设置取消后的协作清理宽限期。 |
| `--run-id <id>` | 无同名关键字参数 | CLI 覆盖每个请求的 `output.run_id`；SDK 需在各 `RunRequestSpec.output` 中设置。 |
| `--reuse` | 无同名关键字参数 | 对应 `OrchestrationDefaults.runtime` 中的 `reuse: true`；单个请求可覆盖该默认值。 |
| `--dry-run` | 无 | 仅 CLI 提供编排预检和解析结果输出。 |
| 编排文件中的 `runtime.recipe_dirs` | `OrchestrationSpec.runtime.recipe_dirs` | 多评测没有对应的 CLI 选项或 `launch()` 关键字参数。 |
| 无 | `on_request_finished` | SDK 可在每个请求结束时接收回调。 |

`OrchestrationSpec` 的顶层字段为 `version`、`name`、`task_concurrency`、`runtime`、`defaults` 和 `requests`；当前 `version` 仅支持 `1`。

### 请求字段的编排写法

单评测也包含下表中的组件和请求设置，但通过 `agentcompass run` 或 `run_evaluation()` 的直接参数传入。在多评测编排中，这些内容不是 `launch()` 的关键字参数：CLI 将其写入编排文件，SDK 则写入 `OrchestrationDefaults` 或 `RunRequestSpec`。

| 编排文件 | Python SDK | 包含字段 |
| - | - | - |
| `requests[].name` | `RunRequestSpec.name` | 每个请求必填且不能重复的名称。 |
| `defaults.benchmark` / `requests[].benchmark` | `benchmark` | `id` 及与之同级的 Benchmark 配置字段。 |
| `defaults.harness` / `requests[].harness` | `harness` | `id` 及与之同级的 Harness 配置字段。 |
| `defaults.model` / `requests[].model` | `model` | `id`、`base_url`、`api_key`、`api_protocol` 和 `params`。 |
| `defaults.environment` / `requests[].environment` | `environment` | `id` 及与之同级的 Environment 配置字段。 |
| `defaults.execution` / `requests[].execution` | `execution` | `max_retries`、`retry_pattern_list`、`enabled_recipes`、`keep_environment`、`enable_analysis` 和 `analysis_params`。 |
| `defaults.runtime` / `requests[].runtime` | `runtime` | `reuse`、`reuse_run_id` 和 `checkpoint_resume`。 |
| `defaults.output` / `requests[].output` | `output` | `run_name` 和 `run_id`。 |

`task_concurrency` 只能作为编排级设置，不能写入 `defaults.execution` 或 `requests[].execution`。完整字段结构和继承规则见 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。

## 相关页面

* 并发、重试和恢复：[运行控制](/zh/user_guide/using_agentcompass/run_controls)
* 总时限与单任务预算：[超时设置](/zh/user_guide/using_agentcompass/timeouts)
* 保存任务文件：[保存与准备产物](/zh/user_guide/using_agentcompass/artifacts)
* 配置文件的加载和合并：[`agentcompass config`](/zh/user_guide/using_agentcompass/cli/config)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.