Registry / llm-agents / openhands-agent-server

openhands-agent-server

library1.44.1pypypi✓ verified 22d ago

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.

llm-agents http-networking web-framework

pip install openhands-agent-server

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · OPENHANDS-AGENT-SE

openhands-agent-server

llm-agentspythonv1.44.1

Install

29.5s avg

Import

—

Disk

465MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.44.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

py 3.11

✕ build_error

py 3.12

✓ —

✓ 29.3s

py 3.13

✓ —

✓ 29.6s

py 3.9

✕ build_error

465MB installed

● package 465MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AppConfig

✓ from openhands_agent_server.config import AppConfig

✗ from openhands_agent_server.config import AppConfig

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)

Debug

Known issues

breakingSignificant 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.

affects: <1.15.0

breakingWebSocket 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.

affects: <1.12.0

gotchaThe 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.

affects: All versions

gotchaPrior 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.

affects: <1.13.0

Upgrade

Version history

1.44.1latest on PyPI · released Aug 28, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.12 or newer for compatibility.

uvicornrequiredRequired for running the FastAPI application server.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/OpenHands/software-agent-sdk ↗

packagehttps://pypi.org/project/openhands-agent-server/ ↗

docshttps://docs.openhands.dev/sdk ↗