ACP
Driving an external Agent Client Protocol harness from Harmony, and why its capabilities are negotiated rather than assumed.
ACP is the outbound direction. Harmony acts as a client, driving an external harness that speaks the Agent Client Protocol.
This is the opposite of MCP, where Harmony is the server and other agents call in. Both point outward; only one of them points from Harmony.
| Direction | Harmony is | |
|---|---|---|
| MCP | Other agents → Harmony | The server |
| ACP | Harmony → other harness | The client |
See MCP for the inbound side.
What it is for
Running a harness Harmony does not ship — including one you maintain yourself — while keeping it inside the workspace, with tasks, artifacts, and A2A.
The harness stays an independent program. Harmony drives it over a consolidated JSON-RPC-on-stdio client.
Capabilities are negotiated
This is the part that behaves differently from everything else in Harmony.
A harness's session capabilities — such as sessionList and sessionClose —
are negotiated at handshake and reported on the launch card as they were
actually negotiated.
IMPORTANT
The same harness can present different capabilities on different machines or versions. Trust the launch card over documentation, including this page. What was negotiated is what you have.
That is why the capability matrix cannot list ACP harness capabilities as fixed values — they are a runtime property, not a static fact.
Credential isolation
A user-managed harness runs with credential isolation: its credentials are not shared with other providers in the workspace, and the Harmony agent cannot read them.
SECURITY
If an external harness fails to authenticate while first-party providers work, that boundary is usually the reason. It is intended behaviour. Supply its credentials through its own configuration rather than looking for a way around the isolation.
This is the same principle as everywhere else in Harmony: credentials belong to the thing that owns them. See account and authentication.
Adding a harness
An ACP harness is a user-managed provider. You are responsible for installing it, authenticating it, and keeping it current — Harmony drives it, it does not maintain it.
Practical guidance:
- Verify it runs standalone before involving Harmony. A harness that fails on its own will fail under Harmony, with an extra layer between you and the error.
- Check the launch card for negotiated capabilities rather than assuming.
- Treat its output as untrusted, exactly like any provider's.
Limitations
| Limitation | Detail |
|---|---|
| Capabilities vary | Negotiated per handshake, not fixed |
| Not sandboxed | The harness runs with real privileges |
| Harmony does not manage its updates | User-managed means user-maintained |
| Failures surface as transport errors | The harness's own error may be more specific |
NOTE
When an ACP harness misbehaves, read the harness's own output. Harmony reports that the call failed; the harness usually knows why.
Related
- MCP — the inbound direction
- Customization overview
- Capability matrix