ACP

Run agents from the Agent Client Protocol registry.

Harbor’s generic acp integration installs and runs agents from the ACP Registry inside the task environment. ACP provides a common protocol between clients and agents.

--agent acp:... selects an ACP registry agent. It is different from --bridge acp, which connects a simulated user to the target agent.

Run a registry agent

Harbor supports all acp agents in the ACP Registry Github or ACP 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.

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.

CLI

Codex

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

Config

{
  "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"}
    }
  ]
}

Python

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"},
)

Authentication references: Codex ACP, Claude, Cursor ACP, and OpenCode.

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 for all supported options.

Use a local registry entry

Run the generic acp agent with a local agent.json file:

agents:
  - name: acp
    kwargs:
      registry_entry_path: /path/to/agent.json

Output

ACP runs write acp.txt, acp-events.jsonl, acp-summary.json, and an ATIF trajectory named trajectory.json to the agent log directory.