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

> Execution adapters for model calls, CLI agents, terminal agents, and external frameworks.

Harnesses define how a prepared task is attempted. They adapt a model, command-line agent, or external agent framework to AgentCompass' `PreparedTask -> RunResult` contract.

Harnesses should not own benchmark scoring. They run the agent, collect trajectory and output, and return normalized data for the benchmark and analyzers.

## What Harnesses Own

<CardGroup cols={2}>
  <Card title="Compatibility" icon="shield-check">
    Declare whether the harness supports the selected environment and model protocol.
  </Card>

  <Card title="Session setup" icon="play">
    Start any local process, remote entrypoint, tmux session, or framework session needed for tasks.
  </Card>

  <Card title="Task execution" icon="terminal">
    Consume `PreparedTask` and return `RunResult` with prediction, trajectory, errors, and metadata.
  </Card>

  <Card title="Cleanup" icon="rotate-ccw">
    Close sessions without deleting benchmark-owned result artifacts.
  </Card>
</CardGroup>

## Core Interface

| Method                                   | Responsibility                                                 |
| ---------------------------------------- | -------------------------------------------------------------- |
| `supports(environment, model)`           | Validate environment and model compatibility before tasks run. |
| `build_config(req)`                      | Build harness-specific config from merged params.              |
| `build_plan(req, environment)`           | Add harness-side execution plan fields.                        |
| `start_session(env, req, plan)`          | Prepare reusable state for one environment session.            |
| `run_task(session, prepared, req, plan)` | Execute one prepared task and return `RunResult`.              |
| `close_session(session)`                 | Release harness-owned resources.                               |

## Harness Families

| Family                       | Examples                                              | Best Use when                                               |
| ---------------------------- | ----------------------------------------------------- | ----------------------------------------------------------- |
| Direct model calls           | `openai_chat`, `qwen3vl_gui`                          | The task is a prompt, messages, or GUI grounding request.   |
| Coding agents                | `mini_swe_agent`, `openhands`, `claude_code`, `codex` | The task provides a repository workspace and issue prompt.  |
| Terminal agents              | `terminus2`, `terminus2_skills`                       | The task requires shell actions in an environment.          |
| Research agents              | `researchharness`, `naive_search_agent`               | The task requires browsing, search, or long-form research.  |
| Tool-use benchmark harnesses | `scicode_tool_use`, `openclaw`                        | The benchmark has a specialized tool protocol or framework. |

## Usage: 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
```

Here `screenspot` prepares image and instruction data. `qwen3vl_gui` sends the prepared GUI grounding request to the model endpoint. ScreenSpot still owns scoring.

## Usage: 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"
```

The benchmark prepares a repository task under `/testbed`; the Modal recipe selects the task image; `mini_swe_agent` runs the repair workflow against that workspace.

## Usage: 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 harnesses depend heavily on environment behavior. Use remote sandboxes when the task image, command execution, or workspace isolation should not consume local resources.

## What Harnesses Return

Good harness output includes:

* final prediction or generated files;
* structured trajectory steps;
* model usage, latency, and tool-call metadata when available;
* error fields that can be parsed by analyzers;
* enough workspace or command context for benchmark evaluation.

## Developer Notes

Add a harness when an agent framework, CLI, model interaction protocol, or terminal control loop is new. If only the task image or workspace differs, add a recipe or environment config instead.

## Related Pages

* [Models](/key_modules/models)
* [Environments](/key_modules/environments)
* [Runtime Extensions](/developer/runtime_extensions)