ACP Registry Agents

Harbor can run agents from the ACP registry through the built-in generic acp runner.

CLI

Use the acp:<id>[@version] shorthand anywhere --agent is accepted:

harbor run \
  --path examples/tasks/hello-world \
  --agent acp:opencode@1.3.9 \
  --model openai/gpt-5.4 \
  --ae OPENAI_API_KEY=$OPENAI_API_KEY

If the version is omitted, Harbor resolves the latest agent.json from the registry's main branch during agent setup.

Config Files

The same shorthand works in YAML or JSON configs and is preserved in the persisted config.json:

agents:
  - name: acp:opencode@1.3.9
    model_name: openai/gpt-5.4
    kwargs:
      auth_policy: auto
      permission_mode: allow

SDK

SDK users can use the same declarative agent name:

from harbor.models.trial.config import AgentConfig

agent = AgentConfig(
    name="acp:opencode@1.3.9",
    model_name="openai/gpt-5.4",
    env={"OPENAI_API_KEY": "${OPENAI_API_KEY}"},
)

Registry resolution happens asynchronously in AcpAgent.setup(), so creating configs and agents does not perform network I/O.

Options

Common ACP kwargs:

• auth_policy: auto, explicit, or disabled
• permission_mode: allow or deny
• distribution_preference: comma-separated preference among binary, npx, and uvx
• registry_ref: ACP registry git ref for latest-version resolution
• registry_cache_dir: local cache directory for fetched registry entries

You can also run the generic ACP agent with an explicit registry entry:

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

Outputs

ACP runs write these files under the agent log directory:

• acp.txt
• acp-events.jsonl
• acp-summary.json
• trajectory.json

Because Harbor generates trajectory.json, standard trace export works:

harbor traces export -p jobs/<job-name> --recursive