Getting Started

Install the OpenHands SDK and build AI agents that write software.

The OpenHands SDK is a modular framework for building AI agents that interact with code, files, and system commands. Agents can execute bash commands, edit files, browse the web, and more.

Prerequisites

Install the uv package manager (version 0.8.13+):

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Step 1: Acquire an LLM API Key

The SDK requires an LLM API key from any LiteLLM-supported provider. See our recommended models for best results.

Option 1: OpenHands Cloud (Recommended)

Sign up for OpenHands Cloud and get an API key from the API keys page. This gives you access to recommended models with no markup.

Learn more →

Option 2: Direct Provider

Get an API key directly from providers like:

• Anthropic
• OpenAI
• Other LiteLLM-supported providers

Set Your API Key:

export LLM_API_KEY=your-api-key-here

Step 2: Install the SDK

Option 1: Install via PyPI

pip install openhands-sdk # Core SDK (openhands.sdk)
pip install openhands-tools  # Built-in tools (openhands.tools)
# Optional: required for sandboxed workspaces in Docker or remote servers
pip install openhands-workspace # Workspace backends (openhands.workspace)
pip install openhands-agent-server # Remote agent server (openhands.agent_server)

Option 2: Install from Source

# 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

Step 3: Run Your First Agent

Here’s a complete example that creates an agent and asks it to perform a simple task:

examples/01_standalone_sdk/01_hello_world.py

import os

from pydantic import SecretStr

from openhands.sdk import LLM, Conversation
from openhands.tools.preset.default import get_default_agent


# Configure LLM and agent
# You can get an API key from https://app.all-hands.dev/settings/api-keys
api_key = os.getenv("LLM_API_KEY")
assert api_key is not None, "LLM_API_KEY environment variable is not set."
model = os.getenv("LLM_MODEL", "openhands/claude-sonnet-4-5-20250929")
base_url = os.getenv("LLM_BASE_URL")
llm = LLM(
    model=model,
    api_key=SecretStr(api_key),
    base_url=base_url,
    usage_id="agent",
)
agent = get_default_agent(llm=llm, cli_mode=True)

# Start a conversation and send some messages
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

# Send a message and let the agent run
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()

Run the example:

uv run python examples/01_standalone_sdk/01_hello_world.py

You should see the agent understand your request, explore the project, and create a file with facts about it.

Core Concepts

Agent: An AI-powered entity that can reason, plan, and execute actions using tools.

Tools: Capabilities like executing bash commands, editing files, or browsing the web.

Workspace: The execution environment where agents operate (local, Docker, or remote).

Conversation: Manages the interaction lifecycle between you and the agent.

Basic Workflow

1. Configure LLM: Choose model and provide API key
2. Create Agent: Use preset or custom configuration
3. Add Tools: Enable capabilities (bash, file editing, etc.)
4. Start Conversation: Create conversation context
5. Send Message: Provide task description
6. Run Agent: Agent executes until task completes or stops
7. Get Result: Review agent’s output and actions

Try More Examples

The repository includes 24+ examples demonstrating various capabilities:

# Simple hello world
uv run python examples/01_standalone_sdk/01_hello_world.py

# Custom tools
uv run python examples/01_standalone_sdk/02_custom_tools.py

# With microagents
uv run python examples/01_standalone_sdk/03_activate_microagent.py

# See all examples
ls examples/01_standalone_sdk/

Next Steps

Explore Documentation

• SDK Architecture - Deep dive into components
• Tool Documentation - Available tools
• Workspace Options - Execution environments

Build Custom Solutions

• Custom Tools - Create custom tools to expand agent capabilities
• MCP Integration - Connect to external tools via Model Context Protocol
• Docker Workspaces - Sandbox agent execution in containers

Get Help

• Slack Community - Ask questions and share projects
• GitHub Issues - Report bugs or request features
• Example Directory - Browse working code samples