Backup-bdg/OpenHands

1# OpenHands Server2 3This is a WebSocket server that executes tasks using an agent.4 5## Recommended Prerequisites6 7- [Initialize the frontend code](../../frontend/README.md)8- Install Python 3.12 (`brew install python` for those using homebrew)9- Install pipx: (`brew install pipx` followed by `pipx ensurepath`)10- Install poetry: (`pipx install poetry`)11 12## Install13 14First build a distribution of the frontend code (From the project root directory):15 16```sh17cd frontend18npm install19npm run build20cd ..21```22 23Next run `poetry shell` (So you don't have to repeat `poetry run`)24 25## Start the Server26 27```sh28uvicorn openhands.server.listen:app --reload --port 300029```30 31## Test the Server32 33You can use [`websocat`](https://github.com/vi/websocat) to test the server.34 35```sh36websocat ws://127.0.0.1:3000/ws37{"action": "start", "args": {"task": "write a bash script that prints hello"}}38```39 40## Supported Environment Variables41 42```sh43LLM_API_KEY=sk-... # Your Anthropic API Key44LLM_MODEL=claude-3-5-sonnet-20241022 # Default model for the agent to use45SANDBOX_VOLUMES=/path/to/your/workspace:/workspace:rw # Mount paths in format host_path:container_path:mode46```47 48## API Schema49 50There are two types of messages that can be sent to, or received from, the server:51 52* Actions53* Observations54 55### Actions56 57An action has three parts:58 59* `action`: The action to be taken60* `args`: The arguments for the action61* `message`: A friendly message that can be put in the chat log62 63There are several kinds of actions. Their arguments are listed below.64This list may grow over time.65 66* `initialize` - initializes the agent. Only sent by client.67  * `model` - the name of the model to use68  * `directory` - the path to the workspace69  * `agent_cls` - the class of the agent to use70* `start` - starts a new development task. Only sent by the client.71  * `task` - the task to start72* `read` - reads the content of a file.73  * `path` - the path of the file to read74* `write` - writes the content to a file.75  * `path` - the path of the file to write76  * `content` - the content to write to the file77* `run` - runs a command.78  * `command` - the command to run79* `browse` - opens a web page.80  * `url` - the URL to open81* `think` - Allows the agent to make a plan, set a goal, or record thoughts82  * `thought` - the thought to record83* `finish` - agent signals that the task is completed84 85### Observations86 87An observation has four parts:88 89* `observation`: The observation type90* `content`: A string representing the observed data91* `extras`: additional structured data92* `message`: A friendly message that can be put in the chat log93 94There are several kinds of observations. Their extras are listed below.95This list may grow over time.96 97* `read` - the content of a file98  * `path` - the path of the file read99* `browse` - the HTML content of a url100  * `url` - the URL opened101* `run` - the output of a command102  * `command` - the command run103  * `exit_code` - the exit code of the command104* `chat` - a message from the user105 106## Server Components107 108The following section describes the server-side components of the OpenHands project.109 110### 1. session/session.py111 112The `session.py` file defines the `Session` class, which represents a WebSocket session with a client. Key features include:113 114- Handling WebSocket connections and disconnections115- Initializing and managing the agent session116- Dispatching events between the client and the agent117- Sending messages and errors to the client118 119### 2. session/agent_session.py120 121The `agent_session.py` file contains the `AgentSession` class, which manages the lifecycle of an agent within a session. Key features include:122 123- Creating and managing the runtime environment124- Initializing the agent controller125- Handling security analysis126- Managing the event stream127 128### 3. session/conversation_manager/conversation_manager.py129 130The `conversation_manager.py` file defines the `ConversationManager` class, which is responsible for managing multiple client conversations. Key features include:131 132- Adding and restarting conversations133- Sending messages to specific conversations134- Cleaning up inactive conversations135 136### 4. listen.py137 138The `listen.py` file is the main server file that sets up the FastAPI application and defines various API endpoints. Key features include:139 140- Setting up CORS middleware141- Handling WebSocket connections142- Managing file uploads143- Providing API endpoints for agent interactions, file operations, and security analysis144- Serving static files for the frontend145 146## Workflow Description147 1481. **Server Initialization**:149   - The FastAPI application is created and configured in `listen.py`.150   - CORS middleware and static file serving are set up.151   - The `ConversationManager` is initialized.152 1532. **Client Connection**:154   - When a client connects via WebSocket, a new `Session` is created or an existing one is restarted.155   - The `Session` initializes an `AgentSession`, which sets up the runtime environment and agent controller.156 1573. **Agent Initialization**:158   - The client sends an initialization request.159   - The server creates and configures the agent based on the provided parameters.160   - The runtime environment is set up, and the agent controller is initialized.161 1624. **Event Handling**:163   - The `Session` manages the event stream between the client and the agent.164   - Events from the client are dispatched to the agent.165   - Observations from the agent are sent back to the client.166 1675. **File Operations**:168   - The server handles file uploads, ensuring they meet size and type restrictions.169   - File read and write operations are performed through the runtime environment.170 1716. **Security Analysis**:172   - If configured, a security analyzer is initialized for each session.173   - Security-related API requests are forwarded to the security analyzer.174 1757. **Session Management**:176   - The `ConversationManager` periodically cleans up inactive sessions.177   - It also handles sending messages to specific sessions when needed.178 1798. **API Endpoints**:180   - Various API endpoints are provided for agent interactions, file operations, and retrieving configuration defaults.181 182This server architecture allows for managing multiple client sessions, each with its own agent instance, runtime environment, and security analyzer. The event-driven design facilitates real-time communication between clients and agents, while the modular structure allows for easy extension and maintenance of different components.183