> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-686-repository-boundaries.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understanding the OpenHands Software Agent SDK's package structure, component interactions, and execution models.

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](/sdk/arch/design) 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](https://github.com/OpenHands/OpenHands), the [OpenHands CLI](https://github.com/OpenHands/OpenHands-CLI), and custom clients integrate with the SDK or Agent Server without sharing one application repository.

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 50}} }%%
graph TB
    subgraph Clients["Clients"]
        Canvas[Agent Canvas<br><i>Browser client</i>]
        CLI[OpenHands CLI<br><i>Command-line client</i>]
        Custom[Custom Client<br><i>Applications and workflows</i>]
    end

    Server[Agent Server<br><i>REST and WebSocket API</i>]
    SDK[Software Agent SDK<br><i>Agents, tools, and workspaces</i>]

    subgraph External["External Services"]
        LLM[LLM Providers]
        Workspace[Workspace or Sandbox]
    end

    Canvas --> Server
    CLI --> SDK
    Custom --> Server
    Custom --> SDK
    Server --> SDK
    SDK --> LLM
    SDK --> Workspace

    classDef interface fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
    classDef sdk fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
    classDef external fill:#fff4df,stroke:#b7791f,stroke-width:2px

    class Canvas,CLI,Custom interface
    class Server,SDK sdk
    class LLM,Workspace external
```

## Four-Package Architecture

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

| Package                     | What It Does                                        | When You Need It                             |
| --------------------------- | --------------------------------------------------- | -------------------------------------------- |
| **openhands.sdk**           | Core agent framework + base workspace classes       | Always (required)                            |
| **openhands.tools**         | Pre-built tools (bash, file editing, etc.)          | Optional - provides common tools             |
| **openhands.workspace**     | Extended workspace implementations (Docker, remote) | Optional - extends SDK's base classes        |
| **openhands.agent\_server** | Multi-user API server                               | Optional - used by workspace implementations |

### Two Deployment Modes

The SDK supports two deployment architectures depending on your needs:

#### Mode 1: Local Development

**Installation:** Just install `openhands-sdk` + `openhands-tools`

```bash theme={null}
pip install openhands-sdk openhands-tools
```

**Architecture:**

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%%
flowchart LR
    SDK["<b>openhands.sdk</b><br>Agent · LLM · Conversation<br><b>+ LocalWorkspace</b>"]:::sdk
    Tools["<b>openhands.tools</b><br>BashTool · FileEditor · GrepTool · …"]:::tools
    
    SDK -->|uses| Tools
    
    classDef sdk    fill:#e8f3ff,stroke:#2b6cb0,color:#0f2a45,stroke-width:2px,rx:8,ry:8
    classDef tools  fill:#e9f9ef,stroke:#2f855a,color:#14532d,stroke-width:2px,rx:8,ry:8
```

* `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

```bash theme={null}
pip install openhands-sdk openhands-tools openhands-workspace openhands-agent-server
```

**Architecture:**

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 20, "rankSpacing": 30}} }%%
flowchart LR
    
    WSBase["<b>openhands.sdk</b><br>Base Classes:<br>Workspace · Local · Remote"]:::sdk
    
    subgraph WS[" "]
      direction LR
      Docker["<b>openhands.workspace DockerWorkspace</b><br><i>extends RemoteWorkspace</i>"]:::ws
      Remote["<b>openhands.workspace RemoteAPIWorkspace</b><br><i>extends RemoteWorkspace</i>"]:::ws
    end
    
    Server["<b>openhands.agent_server</b><br><i>FastAPI + WebSocket</i>"]:::server
    Agent["<b>openhands.sdk</b><br>Agent · LLM · Conversation"]:::sdk
    Tools["<b>openhands.tools</b><br>BashTool · FileEditor · …"]:::tools
    
    WSBase -.->|extended by| Docker
    WSBase -.->|extended by| Remote
    Docker -->|spawns container with| Server
    Remote -->|connects via HTTP to| Server
    Server -->|runs| Agent
    Agent -->|uses| Tools
    
    classDef sdk    fill:#e8f3ff,stroke:#2b6cb0,color:#0f2a45,stroke-width:1.1px,rx:8,ry:8
    classDef ws     fill:#fff4df,stroke:#b7791f,color:#5b3410,stroke-width:1.1px,rx:8,ry:8
    classDef server fill:#f3e8ff,stroke:#7c3aed,color:#3b2370,stroke-width:1.1px,rx:8,ry:8
    classDef tools  fill:#e9f9ef,stroke:#2f855a,color:#14532d,stroke-width:1.1px,rx:8,ry:8
    
    style WS stroke:#b7791f,stroke-width:1.5px,stroke-dasharray: 4 3,rx:8,ry:8,fill:none
```

