> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harborframework.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate a user

> Evaluate an agent through a multi-turn conversation with a simulated user.

A simulated-user trial pairs a user agent with the target agent under test. The
user agent receives the task instruction. The target starts without it and
learns the task through conversation. Harbor runs the verifier afterward.

<Frame caption="Simulated user architecture diagram">
  <img src="https://mintcdn.com/harborframework/l9c_ohETpnOqpDv2/images/acp-simulated-user.png?fit=max&auto=format&n=l9c_ohETpnOqpDv2&q=85&s=8fb08316424c12dbc718b398db9b6189" alt="Diagram showing a user agent sending prompts through acpx to a target agent while both share a task workspace" width="2400" height="1440" data-path="images/acp-simulated-user.png" />
</Frame>

## Examples

### Hello world

```bash theme={"system"}
uv run harbor run \
  -p examples/tasks/hello-world \
  --agent claude-code --model anthropic/claude-sonnet-5 \
  --user-agent claude-code --user-model anthropic/claude-sonnet-5 \
  --bridge acp
```

### One example from [SWE-Interact](https://arxiv.org/pdf/2606.30573)

```bash theme={"system"}
uv run harbor run \
  -p examples/tasks/deepswe_tomlkit-toml-table-converters \
  --agent claude-code --model anthropic/claude-sonnet-5 \
  --user-agent claude-code --user-model anthropic/claude-sonnet-5 \
  --user-persona-path examples/tasks/deepswe_tomlkit-toml-table-converters/persona.md \
  --bridge acp
```

<Note>
  Simulated-user trials can run for a long time. This example takes about 50
  minutes.
</Note>

<Frame caption="simulated user in viewer">
  <video controls preload="metadata" className="w-full rounded-xl" src="https://mintcdn.com/harborframework/l9c_ohETpnOqpDv2/videos/simulated-user-demo.mp4?fit=max&auto=format&n=l9c_ohETpnOqpDv2&q=85&s=c611f3c66405ec66cd5d01755718cd5a" data-path="videos/simulated-user-demo.mp4">
    Your browser does not support embedded video.
  </video>
</Frame>

## Bridge

`--bridge acp` installs [acpx](https://github.com/openclaw/acpx) in the task
environment and connects the user agent to the target. The user sends each
message with `acpx prompt`.

The ACP bridge supports `claude-code` and `gemini-cli` as **target agents**. The
remaining [ACP Registry Agents](https://agentclientprotocol.com/get-started/registry)
are not wired into Harbor yet. The **user agent** can be **any** Harbor agent.

## User prompt

Harbor builds the user agent's prompt in this
[order](https://github.com/harbor-framework/harbor/blob/main/src/harbor/trial/simulated_user.py#L17-L22):

| Part                | Default                                                                                                            | Override               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| Persona             | [Default persona](https://github.com/harbor-framework/harbor/blob/main/src/harbor/trial/simulated_user.py#L11-L15) | `--user-persona-path`  |
| Bridge instructions | [Default ACP instructions](https://github.com/harbor-framework/harbor/blob/main/src/harbor/bridges/acp.py#L26-L38) | `--bridge-prompt-path` |
| Task instruction    | `instruction.md`                                                                                                   | —                      |

`--user-prompt-template-path` replaces this layout with a Jinja2 template.
The template must include `{{ bridge_instructions }}` and `{{ instruction }}`;
`{{ persona }}` is optional.