Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

docs: UHP in the agent protocol ecosystem, a page on where it sits beside MCP, A2A, ACP and AG-UI (#511)

Lenin Mookiah7f3cf64e7e08
diff --git a/protocol/ECOSYSTEM.md b/protocol/ECOSYSTEM.md
new file mode 100644
index 00000000..e910980f
--- /dev/null
+++ b/protocol/ECOSYSTEM.md
@@ -0,0 +1,21 @@
+# UHP in the agent protocol ecosystem
+
+This page is informative, not part of the UHP specification. The protocols below connect different parts of an agent system; the picture illustrates their roles, not a required architecture or a guarantee that every implementation interoperates.
+
+![Protocol roles: UHP connects a product to a harness; MCP connects an agent to tools and data; A2A connects agents; ACP connects an editor to a coding agent; AG-UI connects a front end to an agent.](./assets/protocol-layers.svg)
+
+## What each protocol connects
+
+**[MCP (Model Context Protocol)](https://modelcontextprotocol.io/specification)** connects an AI application or agent to tools, data and other context exposed by servers. It describes what an agent can access or call, rather than the whole task a product asks a harness to run.
+
+**[A2A (Agent2Agent Protocol)](https://a2a-protocol.org/latest/specification/)** connects agents so they can discover capabilities, delegate work and exchange results. Its boundary is collaboration between agents, rather than a product choosing and driving a harness.
+
+**[ACP (Agent Client Protocol)](https://agentclientprotocol.com/)** connects an editor or other client to a coding agent, including the interaction around a coding session. Here ACP means *Agent Client Protocol*, not the unrelated *Agent Communication Protocol*.
+
+**[AG-UI (Agent User Interaction Protocol)](https://docs.ag-ui.com/)** connects an agent to a front end through events used to present its work and support user interaction. It describes that interaction boundary, rather than how a server runs interchangeable harnesses.
+
+**[UHP (Unified Harness Protocol)](versions/2026-10-19/index.md)** connects a product to a complete agent harness running a task. Its contract covers tasks, sessions, streaming, files and the results a client retrieves, while the harness owns its agent loop and tools.
+
+## How they can combine
+
+A product can submit a task through UHP to a server whose harness calls MCP tools: UHP's [Plugins chapter](versions/2026-10-19/plugins.md) describes how plugins carry MCP servers for the harness. An ACP adapter can also sit behind the UHP boundary; this repository's [ZeroClaw driver](https://github.com/HarnessRouter/harnessrouter/blob/fdadc18bab07c8b5212371d4dfc2dc4893896802/runner/zeroclaw_driver.py) starts the harness's own ACP server over standard input/output. A front end can use AG-UI events around an agent, and agents can collaborate through A2A, where those components support them. These are possible combinations, not features UHP requires every server to implement.
diff --git a/protocol/README.md b/protocol/README.md
index 4982a7a2..4e754728 100644
--- a/protocol/README.md
+++ b/protocol/README.md
@@ -34,6 +34,8 @@ out, tools you have to run yourself. UHP gives you a *task*: work in, and a runn
its own tools, keeps its own session, and hands back results and files. The unit of exchange is a
job, not a completion.
+See [UHP in the agent protocol ecosystem](ECOSYSTEM.md) for how UHP fits alongside MCP, A2A, ACP and AG-UI.
+
## Status of this document
| | |
diff --git a/protocol/assets/protocol-layers.svg b/protocol/assets/protocol-layers.svg
new file mode 100644
index 00000000..3a84ef1e
--- /dev/null
+++ b/protocol/assets/protocol-layers.svg
@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="660" viewBox="0 0 920 660" role="img" aria-labelledby="title desc" style="color-scheme:only light">
+<title id="title">Five protocols, five connection boundaries</title>
+<desc id="desc">UHP connects a product and a harness. MCP connects an AI application or agent to tools and data. A2A connects agents. ACP connects an editor or client to a coding agent. AG-UI connects a front end to an agent. The rows show roles, not a required stack.</desc>
+<rect width="920" height="660" rx="16" fill="#f8fafc"/>
+<g font-family="sans-serif" fill="#0f172a">
+<text x="40" y="48" font-size="26" font-weight="700">Different protocols connect different boundaries</text>
+<text x="40" y="78" font-size="16" fill="#475569">Roles are illustrative; this is not a required stack.</text>
+<rect x="30" y="105" width="860" height="91" rx="10" fill="#dbeafe" stroke="#cbd5e1"/>
+<text x="50" y="138" font-size="21" font-weight="700">UHP</text>
+<text x="180" y="138" font-size="19">Product</text>
+<path d="M 435 131 H 530 M 435 131 l 9 -6 M 435 131 l 9 6 M 530 131 l -9 -6 M 530 131 l -9 6" fill="none" stroke="#2563eb" stroke-width="2"/>
+<text x="555" y="138" font-size="19">Harness</text>
+<text x="180" y="171" font-size="16" fill="#475569">Tasks, sessions, streaming, files</text>
+<rect x="30" y="206" width="860" height="91" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+<text x="50" y="239" font-size="21" font-weight="700">MCP</text>
+<text x="180" y="239" font-size="19">AI application / agent</text>
+<path d="M 435 232 H 530 M 435 232 l 9 -6 M 435 232 l 9 6 M 530 232 l -9 -6 M 530 232 l -9 6" fill="none" stroke="#2563eb" stroke-width="2"/>
+<text x="555" y="239" font-size="19">Tools and data</text>
+<text x="180" y="272" font-size="16" fill="#475569">Tools, resources and context</text>
+<rect x="30" y="307" width="860" height="91" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+<text x="50" y="340" font-size="21" font-weight="700">A2A</text>
+<text x="180" y="340" font-size="19">Agent</text>
+<path d="M 435 333 H 530 M 435 333 l 9 -6 M 435 333 l 9 6 M 530 333 l -9 -6 M 530 333 l -9 6" fill="none" stroke="#2563eb" stroke-width="2"/>
+<text x="555" y="340" font-size="19">Agent</text>
+<text x="180" y="373" font-size="16" fill="#475569">Delegation and collaboration</text>
+<rect x="30" y="408" width="860" height="91" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+<text x="50" y="441" font-size="21" font-weight="700">ACP</text>
+<text x="180" y="441" font-size="19">Editor / client</text>
+<path d="M 435 434 H 530 M 435 434 l 9 -6 M 435 434 l 9 6 M 530 434 l -9 -6 M 530 434 l -9 6" fill="none" stroke="#2563eb" stroke-width="2"/>
+<text x="555" y="441" font-size="19">Coding agent</text>
+<text x="180" y="474" font-size="16" fill="#475569">Coding-session interaction</text>
+<rect x="30" y="509" width="860" height="91" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+<text x="50" y="542" font-size="21" font-weight="700">AG-UI</text>
+<text x="180" y="542" font-size="19">Front end</text>
+<path d="M 435 535 H 530 M 435 535 l 9 -6 M 435 535 l 9 6 M 530 535 l -9 -6 M 530 535 l -9 6" fill="none" stroke="#2563eb" stroke-width="2"/>
+<text x="555" y="542" font-size="19">Agent</text>
+<text x="180" y="575" font-size="16" fill="#475569">Events and user interaction</text>
+<text x="40" y="640" font-size="14" fill="#475569">ACP here means Agent Client Protocol.</text>
+</g></svg>
diff --git a/protocol/site/build.py b/protocol/site/build.py
index e6515a07..d8e0ef17 100644
--- a/protocol/site/build.py
+++ b/protocol/site/build.py
@@ -185,6 +185,7 @@ def inject_levels(examples_html: str) -> str:
NAV = [
("Introduction", [
("index.html", "What is UHP?", ROOT / "README.md"),
+ ("ecosystem.html", "Protocol ecosystem", ROOT / "ECOSYSTEM.md"),
]),
("Specification", [
(f"spec/{VERSION}/{name}.html", title, ROOT / f"versions/{VERSION}/{name}.md")
@@ -218,6 +219,9 @@ EXTRA = [
# metadata manifest: build() asserts every page has one, they are unique, and lengths sit in the
# 100–170 band that renders whole in Google, Bing, and the AI-engine retrieval snippets.
DESCRIPTIONS = {
+ "ecosystem.html":
+ "How UHP fits alongside MCP, A2A, Agent Client Protocol and AG-UI: the boundaries "
+ "each connects and examples of combining them in an agent system.",
"index.html":
"The Unified Harness Protocol (UHP) is an open standard for running complete agent "
"harnesses — tasks, sessions, streaming, files — through one shared contract.",
@@ -752,6 +756,8 @@ def rewrite_links(html_text: str, depth: int, version: str = VERSION) -> str:
(r'href="(?:\.\./)*SERVING\.md"', f'href="{up}serving"'),
(r'href="(?:\.\./)*CONNECTING\.md"', f'href="{up}connecting"'),
(r'href="(?:\.\./)*IMPLEMENTATIONS\.md"', f'href="{up}examples"'),
+ (r'href="(?:\.\./)*ECOSYSTEM\.md#([^"]+)"', rf'href="{up}ecosystem#\1"'),
+ (r'href="(?:\.\./)*ECOSYSTEM\.md"', f'href="{up}ecosystem"'),
(r'href="(?:\.\./)*conformance/README\.md#([^"]+)"', rf'href="{up}conformance#\1"'),
(r'href="(?:\.\./)*conformance/README\.md"', f'href="{up}conformance"'),
(r'href="reports/([^"]+\.json)"', rf'href="{up}reports/\1"'), # measured evidence files