* `RemoteWorkspace` auto-spawns agent-server in containers
* Sandboxed execution for security
* Multi-user deployments
* Distributed systems (e.g., Kubernetes) support

<Tip>
  **Key Point:** Same agent code works in both modes—just swap the workspace type (`LocalWorkspace` → `DockerWorkspace` → `RemoteAPIWorkspace`).
</Tip>

### SDK Package (`openhands.sdk`)

**Purpose:** Core components and base classes for OpenHands agent.

**Key Components:**

* **[Agent](/sdk/arch/agent):** Implements the reasoning-action loop
* **[Conversation](/sdk/arch/conversation):** Manages conversation state and lifecycle
* **[LLM](/sdk/arch/llm):** Provider-agnostic language model interface with retry and telemetry
* **[Tool System](/sdk/arch/tool-system):** Typed base class definitions for action, observation, tool, and executor; includes MCP integration
* **[Events](/sdk/arch/events):** Typed event framework (e.g., action, observation, user messages, state update, etc.)
* **[Workspace](/sdk/arch/workspace):** Base classes (`Workspace`, `LocalWorkspace`, `RemoteWorkspace`)
* **[Skill](/sdk/arch/skill):** Reusable user-defined prompts with trigger-based activation
* **[Condenser](/sdk/arch/condenser):** Conversation history compression for token management
* **[Security](/sdk/arch/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/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk)

### Tools Package (`openhands.tools`)

<Note>
  **Tool Independence:** Tools run alongside the agent in whatever environment workspace configures (local/container/remote). They don't run "through" workspace APIs.
</Note>

**Purpose:** Pre-built tools following consistent patterns.

**Design:** All tools follow Action/Observation/Executor pattern with built-in validation, error handling, and security.

<Note>
  For full list of tools, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools) as the source of truth.
</Note>

### 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.

<Note>
  For full list of implemented workspaces, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace).
</Note>

### 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](/sdk/guides/agent-server/openai-gateway) 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.

<Note>
  For implementation details, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server).
</Note>

## How Components Work Together

### Basic Execution Flow (Local)

When you send a message to an agent, here's what happens:

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Conversation
    participant Agent
    participant LLM
    participant Tool
    
    You->>Conversation: "Create hello.txt"
    Conversation->>Agent: Process message
    Agent->>LLM: What should I do?
    LLM-->>Agent: Use BashTool("touch hello.txt")
    Agent->>Tool: Execute action
    Note over Tool: Runs in same environment<br/>as Agent (local/container/remote)
    Tool-->>Agent: Observation
    Agent->>LLM: Got result, continue?
    LLM-->>Agent: Done
    Agent-->>Conversation: Update state
    Conversation-->>You: "File created!"
```

**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:

```mermaid theme={null}
graph TB
    subgraph "Your Code (Unchanged)"
        Code["Agent + Tools + LLM"]
    end
    
    subgraph "Deployment Options"
        Local["Local<br/><i>Direct execution</i>"]
        Docker["Docker<br/><i>Containerized</i>"]
        Remote["Remote<br/><i>Multi-user server</i>"]
    end
    
    Code -->|LocalWorkspace| Local
    Code -->|DockerWorkspace| Docker
    Code -->|RemoteAPIWorkspace| Remote
    
    style Code fill:#e1f5fe
    style Local fill:#e8f5e8
    style Docker fill:#e8f5e8
    style Remote fill:#e8f5e8
```

## Next Steps

### Get Started

* [Getting Started](/sdk/getting-started) – Build your first agent
* [Hello World](/sdk/guides/hello-world) – Minimal example

### Explore Components

**SDK Package:**

* [Agent](/sdk/arch/agent) – Core reasoning-action loop
* [Conversation](/sdk/arch/conversation) – State management and lifecycle
* [LLM](/sdk/arch/llm) – Language model integration
* [Tool System](/sdk/arch/tool-system) – Action/Observation/Executor pattern
* [Events](/sdk/arch/events) – Typed event framework
* [Workspace](/sdk/arch/workspace) – Base workspace architecture

**Tools Package:**

* See [`openhands-tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools) source code for implementation details

**Workspace Package:**

* See [`openhands-workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace) source code for implementation details

**Agent Server:**

* See [`openhands-agent-server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server) source code for implementation details

### Deploy

* [Remote Server](/sdk/guides/agent-server/overview) – Deploy remotely
* [Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox) – Container setup
* [API Sandboxed Server](/sdk/guides/agent-server/api-sandbox) – Hosted runtime service
* [Local Agent Server](/sdk/guides/agent-server/local-server) – In-process server

### Source Code

* [`openhands/sdk/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk) – Core framework
* [`openhands/tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools) – Pre-built tools
* [`openhands/workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace) – Workspaces
* [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server) – HTTP server
* [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples) – Working examples