The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents

OpenHands is an open-source platform for software agents. Its first architecture, which the authors call V0, assumed every tool call ran inside a sandboxed Docker container, separate from the process running the agent. That meant every conversation spanned two processes whose state could diverge. When the sandbox crashed and the agent kept going, or the reverse, the session was corrupted. Local execution, which the Model Context Protocol assumes, had to be bolted on with duplicate tool and MCP code. Configuration had grown to more than 140 fields across 15 classes and 2,800 lines, spread over separate hierarchies for the CLI, web UI, GitHub App and hosted service.

V1, the Software Agent SDK, rests on four rules. Isolation is optional: the agent runs in-process by default and moves into a container when you need one. Everything is immutable except one object: agents, tools and model settings are frozen Pydantic models, and a single ConversationState holds all mutable data. The agent core is a library that applications import rather than a codebase they share. Components are typed and replaceable, so a new tool or agent does not touch the core.

The state is event-sourced. Every message, tool call, observation, pause and condensation is an immutable event appended to a log, with each event persisted as its own JSON file and metadata in one base_state.json. Resuming a conversation means loading the metadata and replaying the events. The same Conversation(...) call runs locally against a folder, or, given a Docker or hosted workspace, serializes the agent to an agent server that runs it in a container and streams events back over WebSocket.

The paper backs this with production data. V0 and V1 served users side by side for 15 days, and failures attributable to the system rather than to model providers fell from 78.0 to 30.0 per 1,000 conversations.

If you have built an agent demo, you have built the V0 problems in small. A loop calls a model, a tool runs somewhere, and the only record of what happened is a list in memory. That works until the process dies halfway through a two-hour job, a customer asks why the agent deleted a file, or a second entry point (a Slack bot, a scheduled job) needs the same agent with slightly different settings.

The paper is a worked answer to three questions you will face when a pilot becomes a service.

Where does the truth live? One append-only log per conversation, written as it happens. It is your resume point, your audit trail and your debugging tool, and the paper measures its cost as negligible next to model calls.

What may change at runtime? Nothing except that log and a few status fields. Freezing configuration at construction is what made two runs with the same settings behave the same.

Where does the code run? Locally by default, in a container when a customer's security team or a multi-tenant service requires it, with the same agent code in both.

Read the production numbers carefully. Most of the 61% came from removing network calls between two Kubernetes pods. The authentication failures between those pods alone were 43.0 per 1,000 conversations. The lesson for your own deployment is to count the processes and network hops each agent step crosses. Each one is a failure mode that a better model cannot fix.