> ## 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.

# Harnesses

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

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

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

## Harnesses 负责什么

<CardGroup cols={2}>
  <Card title="兼容性" icon="shield-check">
    声明该 harness 是否支持当前 environment 和 model protocol。
  </Card>

  <Card title="Session setup" icon="play">
    启动本地进程、remote entrypoint、tmux session 或 framework session。
  </Card>

  <Card title="任务执行" icon="terminal">
    消费 `PreparedTask` 并返回包含 prediction、trajectory、error 和 metadata 的 `RunResult`。
  </Card>

  <Card title="清理" icon="rotate-ccw">
    释放 harness 自己持有的 session 资源，不删除 benchmark 的结果产物。
  </Card>
</CardGroup>

## 核心接口

| 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

```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
```

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

## 用法：Coding Agent Harness

```bash theme={null}
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

```bash theme={null}
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](/zh/key_modules/models)
* [Environments](/zh/key_modules/environments)
* [Runtime Extensions](/zh/developer/runtime_extensions)