Skip to main content
The OpenHands Software Agent SDK provides a unified, type-safe framework for building and deploying AI agents—from local experiments to full production systems, focused on statelessness, composability, and clear boundaries between research and deployment. Check this document for the core design principles that guided its architecture.

​
Relationship With OpenHands Applications

The Software Agent SDK is the source of truth for agents in OpenHands. Its repository also contains Agent Server, which exposes SDK conversations and workspaces to remote clients through REST and WebSocket APIs. OpenHands applications live in separate repositories and consume these SDK interfaces.
  • The SDK defines agent behavior. It provides agents, LLMs, conversations, tools, workspaces, events, and security policies.
  • Agent Server exposes remote execution. Clients use its APIs to run conversations and tools in the selected workspace or sandbox.
  • Applications remain separate. Agent Canvas, the OpenHands CLI, and custom clients integrate with the SDK or Agent Server without sharing one application repository.

​
Four-Package Architecture

The agent-sdk is organized into four distinct Python packages:

​
Two Deployment Modes

The SDK supports two deployment architectures depending on your needs:

​
Mode 1: Local Development

Installation: Just install openhands-sdk + openhands-tools
Architecture:
  • LocalWorkspace included in SDK (no extra install)
  • Everything runs in one process
  • Perfect for prototyping and simple use cases
  • Quick setup, no Docker required

​
Mode 2: Production / Sandboxed

Installation: Install all 4 packages
Architecture:
  • RemoteWorkspace auto-spawns agent-server in containers
  • Sandboxed execution for security
  • Multi-user deployments
  • Distributed systems (e.g., Kubernetes) support
Key Point: Same agent code works in both modes—just swap the workspace type (LocalWorkspace → DockerWorkspace → RemoteAPIWorkspace).

​
SDK Package (openhands.sdk)

Purpose: Core components and base classes for OpenHands agent. Key Components:
  • Agent: Implements the reasoning-action loop
  • Conversation: Manages conversation state and lifecycle
  • LLM: Provider-agnostic language model interface with retry and telemetry
  • Tool System: Typed base class definitions for action, observation, tool, and executor; includes MCP integration
  • Events: Typed event framework (e.g., action, observation, user messages, state update, etc.)
  • Workspace: Base classes (Workspace, LocalWorkspace, RemoteWorkspace)
  • Skill: Reusable user-defined prompts with trigger-based activation
  • Condenser: Conversation history compression for token management
  • Security: Action risk assessment and validation before execution
Design: Stateless, immutable components with type-safe Pydantic models. Self-Contained: Build and run agents with just openhands-sdk using LocalWorkspace. Source: openhands-sdk/

​
Tools Package (openhands.tools)

Tool Independence: Tools run alongside the agent in whatever environment workspace configures (local/container/remote). They don’t run “through” workspace APIs.
Purpose: Pre-built tools following consistent patterns. Design: All tools follow Action/Observation/Executor pattern with built-in validation, error handling, and security.
For full list of tools, see the source code as the source of truth.

​
Workspace Package (openhands.workspace)

Purpose: Workspace implementations extending SDK base classes. Key Components: Docker Workspace, Remote API Workspace, and more. Design: All workspace implementations extend RemoteWorkspace from SDK, adding container lifecycle or API client functionality. Use Cases: Sandboxed execution, multi-user deployments, production environments.
For full list of implemented workspaces, see the source code.

​
Agent Server Package (openhands.agent_server)

Purpose: FastAPI-based HTTP/WebSocket server for remote agent execution. Features:
  • REST API & WebSocket endpoints for conversations, bash, files, events, desktop, and VSCode
  • OpenAI-compatible /v1/chat/completions endpoint for clients that expect an OpenAI-style backend
  • Service management with isolated per-user sessions
  • API key authentication and health checking
Deployment: Runs inside containers (via DockerWorkspace) or as standalone process (connected via RemoteWorkspace). Use Cases: Multi-user web apps, SaaS products, distributed systems.
For implementation details, see the source code.

​
How Components Work Together

​
Basic Execution Flow (Local)

When you send a message to an agent, here’s what happens: Key takeaway: The agent orchestrates the reasoning-action loop—calling the LLM for decisions and executing tools to perform actions.

​
Deployment Flexibility

The same agent code runs in different environments by swapping workspace configuration:

​
Next Steps

​
Get Started

​
Explore Components

SDK Package:
  • Agent – Core reasoning-action loop
  • Conversation – State management and lifecycle
  • LLM – Language model integration
  • Tool System – Action/Observation/Executor pattern
  • Events – Typed event framework
  • Workspace – Base workspace architecture
Tools Package: Workspace Package: Agent Server:

​
Deploy

​
Source Code