OpenHands Software Agent SDK: a Python, TypeScript and REST SDK for building agents that work with code

The problem: agent loops that touch a real codebase

Most agent frameworks assume the agent talks to an API and returns text. The OpenHands Software Agent SDK assumes the agent edits files and runs commands. The README frames the intended work in three tiers: one-off tasks such as building a README for a repository, routine maintenance such as updating dependencies, and larger efforts such as refactors and rewrites that involve multiple agents. The audience is therefore developers who already have a repository and want an agent to operate on it, rather than developers who want a chat interface.

The second design decision is where that work happens. According to the README, agents can either use the local machine as their workspace, or run inside ephemeral workspaces in Docker or Kubernetes through the Agent Server. That choice is the most consequential thing about the project. A local workspace is simple and gives the agent the same filesystem you have. An ephemeral workspace gives you a disposable boundary, at the cost of a server to run.

The README also states the SDK is the engine behind the OpenHands CLI and OpenHands Cloud. That tells you where the abstraction sits: this repository is infrastructure, and the products built on it live elsewhere.

Agents, tools, conversations and the uv workspace layout

The repository is a uv workspace, not a single package. pyproject.toml lists four members: openhands-sdk, openhands-tools, openhands-workspace and openhands-agent-server. The workspace sources section maps each of those names back into the repository, so a checkout builds them together rather than pulling them from an index. If you install from PyPI you get the published packages; if you clone, you get all four and their internal wiring.

The runtime objects are visible in the README quick start. An LLM wraps a model name and an API key. An Agent combines that LLM with a list of tools. A Conversation binds the agent to a workspace directory. You send a message and call run. Tools are referenced by name, which is why the quick start imports TerminalTool, FileEditorTool and TaskTrackerTool and passes Tool(name=...) rather than instantiating them directly.

The repository boundaries section is unusually explicit about what belongs where. The normal flow is described as SDK/Agent Server, then the OpenAPI contract, then clients/typescript, then Agent Canvas. Backend behaviour and endpoints belong in the Python SDK or Agent Server packages. Browser-compatible client access belongs in clients/typescript. UI belongs in Agent Canvas. Scheduling, webhooks, run history and dispatching belong in OpenHands/automation, which dispatches conversations that this SDK executes. That split matters if you are deciding where to file a patch.

Installing the SDK and running a first conversation

The README does not inline installation commands. It points to the Getting Started Guide at docs.openhands.dev/sdk/getting-started for installation and setup, and says that local development from the repository uses make build to install workspace dependencies and pre-commit hooks. Start from the documented guide rather than guessing a package name.

For repository development, the Makefile defines the target. It first checks the uv version against REQUIRED_UV_VERSION, which is set to 0.8.13, and fails with a message telling you to run uv self update if yours is older. Only then does it sync dependencies.

make build

That target runs uv sync --dev and then uv run pre-commit install. Expect dependency resolution across the four workspace members plus the dev group, which includes pytest, ruff, pyright and pyinstaller.

The README's quick start is the shortest real use. It creates an LLM, gives an agent three tools, points a conversation at the current directory and asks for a file to be written.

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="gpt-5.5", api_key=os.getenv("LLM_API_KEY"))
agent = Agent(llm=llm, tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name), Tool(name=TaskTrackerTool.name)])
conversation = Conversation(agent=agent, workspace=os.getcwd())
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()

After run returns, the README prints All done. The observable result is FACTS.txt in the workspace directory. Note that workspace is set to os.getcwd(), so the agent inherits your working directory. Run this somewhere you are willing to have modified.

For a disposable boundary instead, the examples directory has 02_remote_agent_server for the client-server architecture and WebSocket connections, and 03_github_workflows for CI integration. Those are the paths to read before pointing an agent at anything you care about.

Skills, plugins and the public marketplace

The SDK has a mechanism for injecting package-management guidance into an agent. Enabling load_public_skills=True on AgentContext makes the default OpenHands/extensions marketplace available, and the README names uv and deno skills as examples. Agents pick those up for repositories that carry markers such as uv.lock, deno.json, deno.jsonc or deno.lock.

The point is that an agent asked to add a dependency should use the toolchain the repository already uses, rather than falling back on pip in a uv project. The marker files act as the trigger. The README points to examples/01_standalone_sdk/03_activate_skill.py as a minimal example that turns on public skill loading.

