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

1 Introduction

• The redesign addresses production foundations needed for autonomous agents, including durable state, safe execution, and consistent behavior across deployment environments.These needs arise as agents move from assistive tools toward long-running autonomous software-development systems.Source: §1 · pp. 1–2
• V1 replaces V0’s tightly coupled monolith with a modular SDK whose reusable agent, tool, and workspace packages support clearer architectural boundaries.Figure 1 describes the redesign from a sandbox-centric architecture with duplicated local implementations to modular packages.Source: Figure 1 · p. 2, §1 · p. 2
• V1 is organized around optional isolation, a single event-sourced state, strict separation of concerns, and composable deployment and capability packages.Agents and components are immutable by default, while one conversation-state object records mutable context.Source: §1 · p. 2
• The SDK supports deterministic replay, typed MCP-integrated tools, local-to-containerized execution portability, REST/WebSocket services, and interactive workspace interfaces.The same agent can run locally for prototyping or remotely in secure containerized environments with minimal code changes.Source: §1 · p. 3
• The SDK combines native remote sandboxed execution, a production server, model-agnostic routing across 100+ providers, security analysis, and QA instrumentation.These capabilities distinguish it from the compared OpenAI Agents SDK, Claude Agent SDK, Google ADK, and LangChain.Source: §1 · p. 3
• 61% fewer system-attributable failures than V0 were observed over 15 days, while event-sourcing overhead was negligible across evaluations spanning 14 models and five benchmark categories.The reported benchmarks include SWE-Bench Verified, GAIA, SWE-Bench Multimodal, SWT-Bench, and Commit0.Source: §1 · p. 3

2.1 Agent Design

• Software agents perceive environments, maintain state and memory, and influence those environments through actions implemented by tools.Observations may include text, logs, or visual data; state can include interaction history and retrieved information.Source: §2.1 · p. 3

2.2 Software Agents

• In software engineering, the environment is a workspace exposing files, terminals, and web interfaces that provide program output and test feedback.The workspace supplies the external context in which the agent operates.Source: §2.2 · p. 4
• An event log represents persistent agent state by recording commands, edits, and results across actions.This gives the agent continuing context during an end-to-end development workflow.Source: §2.2 · p. 4
• Software-engineering agents act by editing files, running tests, and invoking structured tools such as a web browser.These actions operationalize the agent’s interaction with its development environment.Source: §2.2 · p. 4

3.1 Universal Sandboxing vs. Local Flexibility

• V0’s universal sandbox split conversations across independent agent and sandbox processes, allowing divergent states, corrupted sessions, and resource-related crashes.Shared multi-tenant containers could also be exhausted by resource-heavy actions such as mass webpage visits producing oversized screenshots.Source: §3.1 · p. 4
• V1 makes sandboxing opt-in, unifying agent and tool execution by default while preserving transparent containerization when isolation is required.This aligns execution with MCP’s local-execution assumptions without removing safety controls.Source: §3.1 · p. 4

3.2 Mutable Configuration vs. Deterministic State

• V0’s configuration sprawl reached 140+ fields, 15 classes, and 2.8K lines, causing small changes to cascade into unrelated failures.Overlapping configuration hierarchies and in-place overrides meant identical parameters could produce subtly divergent runs.Source: §3.2 · pp. 4–5
• V1 makes agents and components immutable and serializable, using one mutable conversation-state object to enable deterministic replay, consistency, and recovery.Components are validated at construction, isolating change to the single state source.Source: §3.2 · p. 5

3.3 Monorepo vs. Modular SDK

• V0’s monorepo mixed core logic, applications, benchmarks, and runtime-specific code, producing heavyweight and fragile deployments with dependency conflicts.Application-specific branches and environment hacks made the system slow to evolve.Source: §3.3 · p. 5
• V1 separates the agent core into an SDK so applications integrate through APIs and research can evolve independently from downstream interfaces.The separation addresses divergent application logic and configuration overrides.Source: §3.3 · p. 5

3.4 Monolith Logic vs. Extensible Architecture

