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

# ACP

> Run agents from the Agent Client Protocol registry.

Harbor's generic `acp` integration installs and runs agents from the
[ACP Registry](https://agentclientprotocol.com/get-started/registry) inside the
task environment. ACP provides a common protocol between clients and agents.

<Note>
  `--agent acp:...` selects an ACP registry agent. It is different from
  [`--bridge acp`](/core-concepts/jobs/simulate-a-user), which connects a
  simulated user to the target agent.
</Note>

## Run a registry agent

Harbor supports **all acp agents** in the
[ACP Registry Github](https://github.com/agentclientprotocol/registry) or
[ACP registry.json](https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json). The four agents below are examples. Use `acp:<agent_id>`
for the latest entry or `acp:<agent_id>@<version>` to pin a version.

<Warning>
  Unlike Harbor's installed agents, ACP agents do not receive provider credentials
  automatically. Pass each required variable with `--agent-env` (`--ae`).

  Authentication rules also vary by agent. Some agents require
  `--agent-kwarg authenticate_method_id=...` in addition to the credential. Check
  the agent's documentation in the
  [ACP Registry](https://github.com/agentclientprotocol/registry).
</Warning>

<Tabs>
  <Tab title="CLI">
    <CodeGroup>
      ```bash Codex theme={"system"}
      harbor run \
        -t hello-world/hello-world \
        --agent acp:codex-acp \
        --model openai/gpt-5.6-sol \
        --agent-env OPENAI_API_KEY="$OPENAI_API_KEY" \
        --agent-kwarg authenticate_method_id=api-key
      ```

      ```bash Claude Code theme={"system"}
      harbor run \
        -t hello-world/hello-world \
        --agent acp:claude-acp \
        --model anthropic/claude-sonnet-5 \
        --agent-env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
      ```

      ```bash Cursor theme={"system"}
      harbor run \
        -t hello-world/hello-world \
        --agent acp:cursor \
        --agent-env CURSOR_API_KEY="$CURSOR_API_KEY" \
        --agent-kwarg authenticate_method_id=cursor_login
      ```

      ```bash OpenCode theme={"system"}
      harbor run \
        -t hello-world/hello-world \
        --agent acp:opencode \
        --model openai/gpt-5.6-sol \
        --agent-env OPENAI_API_KEY="$OPENAI_API_KEY"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Config">
    ```json theme={"system"}
    {
      "agents": [
        {
          "name": "acp:codex-acp",
          "model_name": "openai/gpt-5.6-sol",
          "env": {"OPENAI_API_KEY": "${OPENAI_API_KEY}"},
          "kwargs": {"authenticate_method_id": "api-key"}
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    from harbor.models.trial.config import AgentConfig

    agent = AgentConfig(
        name="acp:codex-acp",
        model_name="openai/gpt-5.6-sol",
        env={"OPENAI_API_KEY": "${OPENAI_API_KEY}"},
        kwargs={"authenticate_method_id": "api-key"},
    )
    ```
  </Tab>
</Tabs>

Authentication references: [Codex ACP](https://github.com/agentclientprotocol/codex-acp#authentication),
[Claude](https://platform.claude.com/docs/en/manage-claude/authentication),
[Cursor ACP](https://cursor.com/docs/cli/acp#authentication), and
[OpenCode](https://opencode.ai/docs/providers).

## Common options

Pass these options with `--agent-kwarg` (`--ak`) or `agents[].kwargs`:

| Option                    | Default               | Purpose                                               |
| ------------------------- | --------------------- | ----------------------------------------------------- |
| `auth_policy`             | `auto`                | Use `auto`, `explicit`, or `disabled` authentication. |
| `authenticate_method_id`  | —                     | Select an ACP authentication method.                  |
| `permission_mode`         | `allow`               | Allow or deny ACP tool permission requests.           |
| `distribution_preference` | `binary,npx,uvx`      | Set the installation order.                           |
| `registry_ref`            | `main`                | Set the registry Git ref for unpinned agents.         |
| `registry_cache_dir`      | `.cache/acp-registry` | Set the local registry cache directory.               |

See the [ACP agent constructor](https://github.com/harbor-framework/harbor/blob/main/src/harbor/agents/installed/acp.py)
for all supported options.

<Accordion title="Use a local registry entry">
  Run the generic `acp` agent with a local `agent.json` file:

  ```yaml theme={"system"}
  agents:
    - name: acp
      kwargs:
        registry_entry_path: /path/to/agent.json
  ```
</Accordion>

## Output

ACP runs write `acp.txt`, `acp-events.jsonl`, `acp-summary.json`, and an
[ATIF trajectory](/core-concepts/agents/atif) named `trajectory.json` to the
agent log directory.