docs(sdk): document ACP remote conversation routing (OpenHands#399)

Co-authored-by: Debug Agent <debug@example.com>
Co-authored-by: openhands <openhands@all-hands.dev>

Author: 3 people

sdk/guides/agent-acp.mdx

@@ -41,6 +41,22 @@ Because the ACP server manages its own tools and context, these `AgentBase` feat
 
 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
@@ -266,6 +282,10 @@ cd software-agent-sdk
 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

@@ -84,6 +84,14 @@ assert isinstance(conversation, RemoteConversation)
 
 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>