> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime

> 把一次请求编排成有并发控制、可持久化 evaluation run 的核心层。

Runtime 是 AgentCompass 的中心。它接收 CLI flags 或 Python 参数，归一化成 `RunRequest`，加载注册组件，在并发上限内执行任务，并写出可复用的结果产物。

当你想理解 `agentcompass run` 启动后发生了什么，先读这一页。

## Runtime 负责什么

<CardGroup cols={2}>
  <Card title="请求构造" icon="file-code">
    合并 `config/defaults.yaml`、组件默认值、CLI overrides 和 Python kwargs，生成 `RunRequest`。
  </Card>

  <Card title="执行计划" icon="workflow">
    为每个任务构造 `ExecutionPlan`，并在 environment 启动前让 recipe 改写计划。
  </Card>

  <Card title="并发控制" icon="gauge">
    同时处理 per-run `task_concurrency` 和 process-global provider limits。
  </Card>

  <Card title="产物持久化" icon="database">
    写出 run info、task details、summary、progress events、logs 和可选 analysis output。
  </Card>
</CardGroup>

Runtime 不实现 benchmark scoring、agent 行为、provider SDK 调用或 badcase 诊断。这些分别属于 benchmarks、harnesses、environments 和 analyzers。

## 核心对象

| Object                     | 作用                                                                           |
| -------------------------- | ---------------------------------------------------------------------------- |
| `RunRequest`               | 完整请求：benchmark、harness、environment、model、execution controls、output controls。 |
| `ExecutionSpec`            | task concurrency、enabled recipes、retry count 和 analysis settings。            |
| `ExecutionPlan`            | 单任务计划，包含 benchmark、harness、environment 三侧信息。                                 |
| `UnifiedEvaluationRuntime` | CLI 和 Python API 共用的 in-process executor。                                    |
| `ProgressEvent`            | task loading、setup、execution、summary、release 阶段的结构化事件。                       |

## 执行流

```text theme={null}
run_evaluation(...) / agentcompass run
  -> build RunRequest
  -> load built-in registries
  -> benchmark.load_tasks()
  -> benchmark.select_tasks()
  -> load reusable details
  -> run pending tasks with task_concurrency
  -> process and save summary
  -> optionally save analysis summary
```

单个 pending task 的流程：

```text theme={null}
planner builds ExecutionPlan
  -> matching recipes apply
  -> environment.open()
  -> benchmark.prepare_task()
  -> harness.start_session()
  -> harness.run_task()
  -> benchmark.evaluate()
  -> analyzers run if enabled
  -> environment.close()
```

## CLI 用法

```bash theme={null}
agentcompass run \
  screenspot \
  qwen3vl_gui \
  qwen3-vl \
  --env <env-provider> \
  --benchmark-params '{"category":"desktop"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --task-concurrency 8 \
  --results-dir results \
  --data-dir data
```

三个位置参数选择 `benchmark`、`harness` 和 `model`。environment、model endpoint、concurrency 和 output directories 都会进入同一个 `RunRequest`。

## Python 用法

```python theme={null}
from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="screenspot",
    harness="qwen3vl_gui",
    model="qwen3-vl",
    environment="host_process",
    benchmark_params={"category": "desktop"},
    model_base_url="https://your-endpoint/v1",
    model_api_key="sk-...",
    model_api_protocol="openai-chat",
    task_concurrency=8,
    results_dir="results",
    data_dir="data",
)
```

返回值包含聚合 metadata、metrics、summary、output paths 和 applied recipes。per-task details 仍然写在磁盘上，避免大规模评测把所有细节留在内存中。

## 配置优先级

| 来源                        | 作用                                                            |
| ------------------------- | ------------------------------------------------------------- |
| `config/defaults.yaml`    | runtime、execution、components、providers 和 analysis 的项目默认值。     |
| Component defaults        | `benchmarks.<id>`、`harnesses.<id>`、`environments.<id>` block。 |
| CLI flags / Python kwargs | 单次 run 的最高优先级 override。                                       |
| Recipes                   | environment 启动前的最终 provider-aware plan rewrite。               |

## 常见模式

| 场景          | 写法                                                                                 |
| ----------- | ---------------------------------------------------------------------------------- |
| 跑单个样本       | `--benchmark-params '{"sample_ids":["task-id"]}'`                                  |
| 使用 provider | `--env <env-provider>`；对支持的 benchmark/provider 组合，recipe 可能自动推导 image 和 workspace。 |
| 提升吞吐        | `--task-concurrency 32`，同时确认模型 endpoint 和 provider 限额。                             |
| 复用已有结果      | 使用 output reuse 相关 CLI 或配置；runtime 会跳过已有 details。                                  |
| 后置分析        | run 时加 `--enable-analysis`，或之后使用 `agentcompass analysis`。                          |

## 开发者说明

大多数扩展不需要修改 runtime。优先新增或修改 benchmark、harness、environment、recipe 或 analyzer。只有当你需要新的跨模块执行行为，例如新的 progress event、新的结果持久化行为或新的 request-level control 时，才应该改 runtime。

## 相关页面

* [Python API](/zh/reference/python_api)
* [CLI 参考](/zh/reference/cli)
* [Configuration 模块](/zh/key_modules/configuration)
* [配置](/zh/reference/configuration)
* [架构](/zh/developer/architecture)