Harnesses

模型调用、CLI agent、terminal agent 和外部框架的执行适配层。

Harnesses 定义“如何尝试完成任务”。它们把模型、命令行 agent 或外部 agent framework 适配到 AgentCompass 的 PreparedTask -> RunResult 契约。

Harness 不负责 benchmark scoring。它运行 agent，收集 trajectory 和 output，并把标准化结果交给 benchmark 和 analyzers。

​

Harnesses 负责什么

兼容性

声明该 harness 是否支持当前 environment 和 model protocol。

Session setup

启动本地进程、remote entrypoint、tmux session 或 framework session。

任务执行

消费 PreparedTask 并返回包含 prediction、trajectory、error 和 metadata 的 RunResult。

清理

释放 harness 自己持有的 session 资源，不删除 benchmark 的结果产物。

​

核心接口

Method	职责
supports(environment, model)	在任务运行前检查 environment 和 model 兼容性。
build_config(req)	从 merged params 构造 harness-specific config。
build_plan(req, environment)	添加 harness-side execution plan fields。
start_session(env, req, plan)	为一个 environment session 准备可复用状态。
run_task(session, prepared, req, plan)	执行单个 prepared task 并返回 RunResult。
close_session(session)	释放 harness-owned resources。

​

Harness 家族

家族	示例	适用场景
Direct model calls	openai_chat, qwen3vl_gui	任务是 prompt、messages 或 GUI grounding request。
Coding agents	mini_swe_agent, openhands, claude_code, codex	任务提供 repository workspace 和 issue prompt。
Terminal agents	terminus2, terminus2_skills	任务需要在 environment 中执行 shell actions。
Research agents	researchharness, naive_search_agent	任务需要 browsing、search 或 long-form research。
Tool-use harnesses	scicode_tool_use, openclaw	benchmark 有专门的 tool protocol 或 framework。

​

用法：GUI Grounding Harness

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

这里 screenspot 准备图片和指令，qwen3vl_gui 调用模型 endpoint。评分仍然由 ScreenSpot benchmark 负责。

​

用法：Coding Agent Harness

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"

Benchmark 在 /testbed 准备 repository task，Modal recipe 选择任务镜像，mini_swe_agent 在 workspace 中运行修复流程。

​

用法：Terminal Agent Harness

agentcompass run \
  terminal_bench_2 \
  terminus2 \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["overfull-hbox"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"

Terminal harness 高度依赖 environment 行为。如果任务 image、命令执行或 workspace isolation 不应占用本地资源，优先使用 remote sandbox。

​

Harness 输出应包含什么

• final prediction 或生成文件；
• 结构化 trajectory steps；
• 可用时记录 model usage、latency、tool-call metadata；
• analyzer 能解析的 error fields；
• benchmark evaluation 所需的 workspace 或 command context。

​

开发者说明

当 agent framework、CLI、model interaction protocol 或 terminal control loop 是新的，就新增 harness。如果只是 task image 或 workspace 不同，应使用 recipe 或 environment config。

​

相关页面

• Models
• Environments
• Runtime Extensions