OpenHands SDK

1.16.1 · active · verified Sat Apr 11

The OpenHands SDK is a composable Python library providing core functionality for building AI agents that work with code. It enables defining agents in code and running them locally or at scale in the cloud, serving as the engine behind OpenHands CLI and OpenHands Cloud. As of version 1.16.1, it focuses on modularity, extensibility, and production readiness, with frequent releases aimed at enhanced capabilities and improved user experience.

Warnings

breaking OpenHands V1, which includes this SDK, represents a significant architectural redesign from V0. Older conversations, CLI, and web API configurations are not directly compatible, and changes were made to package management (from poetry to uv) and modularity. Users upgrading from pre-V1 versions should expect to adapt their code and configurations.
Fix: Review the OpenHands V1 migration guide (if available) and adapt configurations, imports, and agent definitions to the new modular structure and API. Ensure `openhands-tools` is installed for common agent tools.
gotcha Common agent tools like `FileEditorTool`, `TerminalTool`, and `TaskTrackerTool` are now part of the separate `openhands-tools` package, not `openhands-sdk`. Attempting to import them directly from `openhands.sdk.tools` will result in an `ImportError`.
Fix: Install `openhands-tools` (`pip install openhands-tools`) and import tools from `from openhands.tools.*`.
gotcha The SDK relies on environment variables like `LLM_API_KEY` and `LLM_MODEL` for LLM configuration. Ensure these are securely managed and correctly set, especially when deploying agents to different environments. A security fix in v1.12.0 for the agent-server highlighted the importance of not inadvertently forwarding sensitive API keys.
Fix: Always use `os.environ.get()` to retrieve API keys and other sensitive configurations. Follow security best practices for credential management in your deployment environment (e.g., Kubernetes secrets, AWS Secrets Manager).
deprecated Older, monolithic components like the `openhands-aci` (Agent Computer Interface) repository have been deprecated, with their functionalities (e.g., file editor tools) migrated into the `openhands-sdk` or `openhands-tools` packages. Relying on deprecated external repositories may lead to outdated or unsupported features.
Fix: Migrate to the equivalent functionalities within the `openhands-sdk` and `openhands-tools` packages, referring to the latest documentation for correct usage.

Install

pip install openhands-sdk Install core SDK

Imports

LLM
```
from openhands.sdk import LLM
```
Agent
```
from openhands.sdk import Agent
```
Conversation
```
from openhands.sdk import Conversation
```
Tool
```
from openhands.sdk import Tool
```
FileEditorTool
```
from openhands.tools.file_editor import FileEditorTool
```
Tools are now in the separate `openhands-tools` package as of V1 for modularity.
TerminalTool
```
from openhands.tools.terminal import TerminalTool
```
Tools are now in the separate `openhands-tools` package as of V1 for modularity.

Quickstart

This quickstart initializes an LLM, an agent with basic tools (Terminal, FileEditor, TaskTracker), and runs a conversation to perform a file-writing task in the current working directory. Ensure `openhands-tools` is installed and `LLM_API_KEY` and `LLM_MODEL` environment variables are set.

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

# Ensure LLM_API_KEY and LLM_MODEL are set in your environment
# Example: export LLM_API_KEY='your_api_key' / export LLM_MODEL='anthropic/claude-sonnet-4-5-20250929'
llm_api_key = os.environ.get('LLM_API_KEY', '')
llm_model = os.environ.get('LLM_MODEL', 'anthropic/claude-sonnet-4-5-20250929') # Placeholder model

llm = LLM(model=llm_model, api_key=llm_api_key)

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(f"Agent will operate in: {cwd}")
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

view raw JSON →