跳转到主要内容
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。
ExecutionSpectask concurrency、enabled recipes、retry count 和 analysis settings。
ExecutionPlan单任务计划，包含 benchmark、harness、environment 三侧信息。
UnifiedEvaluationRuntimeCLI 和 Python API 共用的 in-process executor。
ProgressEventtask 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.yamlruntime、execution、components、providers 和 analysis 的项目默认值。
Component defaultsbenchmarks.<id>、harnesses.<id>、environments.<id> block。
CLI flags / Python kwargs单次 run 的最高优先级 override。
Recipesenvironment 启动前的最终 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。

​
相关页面