OpenHands Software Agent SDK
by OpenHands
Build your own coding agent — sandboxed execution, custom tools and multi-LLM routing, all documented.
Overview
The documentation splits into three trunks. Getting Started installs openhands-sdk and openhands-tools with uv or pip, sets LLM_API_KEY and LLM_MODEL, and walks a hello-world agent wired to three built-in tools: terminal, file editor and task tracker. The Architecture section is the conceptual core — Design Principles, Agent, Conversation, Events, LLM, Tool System & MCP, Workspace, Condenser, Skill, Security, and the SDK and Agent Server packages — and it explains the event-sourced conversation model that makes runs resumable, forkable and replayable. Guides is the largest section, covering custom tools, MCP integration, hooks and plugins, context condensers, persistent memory, browser use, an interactive terminal, a stuck detector, an experimental critic, parallel tool execution, LLM routing, fallback chains, streaming, registries and profile stores, observability and tracing, metrics, secret registries, action confirmation, and ready-made GitHub workflows for PR review and TODO management. A dedicated Agent Server track shows the same client API running against Docker, Apptainer, API-based and cloud sandboxes, or behind an OpenAI-compatible gateway. The stack is Python plus a REST and WebSocket agent server, MIT licensed, and model-agnostic across Claude, GPT, Qwen and Devstral. It is maintained by the OpenHands team — Xingyao Wang, Robert Brennan, Graham Neubig and others — whose accompanying paper, arXiv 2511.03690, was accepted at MLSys 2026.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~4-6 hours to work through getting-started plus the architecture section; reference material thereafter
- Provider
- OpenHands
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Stand up a coding agent with terminal, file-editor and task-tracker tools
- ✓Model the agent loop as event-sourced conversations you can pause, fork and resume
- ✓Write custom tools and register MCP servers so agents reach external systems
- ✓Run agents in Docker, Apptainer, API or cloud sandboxes behind one workspace API
- ✓Configure LLM routing, fallback chains, streaming, reasoning and per-model presets
- ✓Condense long contexts and add persistent memory so long tasks survive the window
- ✓Gate risky actions behind security analysis and explicit action confirmation
- ✓Expose an agent as an OpenAI-compatible endpoint or a GitHub PR-review workflow
Highlights
- •Backed by a peer-reviewed paper (arXiv 2511.03690, MLSys 2026) that reports production failure-rate data, not only benchmark scores
- •Sandboxed execution is native rather than bolted on — Docker, Apptainer, Kubernetes and hosted API sandboxes all swap in behind the same workspace API
- •Model-agnostic by design: an LLM registry, routing and fallback chains across Claude, GPT, Qwen and Devstral, plus a GPT-5 ApplyPatchTool preset
- •The parent OpenHands project passed 68K GitHub stars in early 2026 and is widely used as a coding-agent evaluation harness, so the agent loop is heavily exercised
- •Event-sourced conversations make runs forkable, resumable and replayable — the piece most agent SDKs leave you to build yourself
Who It’s For
Best For
- ✓Engineers building an in-house coding agent instead of buying one
- ✓Platform teams that need agents sandboxed in Docker or Kubernetes
- ✓Researchers running agent evaluations on SWE-bench-style harnesses
- ✓Teams leaving a closed agent SDK who need multi-LLM portability
Prerequisites
- •Solid Python, comfortable with async, packaging and uv or pip
- •Working knowledge of an LLM API and tool/function calling
- •Docker basics if you want sandboxed or remote execution
FAQ
What is OpenHands Software Agent SDK?
The official documentation for the Python SDK behind OpenHands, the open-source coding-agent platform. It is written for engineers who need to build and ship agents that actually edit code, run terminal commands and open pull requests rather than chat about them. After working through it you can stand up a custom agent with your own tools, run it inside Docker or Kubernetes, route across multiple LLMs, and expose it behind an OpenAI-compatible endpoint.
Is OpenHands Software Agent SDK free?
OpenHands Software Agent SDK is free to access.
What level is OpenHands Software Agent SDK for?
OpenHands Software Agent SDK is aimed at a intermediate audience. Recommended background: Solid Python, comfortable with async, packaging and uv or pip, Working knowledge of an LLM API and tool/function calling, Docker basics if you want sandboxed or remote execution.
How long does OpenHands Software Agent SDK take?
Expect roughly ~4-6 hours to work through getting-started plus the architecture section; reference material thereafter. Most learners work through it at their own pace.
What will I learn from OpenHands Software Agent SDK?
You'll learn: Stand up a coding agent with terminal, file-editor and task-tracker tools; Model the agent loop as event-sourced conversations you can pause, fork and resume; Write custom tools and register MCP servers so agents reach external systems; Run agents in Docker, Apptainer, API or cloud sandboxes behind one workspace API; Configure LLM routing, fallback chains, streaming, reasoning and per-model presets; Condense long contexts and add persistent memory so long tasks survive the window; Gate risky actions behind security analysis and explicit action confirmation; Expose an agent as an OpenAI-compatible endpoint or a GitHub PR-review workflow.
Topics
Sources
This page was written from 3 sources, 2 on domains other than docs.openhands.dev.