OpenHands / OpenHands/software-agent-sdk
[Feature]: Add a lightweight remote conversation control client
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 542
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Is there an existing feature request for this?
- I have searched existing issues and feature requests, and this is not a duplicate.
Problem or Use Case
Services that create and schedule remote agent work currently have to instantiate RemoteConversation. That client synchronizes conversation state and events, starts a WebSocket, and imports every agent tool package needed to deserialize the history. A scheduler only needs to create the conversation and submit work; requiring the full interactive client couples the scheduler process to the agent runtime's tools.
Desired Behavior
Add a small SDK control client for remote conversations. It should use the existing Agent Server API to create a conversation and submit a user turn while leaving state synchronization, event materialization, tool registration, and interactive callbacks to RemoteConversation.
The existing RemoteConversation methods should reuse the same request primitives where practical so the two clients do not duplicate transport behavior.
Acceptance Criteria
- A public Python SDK client can create an idempotently named remote conversation without constructing
RemoteConversationor loading agent/tool state. - The client can submit a user message and trigger the conversation run without opening a WebSocket.
- The client can read execution status so an existing scheduler or watchdog can observe completion.
- The client returns the conversation ID from creation and reports request failures with the existing SDK error behavior.
-
RemoteConversation.create(), message submission, and status reads reuse the same transport primitives where practical. - Focused tests prove the control path does not construct remote state or import tool modules.
- Public SDK documentation explains when to use the control client and when to use
RemoteConversation. - Existing Agent Server endpoints and the generated TypeScript client remain the source of truth; no duplicate endpoint or Automation-specific API is introduced.
Alternatives Considered
Adding a connect=False option to RemoteConversation.create() would make one method return two different abstractions. Installing every runtime tool package in scheduler processes would add unnecessary dependencies and erase the process boundary.
Priority / Severity
High - Significant impact on productivity
Estimated Scope
Small - Focused change with limited surface area
Feature Area
- SDK
Technical Implementation Ideas (Optional)
Model the control plane as a separate class bound to RemoteWorkspace. Keep the low-level HTTP request helpers shared with RemoteConversation and rely on the existing generated TypeScript endpoint methods for browser clients.
Additional Context
This enables schedulers and webhook services to launch agent work while keeping agent tools inside the provisioned runtime.
This issue was created by an AI agent (OpenHands) on behalf of the user.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing RemoteConversation and RemoteWorkspace, the existing Agent Server API request helpers, and the generated TypeScript endpoint methods. Identify the shared transport behavior before designing the separate control client. Done means creation, message submission, status reads, focused isolation tests, error handling, and public SDK documentation without WebSocket or tool-state loading.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, typescript
- Domain
- api, backend, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100