{"id":4667,"library":"openhands-agent-server","title":"OpenHands Agent Server","description":"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.","status":"active","version":"1.16.1","language":"en","source_language":"en","source_url":"https://github.com/OpenHands/software-agent-sdk","tags":["ai-agent","server","rest-api","websocket","fastapi","sdk"],"install":[{"cmd":"pip install openhands-agent-server","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.12 or newer for compatibility.","package":"python","optional":false},{"reason":"Required for running the FastAPI application server.","package":"uvicorn","optional":false}],"imports":[{"note":"Used for programmatic access to the server's configuration settings if embedding or extending.","symbol":"AppConfig","correct":"from openhands_agent_server.config import AppConfig"},{"note":"The main FastAPI application instance is exposed through `main.py`, not `app.py` directly for import.","wrong":"from openhands_agent_server.app import app","symbol":"FastAPI","correct":"from openhands_agent_server.main import app"}],"quickstart":{"code":"import uvicorn\nimport os\n\n# Set any necessary environment variables for configuration (e.g., API keys)\n# For example, to configure an OpenAI key (replace with your actual key/method)\n# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'your-openai-api-key')\n\nif __name__ == \"__main__\":\n    # The server's main FastAPI application instance is named 'app' in 'openhands_agent_server.main'\n    print(\"Starting OpenHands Agent Server on http://0.0.0.0:8000\")\n    uvicorn.run(\"openhands_agent_server.main:app\", host=\"0.0.0.0\", port=8000, reload=True)","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.15.0"},{"fix":"Review the documentation for WebSocket client authentication and secrets management for versions v1.12.0 and later to ensure compatibility.","message":"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.","severity":"breaking","affected_versions":"<1.12.0"},{"fix":"Ensure your development and deployment environment uses Python 3.12 or a newer compatible version.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Prior to v1.13.0, `hook_config` in `RemoteConversation` might have been silently dropped, preventing server-side execution of remote conversation hooks.","severity":"gotcha","affected_versions":"<1.13.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}