audited local server

Author: xingyaoww

…ides/agent-server/local-agent-server.mdx sdk/guides/agent-server/local-server.mdxsdk/guides/agent-server/local-agent-server.mdx renamed to sdk/guides/agent-server/local-server.mdx sdk/guides/agent-server/local-agent-server.mdx renamed to sdk/guides/agent-server/local-server.mdx

@@ -3,7 +3,7 @@ title: Local Agent Server
 description: Run agents through a local HTTP server with RemoteConversation for client-server architecture.
 ---
 
-The Local Agent Server demonstrates how to run a remote agent server locally and connect to it using RemoteConversation. This enables separation between client code and agent execution, making it possible to run agents on dedicated servers or different machines.
+The Local Agent Server demonstrates how to run a remote agent server locally and connect to it using RemoteConversation. This pattern is useful for local development, testing, and scenarios where you want to separate the client code from the agent execution environment.
 
 ## Basic Example
 
@@ -294,20 +294,21 @@ The server starts with `python -m openhands.agent_server` and automatically hand
 
 ### Remote Workspace
 
-When using a remote server, you need to provide a `Workspace` that connects to that server:
+When connecting to a remote server, you need to provide a `Workspace` that connects to that server:
 
-```python highlight={157-158}
+```python
 workspace = Workspace(host=server.base_url)
 result = workspace.execute_command("pwd")
 ```
 
+When `host` is provided, the `Workspace` returns an instance of `RemoteWorkspace` ([source](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/workspace.py)).
 The `Workspace` object communicates with the remote server's API to execute commands and manage files.
 
 ### RemoteConversation
 
-When you pass a remote `Workspace` to `Conversation`, it automatically becomes a `RemoteConversation`:
+When you pass a remote `Workspace` to `Conversation`, it automatically becomes a `RemoteConversation` ([source](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py)):
 
-```python highlight={164-170}
+```python
 conversation = Conversation(
     agent=agent,
     workspace=workspace,
@@ -323,7 +324,7 @@ RemoteConversation handles communication with the remote agent server over WebSo
 
 Callbacks receive events in real-time as they happen on the remote server:
 
-```python highlight={148-153}
+```python
 def event_callback(event):
     """Callback to capture events for testing."""
     event_type = type(event).__name__
@@ -338,7 +339,7 @@ This enables monitoring agent activity, tracking progress, and implementing cust
 
 The conversation state provides access to all events and status:
 
-```python highlight={208-214}
+```python
 # Count total events using state.events
 total_events = len(conversation.state.events)
 logger.info(f"📈 Total events in conversation: {total_events}")
@@ -350,18 +351,8 @@ recent_events = all_events[-5:] if len(all_events) >= 5 else all_events
 
 This allows you to inspect the conversation history, analyze agent behavior, and build custom monitoring tools.
 
-## When to Use Local Agent Server
-
-The local agent server pattern is useful when you want to:
-
-- **Separate Concerns**: Keep client code separate from agent execution
-- **Development**: Test remote conversation features locally
-- **Multi-Client**: Allow multiple clients to connect to the same server
-- **Debugging**: Inspect server logs and behavior independently
-- **Preparation**: Prepare code for deploying to a real remote server
-
 ## Next Steps
 
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandboxed-server)** - Run server in Docker for isolation
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandboxed-server)** - Connect to hosted API service
-- **[Agent Server Architecture](/sdk/arch/agent_server/overview)** - Deep dive into server internals
+- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run server in Docker for isolation
+- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted API service
+- **[Agent Server Package Architecture](/sdk/arch/agent-server-package)** - Architecture and design decisions