OpenHands Agent Server

1.16.1 · active · verified Sun Apr 12

OpenHands Agent Server is the server-side component for OpenHands AI agents, providing RESTful and WebSocket APIs for agent interaction and management. It serves as the backbone for running and communicating with AI agents developed using the OpenHands Software Agent SDK. Currently at version 1.16.1, the library maintains an active development pace with minor versions released frequently.

Warnings

breaking Significant API changes and less stability guarantees existed prior to v1.15.0. Upgrades from older versions may require reviewing REST API endpoint changes and deprecations.
Fix: Consult the release notes and migration guides for versions between your current version and v1.15.0. Pay close attention to changes enforced by OpenAPI deprecations in v1.14.0.
breaking WebSocket authentication mechanisms and secrets handling were improved and changed in v1.12.0. Clients connecting via WebSocket might require updates to their authentication headers or secrets management.
Fix: Review the documentation for WebSocket client authentication and secrets management for versions v1.12.0 and later to ensure compatibility.
gotcha The library explicitly requires Python 3.12 or newer. Attempting to install or run on older Python versions will result in `Requires-Python` errors during installation or runtime issues.
Fix: Ensure your development and deployment environment uses Python 3.12 or a newer compatible version.
gotcha Prior to v1.13.0, `hook_config` in `RemoteConversation` might have been silently dropped, preventing server-side execution of remote conversation hooks.
Fix: If relying on server-side execution of `RemoteConversation` hooks, ensure you upgrade to v1.13.0 or a newer version to guarantee correct `hook_config` forwarding.

Install

pip install openhands-agent-server Install latest version

Imports

AppConfig
```
from openhands_agent_server.config import AppConfig
```
Used for programmatic access to the server's configuration settings if embedding or extending.
FastAPI
```
from openhands_agent_server.main import app
```
The main FastAPI application instance is exposed through `main.py`, not `app.py` directly for import.

Quickstart

This quickstart demonstrates how to programmatically start the OpenHands Agent Server using `uvicorn`. This is useful for embedding the server within a larger Python application or for custom deployment configurations. The server will be accessible at `http://0.0.0.0:8000`.

import uvicorn
import os

# Set any necessary environment variables for configuration (e.g., API keys)
# For example, to configure an OpenAI key (replace with your actual key/method)
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your-openai-api-key')

if __name__ == "__main__":
    # The server's main FastAPI application instance is named 'app' in 'openhands_agent_server.main'
    print("Starting OpenHands Agent Server on http://0.0.0.0:8000")
    uvicorn.run("openhands_agent_server.main:app", host="0.0.0.0", port=8000, reload=True)

view raw JSON →