Introduction

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

The OpenHands SDK allows you to build things with agents that write software. For instance, some use cases include:

1. A documentation system that checks the changes made to your codebase this week and updates them
2. An SRE system that reads your server logs and your codebase, then uses this info to debug new errors that are appearing in prod
3. A customer onboarding system that takes all of their documents in unstructured format and enters information into your database

This SDK also powers OpenHands, an all-batteries-included coding agent that you can access through a GUI, CLI, or API.

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

• Python 3.12+
• uv package manager (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 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

For more detailed documentation and examples, refer to the examples/ directory which contains comprehensive usage examples covering all major features of the SDK.