Openhands Sdk

Name: Openhands Sdk
Author: openhands

openhands/extensions

2 installs
134 repo stars
Updated August 4, 2026
openhands/extensions

Build AI software agents with the OpenHands SDK: create custom tools, configure LLMs, manage conversations, and delegate to sub-agents.

About

A reference for the OpenHands Software Agent SDK, the Python framework for building AI agents that write software. A developer uses it to build agents, custom tools, and multi-agent workflows locally or remotely.

Python framework for building AI agents that write software
Create custom tools, configure LLMs, manage conversations, delegate to sub-agents

Openhands Sdk by the numbers

2 all-time installs (skills.sh)
Ranked #13,958 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/openhands/extensions --skill openhands-sdk

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/openhands/extensions/openhands-sdk.svg)](https://skillselion.com/skills/openhands/extensions/openhands-sdk)

Installs	2
repo stars	★ 134
Last updated	August 4, 2026
Repository	openhands/extensions ↗

What it does

Build AI software agents with the OpenHands SDK: create custom tools, configure LLMs, manage conversations, and delegate to sub-agents.

Files

SKILL.mdMarkdownGitHub ↗

OpenHands Software Agent SDK

All SDK documentation lives at <https://docs.openhands.dev/sdk>.

For the full topic index, fetch <https://docs.openhands.dev/llms.txt> and read the "OpenHands Software Agent SDK" section.

Quick reference

Install: pip install openhands-sdk openhands-tools

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!")

Core classes (`openhands.sdk`)

Class	Purpose
`Agent`	Reasoning-action loop
`Condenser`	Conversation history compression system
`Conversation`	Conversation orchestration system
`Event`	Typed event framework
`LLM`	Provider-agnostic language model interface
`SecurityAnalyzer`	Action security analysis and validation
`Skill`	Reusable prompt system
`Tool / ToolDefinition`	Action-observation tool framework
`Workspace`	Execution environment abstraction

API reference

`openhands.sdk.agent`, `openhands.sdk.conversation`, `openhands.sdk.event`, `openhands.sdk.llm`, `openhands.sdk.security`, `openhands.sdk.tool`, `openhands.sdk.utils`, `openhands.sdk.workspace`

Guides

ACP Agent: Delegate to an ACP-compatible server (Claude Code, Gemini CLI, etc.) instead of calling an LLM directly.
Agent Settings: Configure, serialize, and recreate agents from structured settings.
Agent Skills & Context: Skills add specialized behaviors, domain knowledge, and context-aware triggers to your agent through structured prompts.
API-based Sandbox: Connect to hosted API-based agent server for fully managed infrastructure.
Apptainer Sandbox: Run agent server in rootless Apptainer containers for HPC and shared computing environments.
Ask Agent Questions: Get sidebar replies from the agent during conversation execution without interrupting the main flow.
Assign Reviews: Automate PR management with intelligent reviewer assignment and workflow notifications using OpenHands Agent
Browser Session Recording: Record and replay your agent's browser sessions using rrweb.
Browser Use: Enable web browsing and interaction capabilities for your agent.
Context Condenser: Manage agent memory by condensing conversation history to save tokens.
Conversation with Async: Use async/await for concurrent agent operations and non-blocking execution.
Creating Custom Agent: Learn how to design specialized agents with custom tool sets
Critic (Experimental): Real-time evaluation of agent actions using an LLM-based critic model, with built-in iterative refinement.
Custom Tools: Tools define what agents can do. The SDK includes built-in tools for common operations and supports creating custom tools for specialized needs.
Custom Tools with Remote Agent Server: Learn how to use custom tools with a remote agent server by building a custom base image that includes your tool implementations.
Custom Visualizer: Customize conversation visualization by creating custom visualizers or configuring the default visualizer.
Docker Sandbox: Run agent server in isolated Docker containers for security and reproducibility.
Exception Handling: Provider‑agnostic exceptions raised by the SDK and recommended patterns for handling them.
FAQ: Frequently asked questions about the OpenHands SDK
File-Based Agents: Define specialized sub-agents as simple Markdown files with YAML frontmatter — no Python code required.
Fork a Conversation: Branch off an existing conversation for follow-up exploration without contaminating the original.
Getting Started: Install the OpenHands SDK and build AI agents that write software.
GPT-5 Preset (ApplyPatchTool): Use the GPT-5 preset to build an agent that swaps the standard FileEditorTool for ApplyPatchTool.
Hello World: The simplest possible OpenHands agent - configure an LLM, create an agent, and complete a task.
Hooks: Use lifecycle hooks to observe, log, and customize agent execution.
Image Input: Send images to multimodal agents for vision-based tasks and analysis.
Interactive Terminal: Enable agents to interact with terminal applications like ipython, python REPL, and other interactive CLI tools.
Iterative Refinement: Implement iterative refinement workflows where agents refine their work based on critique feedback until quality thresholds are met.
LLM Fallback Strategy: Automatically try alternate LLMs when the primary model fails with a transient error.
LLM Profile Store: Save, load, and manage reusable LLM configurations so you never repeat setup code again.
LLM Registry: Dynamically select and configure language models using the LLM registry.
LLM Streaming: Stream LLM responses token-by-token for real-time display and interactive user experiences.
LLM Subscriptions: Use your ChatGPT Plus/Pro subscription to access Codex models without consuming API credits.
Local Agent Server: Run agents through a local HTTP server with RemoteConversation for client-server architecture.
Metrics Tracking: Track token usage, costs, and latency metrics for your agents.
Model Context Protocol: Model Context Protocol (MCP) enables dynamic tool integration from external servers. Agents can discover and use MCP-provided tools automatically.
Model Routing: Route agent's LLM requests to different models.
Observability & Tracing: Enable OpenTelemetry tracing to monitor and debug your agent's execution with tools like Laminar, MLflow, Honeycomb, or any OTLP-compatible backend.
OpenHands Cloud Workspace: Connect to OpenHands Cloud for fully managed sandbox environments with optional SaaS credential inheritance.
Overview: Run agents on remote servers with isolated workspaces for production deployments.
Parallel Tool Execution: Execute multiple tools concurrently within a single LLM response to improve throughput for independent operations.
Pause and Resume: Pause agent execution, perform operations, and resume without losing state.
Persistence: Save and restore conversation state for multi-session workflows.
Plugins: Plugins bundle skills, hooks, MCP servers, agents, and commands into reusable packages that extend agent capabilities.
PR Review: Use OpenHands Agent to generate meaningful pull request review
Reasoning: Access model reasoning traces from Anthropic extended thinking and OpenAI responses API.
Secret Registry: Provide environment variables and secrets to agent workspace securely.
Security & Action Confirmation: Control agent action execution through confirmation policy and security analyzer.
Send Message While Running: Interrupt running agents to provide additional context or corrections.
Software Agent SDK: Build AI agents that write software. A clean, modular SDK with production-ready tools.
Stuck Detector: Detect and handle stuck agents automatically with timeout mechanisms.
Sub-Agent Delegation: Enable parallel task execution by delegating work to multiple sub-agents that run independently and return consolidated results.
Task Tool Set: Delegate complex work to specialized sub-agents that run synchronously and return results to the parent agent.
Theory of Mind (TOM) Agent: Enable your agent to understand user intent and preferences through Theory of Mind capabilities, providing personalized guidance based on user modeling.
TODO Management: Implement TODOs using OpenHands Agent

Examples

Source: `examples/`

{
  "name": "openhands-sdk",
  "version": "1.0.0",
  "description": "Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversations, sub-agent delegation, MCP integration, security, and persistence.",
  "author": {
    "name": "OpenHands",
    "email": "contact@all-hands.dev"
  },
  "homepage": "https://github.com/OpenHands/extensions",
  "repository": "https://github.com/OpenHands/extensions",
  "license": "MIT",
  "keywords": [
    "sdk",
    "agent",
    "openhands",
    "tools",
    "llm",
    "conversation"
  ]
}