Skip to main content
The OpenHands SDK is a production-ready framework for building AI agents that interact with code and software systems. Built on modern software engineering principles—event sourcing, immutability, and type safety—it provides a robust foundation for both research and production deployments.

​
Why OpenHands SDK?

​
🎯 Correctness & Reliability

  • Event-sourced architecture for perfect reproducibility
  • Immutable state eliminates entire classes of bugs
  • Type-safe APIs catch errors at compile time
  • Time-travel debugging via event replay

​
🛠️ Developer Experience

  • Stateless agents are easy to test and compose
  • 100+ LLM providers via LiteLLM integration
  • Native MCP support for thousands of tools
  • Clear, minimal API with sensible defaults

​
🚀 Production Ready

  • Built-in REST/WebSocket server with authentication
  • Container sandboxing for secure execution
  • Auto context condensation (60-70% token reduction)
  • Interactive debugging via VNC, VSCode Web

​
📊 Research Friendly

  • Custom agents for arbitrary reasoning strategies
  • LLM routing for A/B testing
  • Event logs for retrospective analysis
  • Microagents for rapid prompt engineering

​
Use Cases

The SDK enables a wide range of applications:
  1. Documentation Automation - Agents that analyze code changes and update documentation
  2. SRE Assistants - Debug production issues by analyzing logs and code together
  3. Data Processing - Transform unstructured data into structured database entries
  4. Code Review Bots - Automatically review PRs and suggest improvements
  5. Testing Automation - Generate and maintain test suites
  6. DevOps Agents - Automate deployment and infrastructure management
This SDK also powers OpenHands, an all-batteries-included coding agent with GUI, CLI, and API interfaces.

​
Hello World Example

This is what it looks like to write a program with an OpenHands agent: 
import os
from pydantic import SecretStr
from openhands.sdk import LLM, Conversation
from openhands.sdk.preset.default import get_default_agent

# Configure LLM
api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."
llm = LLM(
    model="openhands/claude-sonnet-4-5-20250929",
    api_key=SecretStr(api_key),
)

# Create agent with default tools and configuration
agent = get_default_agent(
    llm=llm,
    working_dir=os.getcwd(),
    cli_mode=True,  # Disable browser tools for CLI environments
)

# Create conversation, send a message, and run
conversation = Conversation(agent=agent)
conversation.send_message("Create a Python file that prints 'Hello, World!'")
conversation.run()

​
Installation & Quickstart

​
Prerequisites

​
Acquire and Set an LLM API Key

Obtain an API key from your favorite LLM provider, any provider supported by LiteLLM is supported by the Agent SDK, although we have a set of recommended models that work well with OpenHands agents. If you want to get started quickly, you can sign up for the OpenHands Cloud and go to the API key page, which allows you to use most of our recommended models with no markup — documentation is here. Once you do this, you can export LLM_API_KEY=xxx to use all the examples.

​
Setup

Once this is done, run the following to do a Hello World example. 
# Clone the repository
git clone https://github.com/All-Hands-AI/agent-sdk.git
cd agent-sdk

# Install dependencies and setup development environment
make build

# Verify installation
uv run python examples/01_hello_world.py

​
Documentation Structure

​
📐 Architecture & Core Concepts

Architecture Overview - High-level system design with Mermaid diagrams
  • Event-sourced state management
  • Stateless agent design
  • Component interaction patterns
  • Design principles and benefits
Core Components - Deep dive into SDK components

​
🚀 Advanced Features

Advanced Features Overview - Production capabilities

​
🔒 Security & Production

Security - Defense in depth Production Deployment - Deploy at scale

​
📚 Guides & Examples

Examples - Complete working examples
  • 01_hello_world.py - Basic agent usage
  • 09_pause_example.py - Pause and resume
  • 14_context_condenser.py - Context management
  • And 20+ more examples covering all features

​
Quick Start Paths

​
For Researchers

  1. Start with Hello World
  2. Read Architecture Overview
  3. Explore Custom Agents
  4. Check Advanced Features

​
For Production Engineers

  1. Start with Hello World
  2. Review Security
  3. Set up Production Server
  4. Configure Container Sandboxing

​
For Integration Developers

  1. Start with Hello World
  2. Understand Event System
  3. Explore Tools
  4. Check MCP Integration

​
Key Concepts

​
Event Sourcing

All state is derived from an immutable event log, enabling:
  • Perfect reproducibility
  • Time-travel debugging
  • Complete audit trails
  • Zero race conditions
# State is derived, not stored
state = ConversationState()
state.append_event(event1)
state.append_event(event2)

# Same events → same state, always
assert state.agent_execution_status == compute_status(event1, event2)

​
Stateless Agents

Agents are pure functions with no internal state:
  • Easy to test (no mocking)
  • Easy to serialize (send over network)
  • Easy to scale (run anywhere)
  • Easy to compose (sub-agents)
class Agent:
    def step(self, state: ConversationState) -> Generator[Event]:
        # Read state (never modify!)
        # Generate actions
        # No internal state!

​
Immutable Configuration

All configuration is frozen after creation:
  • No config drift
  • Type-safe at compile time
  • Easy to version control
  • Clear dependencies
agent = Agent(llm=llm, tools=tools)  # Frozen
# To change, create new instance
new_agent = agent.model_copy(update={"llm": new_llm})

​
Next Steps

​
Community & Support