feat: Update SDK API to use Agent and Conversation aliases with explicit workspace creation

- Add Agent type alias for AgentBase to provide cleaner user-facing API
- Add Conversation const alias for RemoteConversation for consistency with Python SDK
- Update create/load methods to require explicit RemoteWorkspace parameter
- Modify ConversationManager to create RemoteWorkspace instances explicitly
- Update all examples and documentation to use new API pattern:
  - Use Agent instead of AgentBase
  - Use Conversation instead of RemoteConversation
  - Explicitly construct RemoteWorkspace objects
- Update example React app and basic usage examples
- Maintain backward compatibility by keeping original exports

This change aligns the TypeScript SDK more closely with the Python SDK
architecture and provides a more intuitive API for end users.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

README.md

@@ -21,19 +21,27 @@ npm install @openhands/agent-server-typescript-client
 ### Creating a Conversation
 
 ```typescript
-import { RemoteConversation, AgentBase } from '@openhands/agent-server-typescript-client';
+import { Conversation, Agent, RemoteWorkspace } from '@openhands/agent-server-typescript-client';
 
-const agent: AgentBase = {
-  name: 'CodeActAgent',
+const agent: Agent = {
+  kind: 'CodeActAgent',
   llm: {
     model: 'gpt-4',
     api_key: 'your-openai-api-key'
   }
 };
 
-const conversation = await RemoteConversation.create(
+// Create a remote workspace
+const workspace = new RemoteWorkspace({
+  host: 'http://localhost:3000',
+  workingDir: '/tmp',
+  apiKey: 'your-session-api-key'
+});
+
+const conversation = await Conversation.create(
   'http://localhost:3000', // Agent server URL
   agent,
+  workspace,
   {
     apiKey: 'your-session-api-key',
     initialMessage: 'Hello, can you help me write some code?',
@@ -54,9 +62,17 @@ await conversation.run();
 ### Loading an Existing Conversation
 
 ```typescript
