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

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

Examples

Source: examples/

01standalonesdk/

• 01helloworld.py
• 02customtools.py
• 03activateskill.py
• 04confirmationmodeexample.py
• 05usellmregistry.py
• 06interactiveterminalwreasoning.py
• 07mcpintegration.py
• 08mcpwithoauth.py
• 09pauseexample.py
• 10persistence.py
• 11async.py
• 12customsecrets.py
• 13getllmmetrics.py
• 14contextcondenser.py
• 15browseruse.py
• 16llmsecurityanalyzer.py
• 17imageinput.py
• 18sendmessagewhileprocessing.py
• 19llmrouting.py
• 20stuckdetector.py
• 21generateextraneousconversationcosts.py
• 22anthropicthinking.py
• 23responsesreasoning.py
• 24planningagentworkflow.py
• 25agentdelegation.py
• 26customvisualizer.py
• 27observabilitylaminar.py
• 28askagentexample.py
• 29llmstreaming.py
• 30tomagent.py
• 31iterativerefinement.py
• 32configurablesecuritypolicy.py
• 33hooks
• 34criticexample.py
• 35subscriptionlogin.py
• 36eventjsontoopenaimessages.py
• 37llmprofilestore
• 38browsersessionrecording.py
• 39llmfallback.py
• 40acpagentexample.py
• 41tasktoolset.py
• 42filebasedsubagents.py
• 44modelswitchinginconvo.py
• 45paralleltoolexecution.py
• 46agentsettings.py
• 47defenseindepthsecurity.py
• 48conversationfork.py
• 49switchllmtool.py
• 50asynccancellation.py
• 51agenthooks
• 52dynamicworkflow.py
• 53clientdefinedtools.py
• 54goalcompletionloop.py
• 55persistentmemory.py
• 56structuredoutput.py
• 57prompthooks
• 58askoracletool