OpenHands / OpenHands/software-agent-sdk

[Feature]: Add a lightweight remote conversation control client

Open
#5,080 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement ready-for-dev
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 RemoteConversation or 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.