-const conversation = await RemoteConversation.load(
+// Create a remote workspace for the existing conversation
+const workspace = new RemoteWorkspace({
+  host: 'http://localhost:3000',
+  workingDir: '/tmp',
+  apiKey: 'your-session-api-key'
+});
+
+const conversation = await Conversation.load(
   'http://localhost:3000',
   'conversation-id-here',
+  workspace,
   {
     apiKey: 'your-session-api-key'
   }

example/src/components/ConversationManager.tsx

@@ -2,8 +2,10 @@ import React, { useState, useEffect } from 'react';
 import { 
   ConversationManager as SDKConversationManager,
   ConversationInfo,
+  Conversation,
   RemoteConversation,
-  AgentBase,
+  Agent,
+  RemoteWorkspace,
   Event
 } from '@openhands/agent-server-typescript-client';
 import { useSettings } from '../contexts/SettingsContext';
@@ -118,7 +120,7 @@ export const ConversationManager: React.FC = () => {
   useEffect(() => {
     return () => {
       if (selectedConversation?.remoteConversation) {
-        selectedConversation.remoteConversation.stopWebSocketClient().catch(err => {
+        selectedConversation.remoteConversation.stopWebSocketClient().catch((err: any) => {
           console.warn('Failed to stop WebSocket client on unmount:', err);
         });
       }
@@ -190,17 +192,25 @@ export const ConversationManager: React.FC = () => {
     setError(null);
     try {
       // Create a simple agent configuration
-      const agent: AgentBase = {
+      const agent: Agent = {
         kind: 'Agent',
         llm: {
           model: settings.modelName,
           api_key: settings.apiKey || ''
         }
       };
 
-      const conversation = await RemoteConversation.create(
+      // Create a remote workspace
+      const workspace = new RemoteWorkspace({
+        host: manager.host,
+        workingDir: '/tmp',
+        apiKey: manager.apiKey
+      });
+
+      const conversation = await Conversation.create(
         manager.host,
         agent,
+        workspace,
         {
           apiKey: manager.apiKey,
           initialMessage: 'Hello! I\'m ready to help you with your tasks.',
@@ -320,10 +330,18 @@ export const ConversationManager: React.FC = () => {
         }
       };
 
+      // Create a remote workspace for the existing conversation
+      const workspace = new RemoteWorkspace({
+        host: manager.host,
+        workingDir: '/tmp',
+        apiKey: manager.apiKey
+      });
+
       // Load conversation with callback
-      const remoteConversation = await RemoteConversation.load(
+      const remoteConversation = await Conversation.load(
         manager.host,
         conversationId,
+        workspace,
         {
           apiKey: manager.apiKey,
           callback: eventCallback,

example/src/utils/serverStatus.ts

@@ -1,5 +1,5 @@
 import { Settings } from '../components/SettingsModal';
-import { HttpClient, RemoteConversation } from '@openhands/agent-server-typescript-client';
+import { HttpClient, RemoteConversation, RemoteWorkspace } from '@openhands/agent-server-typescript-client';
 
 export interface ServerStatus {
   isConnected: boolean;
@@ -51,6 +51,13 @@ export const testLLMConfiguration = async (settings: Settings): Promise<{ succes
       return { success: false, error: `Server not reachable: ${healthCheck.error}` };
     }
 
+    // Create a workspace for the test conversation
+    const workspace = new RemoteWorkspace({
+      host: settings.agentServerUrl,
+      workingDir: '/tmp/test-workspace',
+      apiKey: settings.agentServerApiKey,
+    });
+
     // Create a test conversation using the SDK
     const conversation = await RemoteConversation.create(
       settings.agentServerUrl,
@@ -61,13 +68,9 @@ export const testLLMConfiguration = async (settings: Settings): Promise<{ succes
           api_key: settings.apiKey,
         }
       },
+      workspace,
       {
         apiKey: settings.agentServerApiKey,
-        workspace: {
-          type: 'local',
-          path: '/tmp/test-workspace',
-          working_dir: '/tmp/test-workspace'
-        }
       }
     );
 

examples/basic-usage.ts

@@ -2,24 +2,32 @@
  * Basic usage example for the OpenHands Agent Server TypeScript Client
  */
 
-import { RemoteConversation, AgentBase, AgentExecutionStatus } from '../src/index.js';
+import { Conversation, Agent, RemoteWorkspace, AgentExecutionStatus } from '../src/index.js';
 
 async function main() {
   // Define the agent configuration
-  const agent: AgentBase = {
-    name: 'CodeActAgent',
+  const agent: Agent = {
+    kind: 'CodeActAgent',
     llm: {
       model: 'gpt-4',
       api_key: process.env.OPENAI_API_KEY || 'your-openai-api-key',
     },
   };
 
   try {
+    // Create a remote workspace
+    const workspace = new RemoteWorkspace({
+      host: 'http://localhost:3000',
+      workingDir: '/tmp',
+      apiKey: process.env.SESSION_API_KEY || 'your-session-api-key'
+    });
+
     // Create a new conversation
     console.log('Creating conversation...');
-    const conversation = await RemoteConversation.create(
+    const conversation = await Conversation.create(
       'http://localhost:3000', // Replace with your agent server URL
       agent,
+      workspace,
       {
         apiKey: process.env.SESSION_API_KEY || 'your-session-api-key',
         initialMessage: 'Hello! Can you help me write a simple Python script?',
@@ -80,9 +88,17 @@ async function main() {
 // Example of loading an existing conversation
 async function loadExistingConversation() {
   try {
-    const conversation = await RemoteConversation.load(
+    // Create a remote workspace for the existing conversation
+    const workspace = new RemoteWorkspace({
+      host: 'http://localhost:3000',
+      workingDir: '/tmp',
+      apiKey: process.env.SESSION_API_KEY || 'your-session-api-key'
+    });
+
+    const conversation = await Conversation.load(
       'http://localhost:3000',
       'existing-conversation-id',
+      workspace,
       {
         apiKey: process.env.SESSION_API_KEY || 'your-session-api-key',
       }

src/conversation/conversation-manager.ts

@@ -4,6 +4,7 @@
 
 import { HttpClient } from '../client/http-client';
 import { RemoteConversation } from './remote-conversation';
+import { RemoteWorkspace } from '../workspace/remote-workspace';
 import {
   ConversationInfo,
   ConversationSearchRequest,
@@ -86,20 +87,36 @@ export class ConversationManager {
       initialMessage?: string;
       maxIterations?: number;
       stuckDetection?: boolean;
-      workspace?: any;
+      workingDir?: string;
     } = {}
   ): Promise<RemoteConversation> {
-    return RemoteConversation.create(this.host, agent, {
+    // Create a workspace for the conversation
+    const workspace = new RemoteWorkspace({
+      host: this.host,
+      workingDir: options.workingDir || '/tmp',
       apiKey: this.apiKey,
-      ...options,
+    });
+
+    return RemoteConversation.create(this.host, agent, workspace, {
+      apiKey: this.apiKey,
+      initialMessage: options.initialMessage,
+      maxIterations: options.maxIterations,
+      stuckDetection: options.stuckDetection,
     });
   }
 
   /**
    * Load an existing conversation
    */
-  async loadConversation(conversationId: ConversationID): Promise<RemoteConversation> {
-    return RemoteConversation.load(this.host, conversationId, {
+  async loadConversation(conversationId: ConversationID, workingDir: string = '/tmp'): Promise<RemoteConversation> {
+    // Create a workspace for the existing conversation
+    const workspace = new RemoteWorkspace({
+      host: this.host,
+      workingDir,
+      apiKey: this.apiKey,
+    });
+
+    return RemoteConversation.load(this.host, conversationId, workspace, {
       apiKey: this.apiKey,
     });
   }

src/conversation/remote-conversation.ts

@@ -189,12 +189,12 @@ export class RemoteConversation {
   static async create(
     host: string,
     agent: AgentBase,
+    workspace: RemoteWorkspace,
     options: {
       apiKey?: string;
       initialMessage?: string;
       maxIterations?: number;
       stuckDetection?: boolean;
-      workspace?: any;
       callback?: ConversationCallbackType;
     } = {}
   ): Promise<RemoteConversation> {
@@ -220,7 +220,7 @@ export class RemoteConversation {
       initial_message: initialMessage,
       max_iterations: options.maxIterations || 50,
       stuck_detection: options.stuckDetection ?? true,
-      workspace: options.workspace || { type: 'local', working_dir: '/tmp' },
+      workspace: { type: 'local', working_dir: workspace.workingDir },
     };
 
     console.log('Full request object:', JSON.stringify(request, null, 2));
@@ -235,19 +235,16 @@ export class RemoteConversation {
       callback: options.callback,
     });
 
-    // Initialize workspace
-    conversation._workspace = new RemoteWorkspace({
-      host,
-      workingDir: conversationInfo.workspace?.working_dir || '/tmp',
-      apiKey: options.apiKey,
-    });
+    // Use the provided workspace
+    conversation._workspace = workspace;
 
     return conversation;
   }
 
   static async load(
     host: string,
     conversationId: string,
+    workspace: RemoteWorkspace,
     options: {
       apiKey?: string;
       callback?: ConversationCallbackType;
@@ -266,12 +263,8 @@ export class RemoteConversation {
     );
     const conversationInfo = response.data;
 
-    // Initialize workspace
-    conversation._workspace = new RemoteWorkspace({
-      host,
-      workingDir: conversationInfo.workspace?.working_dir || '/tmp',
-      apiKey: options.apiKey,
-    });
+    // Use the provided workspace
+    conversation._workspace = workspace;
 
     return conversation;
   }
@@ -284,3 +277,6 @@ export class RemoteConversation {
     }
   }
 }
+
+// Alias for user-facing API
+export const Conversation = RemoteConversation;

src/index.ts

@@ -6,7 +6,7 @@
  */
 
 // Main conversation and workspace classes
-export { RemoteConversation } from './conversation/remote-conversation';
+export { RemoteConversation, Conversation } from './conversation/remote-conversation';
 export { ConversationManager } from './conversation/conversation-manager';
 export { RemoteWorkspace } from './workspace/remote-workspace';
 export { RemoteState } from './conversation/remote-state';
@@ -33,6 +33,7 @@ export type {
   TextContent,
   ImageContent,
   AgentBase,
+  Agent,
   LLM,
   ServerInfo,
   Success,
@@ -75,7 +76,7 @@ export type { RemoteConversationOptions } from './conversation/remote-conversati
 export type { ConversationManagerOptions } from './conversation/conversation-manager';
 
 // Re-import for default export
-import { RemoteConversation } from './conversation/remote-conversation';
+import { RemoteConversation, Conversation } from './conversation/remote-conversation';
 import { ConversationManager } from './conversation/conversation-manager';
 import { RemoteWorkspace } from './workspace/remote-workspace';
 import { RemoteState } from './conversation/remote-state';
@@ -87,6 +88,7 @@ import { EventSortOrder, AgentExecutionStatus } from './types/base';
 // Default export for convenience
 export default {
   RemoteConversation,
+  Conversation,
   ConversationManager,
   RemoteWorkspace,
   RemoteState,

src/types/base.ts

@@ -79,6 +79,9 @@ export interface AgentBase {
   [key: string]: any;
 }
 
+// Alias for user-facing API
+export type Agent = AgentBase;
+
 export interface LLM {
   model: string;
   api_key?: string;