快速开始

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.

<AccordionGroup>

Bring your own API key from providers like:

* [Anthropic](https://console.anthropic.com/)
* [OpenAI](https://platform.openai.com/)
* [Other LiteLLM-supported providers](https://docs.litellm.ai/docs/providers)

Example:

export LLM_API_KEY="your-api-key"
uv run python examples/01_standalone_sdk/01_hello_world.py

Sign up for [OpenHands Cloud](https://app.all-hands.dev), add credits to your account, and get your OpenHands LLM API key from the [API keys page](https://app.all-hands.dev/settings/api-keys). This gives you access to models verified to work well with OpenHands, with no markup.

Example:

export LLM_MODEL="openhands/claude-sonnet-4-5-20250929"
uv run python examples/01_standalone_sdk/01_hello_world.py

[Learn more →](https://docs.openhands.dev/openhands/usage/llms/openhands-llms)



If you have a ChatGPT Plus or Pro subscription, you can use `LLM.subscription_login()` to authenticate with your ChatGPT account and access Codex models without consuming API credits.

from openhands.sdk import LLM

llm = LLM.subscription_login(vendor="openai", model="gpt-5.2-codex")

[Learn more →](https://docs.openhands.dev/sdk/guides/llm-subscriptions)

</AccordionGroup>

Tip: Model name prefixes depend on your provider

• If you bring your own provider key (Anthropic/OpenAI/etc.), use that provider's model name, e.g. anthropic/claude-sonnet-4-5-20250929 OpenHands supports dozens of models, you can choose the model you want to try.
• If you use OpenHands Cloud, use openhands/-prefixed models, e.g. openhands/claude-sonnet-4-5-20250929

Many examples in the docs read the model from the LLM_MODEL environment variable. You can set it like:

bash theme={null} export LLM_MODEL="openhands/claude-sonnet-4-5-20250929" # for OpenHands Provider

Set Your API Key:

export LLM_API_KEY=your-api-key-here

Step 2: Install the SDK

<AccordionGroup>

# Core SDK + built-in tools — install together so their versions stay aligned
pip install -U openhands-sdk openhands-tools

# Optional: sandboxed workspaces in Docker or remote servers.
# List every package in one command so they all resolve to the same version.
pip install -U openhands-sdk openhands-tools openhands-workspace openhands-agent-server

  `openhands-sdk` and `openhands-tools` are a matched set: they are built, tested, and released together at the same version number, and `openhands-tools` imports `openhands-sdk` internals directly. Always install and upgrade them in a **single** `pip` command so their versions match. Installing them separately can leave a newer `openhands-tools` against an older `openhands-sdk` (for example, when a previously installed copy is not upgraded), which fails at import with errors like `ModuleNotFoundError: No module named 'openhands.sdk.utils.path'`. To pin a specific release, use the same version for both, e.g. `pip install "openhands-sdk==1.22.1" "openhands-tools==1.22.1"`.

# Clone the repository
git clone https://github.com/OpenHands/software-agent-sdk.git
cd software-agent-sdk

# Install dependencies and setup development environment
make build

</AccordionGroup>

Step 3: Run Your First Agent

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

import os

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool

llm = LLM(
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL", None),
)

agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

Run the example:

# Using a direct provider key (Anthropic/OpenAI/etc.)
uv run python examples/01_standalone_sdk/01_hello_world.py

# Using OpenHands Cloud
export LLM_MODEL="openhands/claude-sonnet-4-5-20250929"
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 skills
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 System - Available tools
• Workspace Architecture - Execution environments
• LLM Configuration - Deep dive into language model configuration

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

Welcome to OpenHands, a community focused on AI-driven development

🙌 Welcome to OpenHands, a community focused on AI-driven development. We'd love for you to join us on Slack.

There are a few ways to work with OpenHands:

Agent Canvas

Agent Canvas is the open-source browser client and control center for agent conversations and automations. It connects to one or more Agent Server backends.

The agent-canvas launcher can start Canvas with local backend services as an all-in-one stack. You can also run the client separately and connect it to a local, self-hosted, Cloud, or Enterprise backend.

Get started with Agent Canvas or view the source.

OpenHands Software Agent SDK and Agent Server

The Software Agent SDK is a composable Python library for building agents that work with code. The same repository contains Agent Server, which exposes agent execution, conversations, tools, and workspaces through REST and WebSocket APIs.

Get started with the SDK or view the source.

OpenHands Cloud

OpenHands Cloud is the managed commercial service for running OpenHands without operating your own backend and sandbox infrastructure. It provides hosted execution, integrations, collaboration, access controls, usage reporting, and budget management.

Open Agent Canvas to sign in and try it.

OpenHands Enterprise

OpenHands Enterprise provides commercial capabilities and support for organizations that need licensed self-hosting or managed deployment options.

Learn more at openhands.dev/enterprise.

Sandbox Server

Sandbox Server is the community-supported standalone OpenHands API and sandbox control plane. It creates and manages sandboxed environments that host Agent Server. It can be configured to use Agent Canvas as its browser client.

Component And Repository Map

Each public repository includes its own license. Check the repository you use or modify instead of assuming one license applies to the entire ecosystem.

Legacy

The archived OpenHands/legacy snapshot also preserves the previous backend and runtime architecture for historical reference.

OpenHands CLI

The CLI is a terminal-based interface powered by the Software Agent SDK. It is feature-complete and primarily maintained for stability.

Check out the docs or view the source.

OpenHands Legacy Local GUI

The Local GUI is the deprecated Docker-based browser application from the former OpenHands monorepo. Use Agent Canvas for active browser-client development.

View the pinned source.

Community

Explore all OpenHands repositories and join us on Slack.