feat: Add ACPAgent for Agent Client Protocol integration (#2133)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Engel Nyst <engel.nyst@gmail.com>
Co-authored-by: Xingyao Wang <xingyao@all-hands.dev>

Author: 4 people

examples/01_standalone_sdk/40_acp_agent_example.py

@@ -0,0 +1,35 @@
+"""Example: Using ACPAgent with Claude Code ACP server.
+
+This example shows how to use an ACP-compatible server (claude-code-acp)
+as the agent backend instead of direct LLM calls.
+
+Prerequisites:
+    - Node.js / npx available
+    - Claude Code CLI authenticated (or CLAUDE_API_KEY set)
+
+Usage:
+    uv run python examples/01_standalone_sdk/40_acp_agent_example.py
+"""
+
+import os
+
+from openhands.sdk.agent import ACPAgent
+from openhands.sdk.conversation import Conversation
+
+
+agent = ACPAgent(acp_command=["npx", "-y", "claude-code-acp"])
+
+try:
+    cwd = os.getcwd()
+    conversation = Conversation(agent=agent, workspace=cwd)
+
+    conversation.send_message(
+        "List the Python source files under openhands-sdk/openhands/sdk/agent/, "
+        "then read the __init__.py and summarize what agent classes are exported."
+    )
+    conversation.run()
+finally:
+    # Clean up the ACP server subprocess
+    agent.close()
+
+print("Done!")

openhands-sdk/openhands/sdk/agent/__init__.py

@@ -1,8 +1,28 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from openhands.sdk.agent.agent import Agent
 from openhands.sdk.agent.base import AgentBase
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.agent.acp_agent import ACPAgent
+
+
+# Lazy import: eagerly importing ACPAgent registers it in the
+# DiscriminatedUnionMixin, which makes `kind` required in Agent payloads
+# that previously defaulted.
+def __getattr__(name: str):
+    if name == "ACPAgent":
+        from openhands.sdk.agent.acp_agent import ACPAgent
+
+        return ACPAgent
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     "Agent",
     "AgentBase",
+    "ACPAgent",
 ]