The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents (2511.03690v1)

Abstract: Agents are now used widely in the process of software development, but building production-ready software engineering agents is a complex task. Deploying software agents effectively requires flexibility in implementation and experimentation, reliable and secure execution, and interfaces for users to interact with agents. In this paper, we present the OpenHands Software Agent SDK, a toolkit for implementing software development agents that satisfy these desiderata. This toolkit is a complete architectural redesign of the agent components of the popular OpenHands framework for software development agents, which has 64k+ GitHub stars. To achieve flexibility, we design a simple interface for implementing agents that requires only a few lines of code in the default case, but is easily extensible to more complex, full-featured agents with features such as custom tools, memory management, and more. For security and reliability, it delivers seamless local-to-remote execution portability, integrated REST/WebSocket services. For interaction with human users, it can connect directly to a variety of interfaces, such as visual workspaces (VS Code, VNC, browser), command-line interfaces, and APIs. Compared with existing SDKs from OpenAI, Claude, and Google, OpenHands uniquely integrates native sandboxed execution, lifecycle control, model-agnostic multi-LLM routing, and built-in security analysis. Empirical results on SWE-Bench Verified and GAIA benchmarks demonstrate strong performance. Put together, these elements allow the OpenHands Software Agent SDK to provide a practical foundation for prototyping, unlocking new classes of custom applications, and reliably deploying agents at scale.

• The paper introduces a modular, composable SDK that redefines agent architecture with optional isolation, event-sourced state management, and two-layer composability.
• It details robust methodologies including multi-LLM routing, integrated REST/WebSocket services, and secure secret management for production deployment.
• Benchmark results validate the SDK’s competitive performance and scalability, establishing it as a viable framework for both research and industrial applications.

The OpenHands Software Agent SDK: Architecture, Implementation, and Evaluation

Introduction

The OpenHands Software Agent SDK presents a composable, extensible, and production-oriented foundation for building software engineering agents. The SDK is a complete architectural redesign of the original OpenHands framework, motivated by the need for flexibility, reliability, and scalable deployment in real-world software development environments. The design addresses critical limitations of monolithic agent architectures, introducing modularity, statelessness, strict separation of concerns, and two-layer composability. The SDK supports seamless local-to-remote execution, integrated REST/WebSocket services, and direct connectivity to diverse user interfaces, including VS Code, VNC, and browser-based workspaces.

Architectural Evolution and Design Principles

The transition from OpenHands V0 to V1 is characterized by a shift from a tightly coupled, sandbox-centric monolith to a modular SDK with clear boundaries and opt-in sandboxing.

Figure 1: OpenHands V0 architecture: monolithic, tightly coupled components with mandatory sandboxing, leading to duplicated implementations and brittle local execution workflows.

V0’s universal sandboxing model, while ensuring safety, introduced significant friction for local workflows and required duplicated logic for CLI runtimes. V1 refactors this into four decoupled packages: SDK, Tools, Workspace, and Agent Server. This modularity enables independent development, testing, and deployment, supporting both rapid prototyping and robust production scenarios.

The four guiding principles of V1 are:

• Optional isolation: Agents run locally by default, with transparent opt-in sandboxing for safety.
• Stateless by default: All components are immutable and validated at construction; mutable context is isolated in a single conversation state object.
• Strict separation of concerns: The agent core is decoupled from applications, enabling shared library usage and preventing logic duplication.
• Two-layer composability: Developers can compose deployment packages and extend the SDK by adding or replacing typed components.

Core Components and Implementation

Modular Four-Package Design

The SDK is organized into four Python packages:

• openhands.sdk: Core abstractions (Agent, Conversation, LLM, Tool, MCP, event system).
• openhands.tools: Concrete tool implementations.
• openhands.workspace: Execution environments (local, Docker, hosted API).
• openhands.agent_server: Web server exposing REST/WebSocket APIs.

This separation enables lightweight integration, isolated testing, and incremental release cycles, critical for production deployments.

Event-Sourced State Management

The SDK employs an event-sourcing pattern, treating all interactions as immutable events appended to a log. The ConversationState class is the sole mutable component, maintaining metadata and an append-only event log. This design enables deterministic replay, strong consistency, and efficient incremental persistence. Conversations can be resumed by loading the base state and replaying events, supporting robust fault recovery.

LLM Abstraction and Multi-LLM Routing

The LLM class provides a unified interface to 100+ LLMs via LiteLLM, supporting both standard and advanced reasoning APIs. The SDK captures native reasoning fields (e.g., Anthropic’s ThinkingBlock, OpenAI’s ReasoningItemModel) and implements fallback mechanisms for non-function-calling models using prompt-based tool invocation and regex extraction.

Multi-LLM routing is supported via the RouterLLM class, enabling dynamic model selection based on input content (e.g., routing text to a cheaper model, images to a multimodal model).

(Figure 2)

Figure 2: Multi-LLM routing example: RouterLLM delegates requests to selected models based on message content.

Tool System and MCP Integration

