| name | openhands-sdk |
| description | 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. |
| triggers | ["openhands-sdk","openhands sdk","software-agent-sdk","agent-sdk","/sdk"] |
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.
- 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/
