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

# Introduction

> A clean, modular SDK for building AI agents. Core agent framework and production-ready tool implementations.

The [OpenHands SDK](https://github.com/All-Hands-AI/agent-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](https://github.com/All-Hands-AI/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:

```python theme={null}
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

* Python 3.12+
* [`uv` package manager](https://docs.astral.sh/uv/) (version 0.8.13+)

### Acquire and Set an LLM API Key

Obtain an API key from your favorite LLM provider, any [provider supported by LiteLLM](https://docs.litellm.ai/docs/providers)
is supported by the Agent SDK, although we have a set of [recommended models](/openhands/usage/llms/llms) that
work well with OpenHands agents.

If you want to get started quickly, you can sign up for the [OpenHands Cloud](https://app.all-hands.dev) and go to the
[API key page](https://app.all-hands.dev/settings/api-keys), which allows you to use most of our recommended models
with no markup -- documentation is [here](/openhands/usage/llms/openhands-llms).

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.

```bash theme={null}
# 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](/sdk/architecture)** - High-level system design with Mermaid diagrams

* Event-sourced state management
* Stateless agent design
* Component interaction patterns
* Design principles and benefits

**[Core Components](/sdk/core/overview)** - Deep dive into SDK components

* [ConversationState](/sdk/core/state) - Event-sourced state management
* [Agent](/sdk/core/agent) - Stateless decision logic
* [LLM](/sdk/core/llm) - Model abstraction and routing
* [Tools](/sdk/core/tools) - Action execution framework
* [Conversation](/sdk/core/conversation) - Orchestration API

### 🚀 Advanced Features

**[Advanced Features Overview](/sdk/advanced/overview)** - Production capabilities

* [Context Condensation](/sdk/advanced/context-condensation) - Reduce token usage by 60-70%
* [Context Files & Microagents](/sdk/advanced/microagents) - Inject targeted knowledge
* [Task Tracking](/sdk/advanced/task-tracking) - Built-in TODO lists
* [Stuck Detection](/sdk/advanced/stuck-detection) - Detect infinite loops

### 🔒 Security & Production

**[Security](/sdk/security/overview)** - Defense in depth

* [Security Analyzer](/sdk/security/analyzer) - Two-tier risk analysis
* [Confirmation Policies](/sdk/security/confirmation-policies) - Custom approval workflows
* [Secrets Management](/sdk/security/secrets) - Auto-masking sensitive data

**[Production Deployment](/sdk/production/overview)** - Deploy at scale

* [Production Server](/sdk/production/server) - Built-in REST/WebSocket APIs
* [Container Sandboxing](/sdk/production/sandboxing) - Isolated execution
* [Interactive Workspace](/sdk/production/workspace-access) - VNC, VSCode Web, SSH

### 📚 Guides & Examples

**[Examples](https://github.com/All-Hands-AI/agent-sdk/tree/main/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](#hello-world-example)
2. Read [Architecture Overview](/sdk/architecture)
3. Explore [Custom Agents](/sdk/core/agent#custom-agents)
4. Check [Advanced Features](/sdk/advanced/overview)

### For Production Engineers

1. Start with [Hello World](#hello-world-example)
2. Review [Security](/sdk/security/overview)
3. Set up [Production Server](/sdk/production/server)
4. Configure [Container Sandboxing](/sdk/production/sandboxing)

### For Integration Developers

1. Start with [Hello World](#hello-world-example)
2. Understand [Event System](/sdk/core/state)
3. Explore [Tools](/sdk/core/tools)
4. Check [MCP Integration](/sdk/advanced/mcp)

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

```python theme={null}
# 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)

```python theme={null}
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

```python theme={null}
agent = Agent(llm=llm, tools=tools)  # Frozen
# To change, create new instance
new_agent = agent.model_copy(update={"llm": new_llm})
```

## Next Steps

* **[Architecture Overview](/sdk/architecture)** - Understand the system design
* **[Core Components](/sdk/core/overview)** - Learn the building blocks
* **[Advanced Features](/sdk/advanced/overview)** - Explore production capabilities
* **[Examples](https://github.com/All-Hands-AI/agent-sdk/tree/main/examples)** - See working code

## Community & Support

* **GitHub**: [All-Hands-AI/agent-sdk](https://github.com/All-Hands-AI/agent-sdk)
* **Issues**: [Report bugs or request features](https://github.com/All-Hands-AI/agent-sdk/issues)
* **Discord**: [Join the community](https://discord.gg/ESHStjSjD4)
* **Docs**: [Full documentation](https://docs.all-hands.dev)