Runtime

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

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

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

​

Runtime 负责什么

请求构造

合并 config/defaults.yaml、组件默认值、CLI overrides 和 Python kwargs，生成 RunRequest。

执行计划

为每个任务构造 ExecutionPlan，并在 environment 启动前让 recipe 改写计划。

并发控制

同时处理 per-run task_concurrency 和 process-global provider limits。

产物持久化

写出 run info、task details、summary、progress events、logs 和可选 analysis output。

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 阶段的结构化事件。

​

执行流

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 的流程：

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 用法

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 用法

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
• CLI 参考
• Configuration 模块
• 配置
• 架构