This is also where the design starts to depend on something outside the repository. The marketplace is a separate project, and the README describes the uv and deno skills as examples of what it includes rather than as a fixed list. If your repository uses a package manager with no corresponding skill, the loading flag does nothing useful for you.

Where the SDK is the wrong tool

If you want an application, this is the wrong layer. The README says the SDK is the engine behind the OpenHands CLI and OpenHands Cloud, which means the user-facing surfaces are separate projects. Adopting this repository to get a chat UI, a job scheduler or a run history view means building those yourself, and the repository boundaries section says scheduling, webhooks, run history and dispatching are owned by OpenHands/automation, not here.

The dependency policy is another real constraint. pyproject.toml sets exclude-newer to 7 days under [tool.uv], described in the file as avoiding packages uploaded in the last 7 days. There is an exclude-newer-package map with per-package overrides for litellm and lmnr, which shows the escape hatch exists, but the default is a deliberate lag. If you need a release published this week, you are working against the configuration.

The same file pins constraint-dependencies for security reasons, including litellm==1.93.0 as the workspace lock target, starlette>=0.49.1, aiohttp>=3.13.3, urllib3>=2.6.3, protobuf>=6.33.5, pillow>=12.3.0, orjson>=3.11.7, rich>=14.3.3 and lupa>=2.8, each annotated with a CVE or issue reference. Those constraints apply to the workspace. If your application pins a different version of any of these, expect resolution work.

Finally, the README does not document rollback for an agent run, and does not describe what happens to a local workspace if a conversation goes wrong. Since the quick start passes os.getcwd() as the workspace, the answer is that your files were edited. Use the Agent Server path or version control if that matters.

How this differs from the OpenAI Agents SDK and the Claude Agent SDK

The OpenAI Agents SDK and the Claude Agent SDK both come up when people search for this project, and the difference is worth stating plainly. Those SDKs are built around their vendor's model endpoint and around tool-calling loops that return structured results to your process. The OpenHands Software Agent SDK is built around a workspace: the README's framing is agents that work with code, with the local machine or an ephemeral Docker or Kubernetes workspace as the execution surface.

That changes what the SDK has to own. It ships an Agent Server, a REST and WebSocket API, an OpenAPI contract, and a TypeScript client generated from that contract. None of that is necessary if your agent only calls functions in your own process. It is necessary if the agent runs commands somewhere else and the browser needs to watch.

Model access is not tied to one vendor in the same way. The LLM object takes a model name and an API key, and pyproject.toml pins LiteLLM as a workspace dependency, which is the routing layer. The trade-off is that your provider support is bounded by the LiteLLM version the workspace locks, currently 1.93.0.

Licence, maintenance and what an upgrade costs

The licence is MIT, stated in the README badge and the LICENSE file at the repository root. MIT is permissive: you can use the SDK in a closed product, and the obligations are limited to retaining the copyright and permission notice. That is a description of the licence text, not legal advice for your situation.

Maintenance signals are straightforward. The repository is not archived, and the last push was on 2026-09-10. Releases are frequent: v1.44.1 on 2026-08-28, v1.45.0 on 2026-09-07 and v1.46.0 on 2026-09-09. A project releasing three times in under two weeks will move under you, and the version numbers confirm the SDK is at 1.x with minor releases carrying changes.

The upgrade cost is concentrated in two places. The first is the OpenAPI contract that sits between the Agent Server and clients/typescript, because the README describes that as the normal flow and a contract change ripples into the TypeScript client. The second is the constraint-dependencies list, which is a moving set of security floors. The litellm entry is pinned to an exact version rather than a floor, so a LiteLLM upgrade is a deliberate workspace change, not something a resolver will do for you. Budget for reading release notes on minor bumps rather than assuming they are drop-in.

Editorial conclusion

Adopt the OpenHands Software Agent SDK if you are building an agent loop into your own product and want the workspace boundary to be explicit, either the local machine or an ephemeral Docker or Kubernetes workspace through the Agent Server. Do not adopt it if you want an end-user application: the README points to the OpenHands CLI and OpenHands Cloud for that, and this repository owns the engine and the API contract, not the UI. Before committing, verify the Agent Server deployment path against your own cluster, check that your provider is reachable through the LiteLLM version pinned in pyproject.toml, and read the workspace dependency guardrails, since the 7-day exclude-newer window will block a package you may want on the day it ships.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. OpenHands/software-agent-sdk on GitHub
4. README
5. Releases