docs: fix agent-server Client SDK section with actual API

[VascoSch92]

Summary

This PR fixes the outdated "Client SDK" documentation in the Agent Server architecture page.

Problem

The documentation at https://docs.openhands.dev/sdk/arch/agent-server#client-sdk referenced a non-existent AgentServerClient class:

from openhands.client import AgentServerClient  # THIS MODULE DOES NOT EXIST

As reported in #495, there is no such client SDK module in the openhands-sdk or openhands-agent-server packages.

Solution

Replace the fictional client SDK documentation with the actual SDK usage patterns:

1. OpenHandsCloudWorkspace - For connecting to OpenHands Cloud
2. APIRemoteWorkspace - For custom runtime environments
3. RemoteConversation - The actual class returned when using remote workspaces

The new documentation shows the correct pattern where Conversation() factory automatically returns a RemoteConversation when given a remote workspace.

Testing

• Verified openhands.client module does not exist (ModuleNotFoundError)
• Verified RemoteConversation, OpenHandsCloudWorkspace, and APIRemoteWorkspace do exist and are importable
• New code examples match patterns used in existing guides (api-sandbox.mdx, cloud-workspace.mdx)

Fixes #495

---

This PR was created by an AI agent (OpenHands) on behalf of the user.

@VascoSch92 can click here to continue refining the PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	May 8, 2026, 7:29 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

🟢 Good taste - Successfully replaces fictional client SDK documentation with accurate workspace-based dispatch architecture.

The new content:

• Correctly documents the actual SDK components (RemoteConversation, workspace types)
• Follows architecture documentation guidelines (diagrams, component tables, links to source)
• Maintains clear separation between architecture (this page) and usage (linked guides)
• Resolves all previously identified issues

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Documentation-only change that corrects inaccurate information. No code changes, no breaking changes, no impact on functionality. The PR fixes a real problem (non-existent AgentServerClient) and replaces it with accurate architectural documentation.

VERDICT:
✅ Worth merging: Documentation is now accurate and follows best practices

KEY INSIGHT:
This PR demonstrates good engineering hygiene - fixing documentation to match reality rather than leaving users confused by references to non-existent APIs.

[all-hands-bot]

🟢 Good taste - Clean fix that replaces fictional client SDK documentation with accurate workspace-based dispatch architecture.

The PR successfully:

• Removes the non-existent AgentServerClient class documentation
• Adds proper architecture-focused content (workspace-based dispatch pattern)
• Includes Mermaid diagram showing the Conversation factory pattern
• Links all components to GitHub source files
• Documents RemoteConversation responsibilities clearly
• Links to usage guides for complete examples
• Follows architecture documentation guidelines

All previous review feedback has been incorporated. No issues found.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Documentation-only change that removes incorrect information and replaces it with verified, accurate architecture documentation. No code modified. All referenced classes verified to exist and be importable.

VERDICT:
✅ Worth merging: Fixes real documentation issue with accurate, well-structured architecture content.

KEY INSIGHT:
Elegant solution that transforms fictional API documentation into a clear architectural explanation of the workspace-based dispatch pattern - exactly what architecture docs should be.