From 7dde6fa0efc3e198f82c31e3e90d59e036e9e8d3 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 8 May 2026 07:11:57 +0000 Subject: [PATCH 1/3] docs: fix agent-server Client SDK section with actual API Replace non-existent AgentServerClient documentation with actual SDK usage. The previous documentation referenced a 'Client SDK' with AgentServerClient class that does not exist. This update replaces it with: - OpenHandsCloudWorkspace for OpenHands Cloud integration - APIRemoteWorkspace for custom runtime environments - RemoteConversation which is the actual API for remote agent execution Fixes #495 Co-authored-by: openhands --- sdk/arch/agent-server.mdx | 66 ++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index 8dc62d5d3..6622399be 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -368,39 +368,55 @@ curl https://agent-server.example.com/health - Resource exhaustion - Container failures -## Client SDK +## Connecting to Agent Server -Python SDK for interacting with Agent Server: +The SDK provides workspace classes that connect to remote agent servers. When you use a remote workspace, the `Conversation` factory automatically returns a `RemoteConversation` that communicates with the server via HTTP/WebSocket. -```python -from openhands.client import AgentServerClient +### Using OpenHands Cloud -client = AgentServerClient( - url="https://agent-server.example.com", - api_key="your-api-key" -) +The simplest way to use a remote agent server is via OpenHands Cloud: -# Create conversation -conversation = client.create_conversation() +```python +from openhands.sdk import Conversation, RemoteConversation +from openhands.workspace import OpenHandsCloudWorkspace + +with OpenHandsCloudWorkspace( + cloud_api_url="https://app.all-hands.dev", + cloud_api_key="your-api-key", +) as workspace: + # Conversation automatically becomes RemoteConversation + conversation = Conversation(agent=agent, workspace=workspace) + assert isinstance(conversation, RemoteConversation) + + conversation.send_message("Hello, agent!") + conversation.run() +``` -# Send message -response = client.send_message( - conversation_id=conversation.id, - message="Hello, agent!" -) +### Using API-based Sandbox + +For custom runtime environments, use `APIRemoteWorkspace`: -# Stream responses -for event in client.stream_conversation(conversation.id): - if event.type == "message": - print(event.content) +```python +from openhands.sdk import Conversation, RemoteConversation +from openhands.workspace import APIRemoteWorkspace + +with APIRemoteWorkspace( + runtime_api_url="https://runtime.example.com", + runtime_api_key="your-api-key", + server_image="ghcr.io/openhands/agent-server:main-python", +) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) + assert isinstance(conversation, RemoteConversation) + + conversation.send_message("Hello, agent!") + conversation.run() ``` -**Client handles**: -- Authentication -- Request/response serialization -- Error handling -- Streaming -- Retries +**Remote workspaces handle**: +- Authentication and session management +- WebSocket streaming for real-time events +- Container lifecycle management +- Automatic reconnection and retries ## Cost Considerations From 69cc95155ecc4994b4d18f972b4b2a9249a3ad0a Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 8 May 2026 07:19:16 +0000 Subject: [PATCH 2/3] docs: refactor to architecture-focused content per review feedback - Replace usage examples with architecture diagram and pattern explanation - Add workspace types table showing dispatch behavior - Document RemoteConversation responsibilities - Link to existing guides for complete working examples Addresses review feedback about architecture docs focusing on design patterns rather than tutorial-style usage instructions. Co-authored-by: openhands --- sdk/arch/agent-server.mdx | 74 +++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 41 deletions(-) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index 6622399be..ea15bd347 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -368,55 +368,47 @@ curl https://agent-server.example.com/health - Resource exhaustion - Container failures -## Connecting to Agent Server +## Client Integration Architecture -The SDK provides workspace classes that connect to remote agent servers. When you use a remote workspace, the `Conversation` factory automatically returns a `RemoteConversation` that communicates with the server via HTTP/WebSocket. +The SDK implements a **workspace-based dispatch pattern** for connecting to agent servers. The `Conversation` factory inspects the workspace type and returns the appropriate conversation implementation. -### Using OpenHands Cloud - -The simplest way to use a remote agent server is via OpenHands Cloud: - -```python -from openhands.sdk import Conversation, RemoteConversation -from openhands.workspace import OpenHandsCloudWorkspace - -with OpenHandsCloudWorkspace( - cloud_api_url="https://app.all-hands.dev", - cloud_api_key="your-api-key", -) as workspace: - # Conversation automatically becomes RemoteConversation - conversation = Conversation(agent=agent, workspace=workspace) - assert isinstance(conversation, RemoteConversation) +```mermaid +flowchart LR + Conv["Conversation()"] --> Check{"Workspace Type?"} + Check -->|LocalWorkspace| Local["LocalConversation"] + Check -->|RemoteWorkspace| Remote["RemoteConversation"] + Remote -->|HTTP/WebSocket| Server["Agent Server"] - conversation.send_message("Hello, agent!") - conversation.run() + style Conv fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + style Remote fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + style Server fill:#fff4df,stroke:#b7791f,stroke-width:2px ``` -### Using API-based Sandbox +### Workspace Types -For custom runtime environments, use `APIRemoteWorkspace`: +| Workspace | Conversation Type | Communication | +|-----------|------------------|---------------| +| `LocalWorkspace` | `LocalConversation` | Direct execution | +| `OpenHandsCloudWorkspace` | `RemoteConversation` | HTTPS + WebSocket to OpenHands Cloud | +| `APIRemoteWorkspace` | `RemoteConversation` | HTTPS + WebSocket to Runtime API | +| `DockerWorkspace` | `RemoteConversation` | HTTP + WebSocket to local container | -```python -from openhands.sdk import Conversation, RemoteConversation -from openhands.workspace import APIRemoteWorkspace - -with APIRemoteWorkspace( - runtime_api_url="https://runtime.example.com", - runtime_api_key="your-api-key", - server_image="ghcr.io/openhands/agent-server:main-python", -) as workspace: - conversation = Conversation(agent=agent, workspace=workspace) - assert isinstance(conversation, RemoteConversation) - - conversation.send_message("Hello, agent!") - conversation.run() -``` +### RemoteConversation Responsibilities + +The `RemoteConversation` implementation handles all client-server concerns: + +- **Session management**: Authenticates and maintains connection to agent server +- **Event streaming**: WebSocket connection for real-time agent events +- **Request routing**: HTTP calls for conversation lifecycle operations +- **Reconnection**: Automatic retry logic for transient failures + +### Usage Examples + +For complete working examples with all required setup: -**Remote workspaces handle**: -- Authentication and session management -- WebSocket streaming for real-time events -- Container lifecycle management -- Automatic reconnection and retries +- **[OpenHands Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** - Managed cloud infrastructure +- **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Custom runtime environments +- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Local containerized execution ## Cost Considerations From 6d1d371f3fd160ec87a2b283f612fd72239afd2f Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 8 May 2026 08:18:50 +0000 Subject: [PATCH 3/3] docs: add GitHub source links to component names Per sdk-arch-guidelines.md, link every component name to its source file. Co-authored-by: openhands --- sdk/arch/agent-server.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index ea15bd347..6a6aa6cb0 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -388,12 +388,12 @@ flowchart LR | Workspace | Conversation Type | Communication | |-----------|------------------|---------------| -| `LocalWorkspace` | `LocalConversation` | Direct execution | -| `OpenHandsCloudWorkspace` | `RemoteConversation` | HTTPS + WebSocket to OpenHands Cloud | -| `APIRemoteWorkspace` | `RemoteConversation` | HTTPS + WebSocket to Runtime API | -| `DockerWorkspace` | `RemoteConversation` | HTTP + WebSocket to local container | +| [`LocalWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/local.py) | [`LocalConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py) | Direct execution | +| [`OpenHandsCloudWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/cloud/workspace.py) | [`RemoteConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py) | HTTPS + WebSocket to OpenHands Cloud | +| [`APIRemoteWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/remote_api/workspace.py) | [`RemoteConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py) | HTTPS + WebSocket to Runtime API | +| [`DockerWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/docker/workspace.py) | [`RemoteConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py) | HTTP + WebSocket to local container | -### RemoteConversation Responsibilities +### [`RemoteConversation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py) Responsibilities The `RemoteConversation` implementation handles all client-server concerns: