OpenHands Software Agent SDK: the event-sourced, local-to-remote foundation underneath OpenHands V1
— views
A clean, modular Python/REST SDK for building code agents — the engine behind OpenHands V1, the CLI, and OpenHands Cloud. Event-sourced state, local-first with sandbox-on-demand, MCP tools. v1.26.0 shipped June 5, 2026.
pip install -U openhands-sdk openhands-toolsWhat it is
The OpenHands Software Agent SDK is a set of Python and REST APIs for building agents that work with code. It is the core of OpenHands V1 — a ground-up redesign that splits the agent core away from the apps built on top of it (the OpenHands CLI and OpenHands Cloud both run on this SDK). The repo is MIT-licensed and moves fast: the latest tag, v1.26.0, landed on June 5, 2026, on the heels of v1.25.0 (June 4) and v1.24.0 (May 27).
The pitch is that the same agent definition should run on your laptop for prototyping and inside a containerized sandbox in production with near-zero code changes. You compose an LLM, a list of typed Tools, and a Conversation bound to a workspace, then drive it with messages.
Why the architecture is interesting
The accompanying paper (arXiv 2511.03690, also an MLSys 2026 oral) lays out four design principles worth stealing even if you never adopt the SDK:
- Optional isolation — local-first, sandbox-on-demand. You only pay the Docker/Kubernetes tax when you actually need isolation.
- Stateless components with immutable config and event-sourced state, which buys you deterministic replay of a run.
- Strict separation between the agent core and the applications that consume it.
- Two-layer composability across four packages — SDK, Tools, Workspace, Server — with typed, swappable components and MCP integration.
Event-sourcing plus immutable configuration is the quiet headline. If every state transition is an appended event, you can replay a failed agent run deterministically instead of trying to reproduce a non-deterministic loop from logs.
Install and run
pip install -U openhands-sdk openhands-toolsThe docs are explicit that openhands-sdk and openhands-tools are a matched set — install and upgrade them in one command so versions stay aligned. For sandboxed workspaces and the bundled server, add openhands-workspace openhands-agent-server.
| Package | Role |
|---|---|
| openhands-sdk | Core agent/conversation/LLM APIs |
| openhands-tools | Built-in terminal, file-editor, task-tracker tools |
| openhands-workspace | Docker / remote sandboxed workspaces |
| openhands-agent-server | REST/WebSocket agent server |
A minimal run wires a terminal, file editor, and task tracker into one agent, points it at the current directory, and sends a single instruction — the agent plans, calls tools, and stops on its own.
Practitioner note
Treat the four-package split as the actual product, not boilerplate. Start with just openhands-sdk + openhands-tools against a local workspace to feel the loop, and only reach for openhands-workspace once you need to run untrusted edits in isolation. Because tools are typed and swappable with MCP support, you can drop in your own tool without forking the core — which is the difference between a library you extend and a harness you fight.
Under-considered angle
Most “agent SDK” coverage fixates on which model it calls. The more durable bet here is the event-sourced state model: deterministic replay turns flaky agent runs into reproducible artifacts you can diff, audit, and regression-test. That reframes an agent from a chat session into something closer to a build pipeline — which is exactly what teams need before they trust one to refactor real code.