• V0 lacked structured composability, so adding behaviors required core edits or entry-point-specific branches and encouraged ad hoc hacks.This limited experimentation and maintainability.Source: §3.4 · p. 5
• V1 makes composability first-class through four deployment packages and typed tools, LLMs, and contexts that can be extended or reconfigured without changing the core.The packages support local, hosted, or containerized execution.Source: §3.4 · p. 5

4.1 Modular Four-Package Design

• The SDK comprises core abstractions, concrete tools, execution workspaces, and an agent server that can be composed for deployment needs.This separation supports independent testing, selective dependencies, and incremental releases.Source: §4.1 · p. 6

4.2 Event-Sourced State Management

• Event sourcing records immutable interactions while ConversationState holds mutable metadata and supports persistence, replay, and recovery.Event hierarchies distinguish LLM-convertible events from internal bookkeeping events.Source: §4.2 · pp. 6–7
• Event-sourcing overhead remains negligible, with sub-millisecond persistence latency and crash recovery under 20 ms.These measurements were reported from agent traces and support the state-management design’s operational practicality.Source: §4.2 · p. 7

4.3 LLM Abstraction Layer

• The LLM abstraction supports 100+ providers, extended reasoning fields, non-function-calling models, and routing different requests to selected models.RouterLLM preserves a unified interface while allowing custom model selection logic.Source: §4.3 · p. 7

4.4 Tool System

• The typed tool system validates JSON actions, executes them, formats observations for LLMs, and treats MCP tools through the same interface.Tool registries additionally serialize specifications across process or network boundaries and reconstruct executors at runtime.Source: §4.4 · pp. 7–9

4.5 Agent: Stateless Event Processor

• Agents are immutable, serializable specifications whose event-driven execution emits structured events for security review, incremental control, recovery, and streaming.AgentContext and Skills customize prompts and behavior without modifying agent logic, while delegation tools support hierarchical coordination.Source: §4.5 · p. 9

4.6 Context Window Management

• Condensers replace oversized histories with summaries while preserving condensation events, enabling long conversations and reducing token costs.The default LLMSummarizingCondenser has been reported to reduce API costs by up to 2× without degrading agent performance.Source: §4.6 · pp. 9–10

4.7 Local Conversation

• LocalConversation runs the full agent loop in-process and supports direct control, callbacks, pausing, persistence, and later resumption.This mode is designed for rapid iteration and debugging without network or container overhead.Source: §4.7 · p. 10

4.8 Secret Registry

• SecretRegistry isolates credentials per conversation, exposes them only at execution time, masks outputs, supports remote sources, and enables live rotation.Secrets are redacted during serialization and may be encrypted with a configurable cipher.Source: §4.8 · p. 10

4.9 Security and Confirmation

• SecurityAnalyzer rates tool-call risk while ConfirmationPolicy determines whether approval is required, allowing risky actions to pause before execution.Developers can customize assessment and enforcement separately, and rejected actions may be retried with safer alternatives.Source: §4.9 · p. 10

4.10 Deployment Architecture: Local to Remote

• The Conversation and Workspace abstractions preserve one API across local and remote execution, allowing deployment to scale by swapping workspace types.Remote execution serializes configuration to an agent server over HTTP and streams events through WebSocket; Docker containers provide isolated environments.Source: §4.10 · pp. 10–11

5.1 Production Reliability: V0 vs. V1

• 61%: V1 reduces system-attributable failures from 78.0 to 30.0 errors per 1k conversations during a 15-day production rollout.The comparison excludes external LLM-provider errors; V1 removes observed inter-pod communication failure modes through co-located execution.Source: §5.1 · p. 12

5.2 Event-Sourcing Systems Overhead

• Under 20 ms: crash recovery completes within this time even for the longest observed conversation, while event-sourcing persist and recovery latencies remain negligible relative to LLM calls.The overhead evaluation replayed 39,870 events from 433 SWE-Bench Verified conversations, and storage grows linearly.Source: §5.2 · p. 13, Table 3 · p. 13

5.3 Continuous Quality Assurance

