Skip to content

ACP (Agent-Client Protocol) Setup Runbook

Ultimate Harness provides native support for ACP v1 (Agent-Client Protocol), allowing UH to orchestrate external ACP-compliant agent processes (e.g. OpenHands, Zed agents, or custom ACP servers) through standard JSON-RPC 2.0 over standard I/O.


  1. An executable agent that implements ACP v1 (reads JSON-RPC on stdin, writes on stdout).
  2. The agent command accessible in PATH or configured via server_command.

The adapter manifest is located at .harness/adapters/acp.yaml.

schema_version: uh.adapter.v0
id: acp
name: Agent-Client Protocol (ACP)
description: Native ACP v1 runner for headless agent orchestration
runtime: acp
capabilities:
- cli-execution
- json-output
- diff-output
status: active
config:
server_command: acp-agent
server_args: []
protocol_version: 1
timeout_ms: 600000
  • server_command (string, default: "acp-agent"): The binary or script invoked by UH.
  • server_args (string[], default: []): Command line arguments passed to the ACP server.
  • protocol_version (integer, default: 1): ACP protocol version (v1).
  • timeout_ms (integer, default: 600000): Per-request timeout in milliseconds.
  • mcp_servers (array, default: []): MCP servers advertised to the agent in session/new. Each entry is either a stdio server ({ name, command, args?, env? }) or an HTTP server ({ type: "http", name, url, headers? }). UH maps these to the ACP v1 wire shape and never writes server env or headers values into any artifact.
  • env (object, default: { set: {}, drop: [] }): Environment policy for the agent process. drop removes exact variable names or NAME_PREFIX* patterns from a copy of process.env; set then adds/replaces values, so set wins over drop. Names compare case-insensitively on Windows. Values are never written into any artifact.

A value in mcp_servers headers or env, or in env.set, may contain ${NAME}, which UH replaces from the environment when the run starts. Keep tokens that way: the adapter file then names the variable and never holds the secret, and a variable that is not set stops the run with a message naming it. Set the variable in your shell, not in a file under the project.

config:
server_command: prime-agent
server_args: ["--mode", "acp"]
mcp_servers:
- name: files
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem"]
env:
FS_ROOT: .
- type: http
name: remote
url: https://example.test/mcp
headers:
Authorization: "Bearer ${ACP_MCP_TOKEN}"
env:
set:
DO_NOT_TRACK: "1"
drop:
- "ORCA_*"

In your mission packet:

schema_version: uh.mission.v0
id: sample-acp-mission
title: "Run task via ACP"
workflow_profile: bugfix-contained
runtime_config_overrides:
server_command: my-acp-binary
timeout_ms: 300000

Execute with:

Terminal window
uh mission run .harness/missions/sample-acp-mission/mission.yaml --runtime acp

ACP is also a first-class team worker adapter:

schema_version: uh.mission.v0
id: sample-team-acp
shape: team
team:
leader:
adapter: command-code
role: leader
workers:
- adapter: acp
role: worker-acp
objective: "Implement headless task via ACP"

When UH executes an ACP mission:

  1. It validates the ACP handshake (initialize).
  2. Spawns the agent within the isolated sandbox boundary.
  3. Services agent-to-client permission requests (session/request_permission) according to harness policy.
  4. Records canonical run facts (runtime-result.yaml, diff.patch, stdout, stderr, and runs/index.json).