From 7199d8b45f426e2d4327d31ec21ff1185e5238cb Mon Sep 17 00:00:00 2001 From: Debug Agent Date: Mon, 16 Mar 2026 15:49:30 -0300 Subject: [PATCH] docs(sdk): document ACP remote conversation routing Co-authored-by: openhands --- sdk/guides/agent-acp.mdx | 20 ++++++++++++++++++++ sdk/guides/agent-server/api-sandbox.mdx | 8 ++++++++ 2 files changed, 28 insertions(+) diff --git a/sdk/guides/agent-acp.mdx b/sdk/guides/agent-acp.mdx index b693d9434..febba1c4f 100644 --- a/sdk/guides/agent-acp.mdx +++ b/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`. + + +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. + + ## 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 ``` + +On the agent-server side, the ACP-capable REST surface lives under `/api/acp/conversations`, including `POST`, `GET`, `search`, `batch get`, and `count`. + + ## Next Steps - **[Creating Custom Agents](/sdk/guides/agent-custom)** — Build specialized agents with custom tool sets and system prompts diff --git a/sdk/guides/agent-server/api-sandbox.mdx b/sdk/guides/agent-server/api-sandbox.mdx index 76d80eefa..fbe28bcb3 100644 --- a/sdk/guides/agent-server/api-sandbox.mdx +++ b/sdk/guides/agent-server/api-sandbox.mdx @@ -84,6 +84,14 @@ assert isinstance(conversation, RemoteConversation) All agent execution happens on the remote runtime infrastructure. + +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). + + + +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`. + + ## Ready-to-run Example