• Three testing tiers cover fast mocked programmatic checks, daily or on-demand real-model tests, and costly on-demand benchmark evaluations.LLM-based test runs cost $0.5–$3 and complete in less than 5 minutes, whereas benchmark evaluations cost $100–1000 and take hours.Source: §5.3 · p. 13

5.4 Benchmark Evaluation

• SOTA on 3 of 5 benchmarks: the SDK remains competitive on the other two, within 2.6 and 5.2 points, across evaluations of 14 language models.The comparison uses a single model per evaluation, while several state-of-the-art systems use multi-model orchestration.Source: §5.4 · pp. 13–14, Table 5 · p. 14
• 62.5%: GPT-5.4 leads long-horizon greenfield development by 12.5 points over second place, while Claude models dominate issue resolution and testing.The model-agnostic evaluation harness exposes task-specific specialization across the benchmark categories.Source: §5.4 · pp. 14–15

6 Related Work

• OpenHands is a fully open-source, vendor-agnostic platform purpose-built for software-engineering agents, unlike provider SDKs tied to their model ecosystems.It combines event-sourced state and immutable configuration with sandboxed execution, a built-in REST/WebSocket server, and workspace-level remote interfaces.Source: §6 · pp. 15–16
• These integrated design choices enable reproducible, deterministic execution and transition from local prototyping to production-scale deployments.The SDK also provides workspace interfaces for human-agent collaboration.Source: §6 · pp. 15–16

7 Discussion

• Event sourcing was chosen over database-backed state because it preserves reproducibility, avoids storage-backend coupling, and supports offline replay.Optional isolation was selected over mandatory containers or local-only execution to preserve sandboxing while aligning with local-first assumptions.Source: §7 · p. 16
• The four-package design balances independent testability with practical dependency management rather than pursuing either a monolithic SDK or microservices architecture.The comparison frames package structure as a trade-off between simpler dependencies and maximum flexibility.Source: §7 · p. 16
• A comprehensive multi-tenant security audit remains future work because shared LLM keys, MCP servers, and secret registries require careful access control.Containerized deployment, per-conversation secrets, and session authentication provide foundations but do not complete the audit.Source: §7 · p. 16
• The implementation focuses on single-agent conversations, while multi-agent coordination mechanisms require further design and LLM-based security analysis remains vulnerable to adversarial prompts and inconsistent classification.The security framework is substantially improved over V0 but cannot guarantee complete safety.Source: §7 · p. 16

8 Conclusion

• 61%: a 15-day production comparison shows V1 reduces system-attributable failures relative to V0.The conclusion attributes the broader architecture to a stateless, event-sourced, composable design spanning SDK, Tools, Workspace, and Server packages.Source: §8 · p. 16
• State-of-the-art results on three of five tasks confirm strong agentic performance across 14 models and five benchmark categories.The conclusion also reports negligible event-sourcing overhead, including crash recovery under 20 ms.Source: §8 · p. 16
• The four architectural lessons emphasize strict separation of concerns, event-sourced state, immutable components, and unified local-to-sandboxed execution.These choices are presented as supporting maintainability, reproducibility, fault recovery, configuration stability, and the transition from experimentation to production.Source: §8 · p. 16

Architectural Alternatives Considered

• Event sourcing was chosen over database-backed state to preserve reproducibility, storage agnosticism, and offline replay.The design avoids coupling the SDK to a specific storage backend.Source: A Discussion · p. 19

Multi-Tenant Deployment

• Multi-tenant deployment has process, filesystem, resource, event-log, secret, and session-isolation foundations, but a comprehensive security audit remains future work.Shared LLM API keys, MCP servers, and secret registries require careful access control.Source: A Discussion · p. 19

Limitations

• The implementation focuses on single-agent conversations, while multiagent coordination remains underdesigned and LLM-based security analysis can be vulnerable to adversarial prompts and inconsistent classification.Source: A Discussion · p. 19

• Table 7 organizes the production reliability analysis through an error taxonomy.Source: Table 7 · p. 19