OpenHands Software Agent SDK

SkillCloud & infra

Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the OpenHands Software Agent SDK skill

What this skill tells your AI

The instructions your AI receives, as published by openhands/extensions in skills/openhands-sdk/SKILL.md and read by ahel’s review.

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", "gpt-5.5"),
    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 Goals: Add a resumable goal strategy to a normal agent-server conversation.
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.
Deferred Init (Warm-Pool): Pre-warm agent-server pods before a user is matched, then activate them at runtime with POST /api/init.
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.
Goal Completion Loop: Drive a conversation toward a verifiable objective with a judge-driven, self-continuing completion loop.
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: Install and run an OpenHands Agent Server on your machine, then connect to it from the SDK.
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.
OpenAI-Compatible Endpoint: Call an OpenHands agent-server through the OpenAI Chat Completions protocol.
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.
Persistent Memory: Give agents opt-in, two-tier memory that survives across conversations.
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.
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