OpenHands AI

1.6.0 · active · verified Sat Apr 11

OpenHands is an open-source, model-agnostic platform for AI-driven software development agents that can write, test, and deploy applications. It extends the idea of AI coding assistants into an "agentic" workflow, enabling systems to iteratively plan, take actions, observe results, and continue until a task is complete. It supports various large language models (LLMs) and provides a flexible, sandboxed environment for developing and deploying AI agents. The current version is 1.6.0, with frequent releases, often on a monthly cadence.

Warnings

breaking OpenHands 1.0.0 introduced a 'new software-agent-sdk' and a complete architectural redesign, which broke compatibility with conversations and serialized agent sessions from pre-1.0.0 versions. The V0 API was also deprecated and removed on April 1, 2026.
Fix: For new projects, start with OpenHands 1.0.0 or later. For existing pre-1.0.0 projects, refer to the official migration guides to adapt to the new SDK and V1 API, as old conversations are not directly compatible.
gotcha When running OpenHands with a Docker sandbox, especially in self-hosted deployments or for remote access, ensure `WEB_HOST`, `SANDBOX_CONTAINER_URL_PATTERN`, and `OH_SANDBOX_USE_HOST_NETWORK=true` environment variables are correctly configured. Incorrect settings can lead to connection failures, sandbox errors, or CORS issues.
Fix: Consult the 'Configuration Options' and 'Docker Sandbox' documentation for your OpenHands version to set up these environment variables appropriately for your deployment scenario. For example: `export WEB_HOST=http://your_ip:3000` and `export SANDBOX_CONTAINER_URL_PATTERN=http://your_ip:{port}`.
gotcha An LLM API key (e.g., for Anthropic or OpenAI) is essential for OpenHands to function. Without a valid key configured, the agent cannot interact with the language model and will not be able to perform tasks.
Fix: Provide your LLM API key via the `LLM_API_KEY` environment variable or configure it through the OpenHands UI settings. Also ensure `LLM_MODEL` and `LLM_BASE_URL` are set if using a non-default model or custom endpoint.
deprecated The OpenHands V0 API was deprecated with the release of version 1.0.0 and was officially removed on April 1, 2026. Integrations relying on the V0 API will no longer work.
Fix: Migrate any integrations using the V0 API to the V1 API, which is documented in the OpenHands Cloud API section.
gotcha Tools provided to an OpenHands agent are part of its initial system prompt and cannot be dynamically changed mid-conversation. To modify the set of tools available to an agent, a new conversation must be started, or conversation forking must be utilized.
Fix: Design your agent's toolset carefully at the start of a conversation. If different tools are needed for a new phase of work, initiate a new conversation or leverage conversation forking if supported in your environment.
gotcha While `pip install openhands-ai` installs the SDK, the `openhands` CLI often has specific installation recommendations (e.g., using `uv` or Docker) to ensure the proper sandboxed runtime environment is configured, especially for local GUI or command-line execution.
Fix: If planning to use the OpenHands CLI or local GUI, refer to the official 'Getting Started' or 'CLI QuickStart' documentation for the recommended installation method, which might involve `uv tool install` or Docker commands, in addition to or instead of `pip install openhands-ai`.

Install

pip install openhands-ai Install SDK

Imports

LLM, Agent, Conversation, Tool
```
from openhands.sdk import LLM, Agent, Conversation, Tool
```
These are core components for building and running an OpenHands AI agent.

FileEditorTool, TaskTrackerTool, TerminalTool

from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool

These are common tools used by OpenHands agents, imported from the 'openhands.tools' sub-package.

Quickstart

This quickstart demonstrates how to initialize an LLM, create an agent with basic tools (Terminal, FileEditor, TaskTracker), set up a conversation in the current working directory, and assign a simple file-writing task. Ensure `LLM_API_KEY` and optionally `LLM_MODEL` are set in your environment variables.

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

# NOTE: Replace with your actual LLM_API_KEY and desired model
llm = LLM(
    model=os.environ.get("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.environ.get("LLM_API_KEY", ""), # Ensure LLM_API_KEY is set in your environment
    base_url=os.environ.get("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)

print("Sending task to agent...")
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("Agent finished.")

view raw JSON →