docs(sdk): document ACP remote conversation routing

sdk/guides/agent-acp.mdx

@@ -5,7 +5,7 @@
 
 > A ready-to-run example is available [here](#ready-to-run-example)!
 
 `ACPAgent` lets you use any [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview) server as the backend for an OpenHands conversation. Instead of calling an LLM directly, the agent spawns an ACP server subprocess and communicates with it over JSON-RPC. The server manages its own LLM, tools, and execution — your code just sends messages and collects responses.
 
 ## Basic Usage
 
@@ -41,6 +41,22 @@
 
 Passing any of these raises `NotImplementedError` at initialization.
 
+## ACPAgent with RemoteConversation
+
+`ACPAgent` also works with remote agent-server deployments such as `APIRemoteWorkspace`, `DockerWorkspace`, and other `RemoteWorkspace`-backed setups.
+
+When `RemoteConversation` detects an `ACPAgent`, it automatically uses the ACP-capable conversation routes for:
+
+- conversation creation
+- conversation info reads
+- conversation counting
+
+The rest of the lifecycle, including events, runs, pauses, and secrets, continues to use the standard agent-server routes. This keeps the existing remote execution flow intact while isolating the schema-sensitive ACP contract under `/api/acp/conversations`.
+
+<Warning>
+If you attach to an existing conversation by `conversation_id`, use `ACPAgent` for ACP-backed conversations. Attaching with a regular `Agent` to an ACP conversation ID is rejected explicitly to avoid mixing the standard and ACP conversation contracts.
+</Warning>
+
 ## How It Works
 
 - **Subprocess delegation**: `ACPAgent` spawns the ACP server and communicates via JSON-RPC over stdin/stdout
@@ -84,7 +100,7 @@
 
 ## Cleanup
 
 Always call `agent.close()` when you are done to terminate the ACP server subprocess. A `try/finally` block is recommended:
 
 ```python icon="python"
 agent = ACPAgent(acp_command=["npx", "-y", "claude-code-acp"])
@@ -165,7 +181,7 @@
 This example is available on GitHub: [examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py)
 </Note>
 
 This example shows how to run an ACPAgent in a remote sandboxed environment via the Runtime API, using `APIRemoteWorkspace`:
 
 ```python icon="python" expandable examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py
 """Example: ACPAgent with Remote Runtime via API.
@@ -266,6 +282,10 @@
 uv run python examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py
 ```
 
+<Note>
+On the agent-server side, the ACP-capable REST surface lives under `/api/acp/conversations`, including `POST`, `GET`, `search`, `batch get`, and `count`.
+</Note>
+
 ## Next Steps
 
 - **[Creating Custom Agents](/sdk/guides/agent-custom)** — Build specialized agents with custom tool sets and system prompts

sdk/guides/agent-server/api-sandbox.mdx

@@ -6,7 +6,7 @@
 > A ready-to-run example is available [here](#ready-to-run-example)!
 
 
 The API-sandboxed agent server demonstrates how to use `APIRemoteWorkspace` to connect to a [OpenHands runtime API service](https://runtime.all-hands.dev/). This eliminates the need to manage your own infrastructure, providing automatic scaling, monitoring, and secure sandboxed execution.
 
 ## Key Concepts
 
@@ -24,7 +24,7 @@
 
 This workspace type:
 - Connects to a remote runtime API service
 - Automatically provisions sandboxed environments
 - Manages container lifecycle through the API
 - Handles all infrastructure concerns
 
@@ -84,6 +84,14 @@
 
 All agent execution happens on the remote runtime infrastructure.
 
+<Note>
+The same runtime flow also supports `ACPAgent`. For an end-to-end example, see the [ACP Agent guide](/sdk/guides/agent-acp#remote-runtime-example).
+</Note>
+
+<Warning>
+ACP-backed remote conversations use the ACP-capable conversation endpoints under `/api/acp/conversations` for creation, reads, and counts. If you reconnect to an existing ACP conversation by `conversation_id`, use `ACPAgent` rather than a standard `Agent`.
+</Warning>
+
 ## Ready-to-run Example
 
 <Note>