The tool system is grounded in an Action–Execution–Observation pattern, with type-safe input validation, structured execution, and LLM-compatible output formatting. MCP tools are treated as first-class SDK tools, with automatic schema translation and structured observation. The registry-based resolution mechanism supports distributed execution and lazy instantiation, enabling tool specs to cross process or network boundaries as pure JSON.

(Figure 3)

Figure 3: Tool system structure: Actions validate inputs, executors run logic, and observations format outputs for LLMs.

Agent Abstraction and Event-Driven Execution

Agents are stateless, immutable specifications, with event-driven execution loops that emit structured events via callbacks. This enables security interleaving, incremental execution, and event streaming for real-time UI updates. Agent context is customizable via skills and prompts, supporting rich behavioral augmentation. Sub-agent delegation is implemented as a standard tool, enabling hierarchical coordination without modifying the core SDK.

Context Window Management

The Condenser system manages context window limits by summarizing and replacing events when history grows too large. The default LLMSummarizingCondenser reduces API costs by up to $2\times$ with no degradation in agent performance.

Local and Remote Execution

The Conversation class abstracts over local and remote execution, enabling seamless migration from prototyping to production. Local conversations run in-process; remote conversations delegate execution to an agent server via HTTP/WebSocket, supporting containerized multi-user deployments.

(Figure 4)

Figure 4: Local-to-remote transition: swapping workspace type enables seamless migration without code changes.

The agent server implements REST endpoints and WebSocket streaming, supporting scalable, isolated execution via official Docker images with dedicated file systems and resources.

(Figure 5)

Figure 5: Agent server architecture: client serializes agent configuration via HTTP; server executes using SDK components inside the container and streams events via WebSocket.

Workspace Abstraction

The BaseWorkspace class enables sandboxes for agents, with local and remote implementations forwarding operations to the host or delegating over HTTP, respectively. The factory pattern ensures agent code remains unchanged across environments.

(Figure 6)

Figure 6: Workspace interface: implementations handle environment details for local and remote execution.

Security and Secrets Management

Security is a first-class concern, with the SecurityAnalyzer rating tool calls and the ConfirmationPolicy determining user approval requirements. The SDK includes built-in risk assessment and confirmation workflows, supporting adaptive trust and custom policies. The SecretRegistry provides secure, session-isolated credential management, with automatic masking and support for live rotation.

Reliability, Evaluation, and Benchmarking

Continuous Quality Assurance

The SDK employs a three-tier testing strategy:

• Programmatic tests: Mock LLM calls for fast feedback.
• LLM-based tests: Integration and example tests with real models, costing \$0.5–\$3 per run.
• Benchmark evaluation: High-cost, comprehensive evaluations on academic datasets.

(Figure 7)

Figure 7: Integration test framework: scenario-based workflows for agent reliability.

Benchmark Results

The SDK demonstrates competitive performance on SWE-Bench Verified and GAIA benchmarks:

Benchmark	Model	Performance
SWE-Bench	Claude Sonnet 4.5	72.8%
SWE-Bench	GPT-5 (reasoning=high)	68.8%
GAIA	Claude Sonnet 4.5	67.9%
GAIA	GPT-5 (reasoning=high)	62.4%
GAIA	Qwen3 Coder 480B A35B	41.2%

These results validate the SDK’s architecture as competitive with research-focused systems, with no loss in agentic capability.

Feature Comparison and Related Work

A systematic comparison with OpenAI Agents SDK, Claude Agent SDK, and Google ADK reveals that OpenHands uniquely combines native remote execution, production server with sandboxing, model-agnostic multi-LLM routing, and built-in security analysis. The SDK also provides features absent in other frameworks, such as context condensation, secrets management, stuck detection, and interactive workspace access.

Practical and Theoretical Implications

The OpenHands Software Agent SDK establishes a robust foundation for both research and industrial-scale deployment of software engineering agents. Its composable architecture, stateless event sourcing, and modular design enable reproducible, deterministic execution and seamless transition from local prototyping to production. The integration of security, secrets management, and interactive workspace access addresses critical concerns for real-world deployment. The SDK’s empirical performance on standardized benchmarks demonstrates its generality and reliability across diverse model backends.

Theoretically, the event-sourced, stateless design provides a blueprint for scalable agent architectures, supporting fault recovery, reproducibility, and extensibility. The separation of concerns and composability principles facilitate rapid experimentation and safe extension, enabling the development of new classes of custom applications.

Future Directions

Potential future developments include:

• Enhanced support for asynchronous and distributed agent coordination.
• Integration with advanced memory systems for long-term context retention.
• Expansion of security analysis to cover adversarial scenarios and prompt injection.
• Automated benchmarking and continuous evaluation pipelines for large-scale deployments.
• Further abstraction of workspace environments to support hybrid cloud/local execution.

Conclusion

The OpenHands Software Agent SDK delivers a composable, stateless, and production-ready foundation for software engineering agents. Its modular architecture, event-sourced state management, and robust security features enable reliable operation across heterogeneous environments. Empirical evaluation confirms strong performance and consistency, validating the SDK as a practical and extensible platform for both research and industrial applications. The design principles and implementation strategies outlined in this work provide a template for future agent frameworks seeking to balance flexibility, reliability, and scalability.