Library / SDK
OpenHands/software-agent-sdk avatar
OpenHands/software-agent-sdk

OpenHands SDK: eleven dependency floors tied to advisories, and a quick start cut mid-string

A clean, modular SDK for building AI agents with OpenHands V1.

1,400 stars785 forksPythonMIT

At a glance

What is it?
A four-package uv workspace for building code agents, with an Agent Server, a browser-compatible TypeScript client and a dependency policy that names the CVE behind every floor. The boundaries with two sibling repositories are documented more carefully than the install example.
Who is it for?
The OpenHands Software Agent SDK fits a team building a code agent product that needs the model loop, tools, conversation state and a server boundary to be its own code rather than a wrapper around someone else's runtime. It does not fit someone who wants a single pip install of a finished agent, since this is an SDK plus four workspace packages plus a server.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • OpenHands/software-agent-sdk1,400 ★ · +319
Star history
Repository2026-09-102026-11-15
OpenHands/software-agent-sdk1.1k1.4k

319 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The quick start stops inside an unclosed string

The build-your-first-agent snippet is the first thing a reader copies, and it is cut off mid-call:

python
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),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

What survives is enough to understand the shape, which is the more important half. A model is constructed with an API key taken from the environment rather than passed in. An agent is given tools by name, using the tool class's own name attribute rather than a string literal, which is what lets a tool be registered in one place and referenced here. A conversation binds the agent to a workspace, and in this example the workspace is simply the current working directory.

The last line that remains ends inside the send_message call with an unterminated string, so the file cannot be pasted and run as it stands. For a project that otherwise documents its boundaries and its dependency policy in unusual detail, that is the one place a newcomer will lose time.

Repository boundaries are a contract with two sibling repositories

The section called Repository boundaries is the most useful paragraph in the README, because it says what does not belong here.

This repository owns the canonical Python SDK and the Agent Server implementation, plus the browser-compatible TypeScript client under clients/typescript. It owns agents, tools, conversations, workspaces, events, the REST and WebSocket API, and typed client access to that API.

Everything else has a different owner. The main OpenHands repository consumes the TypeScript client as something called Agent Canvas. The automation repository owns scheduling, webhooks, run history and dispatching. And the SDK with the Agent Server exists to execute the conversations that automation dispatches.

The normal flow is stated as a chain: SDK and Agent Server, then an OpenAPI contract, then the TypeScript client, then Agent Canvas. The placement rules follow from it. Backend behaviour and endpoints belong in the Python SDK or Agent Server packages. Browser-compatible client access belongs in clients/typescript. User interface code belongs in Agent Canvas. Automation lifecycle behaviour belongs in the automation repository.

For a contributor this is the difference between a pull request being merged and being redirected, and it is stated as a placement table rather than as a convention that lives in a contributor guide.

Eleven dependency floors, each one tied to an advisory

The workspace configuration treats dependency security as a first-class concern, with each floor carrying the identifier that motivated it.

The floors are starlette at 0.49.1 or newer for one advisory, aiohttp at 3.13.3 for one advisory plus seven others, urllib3 at 2.6.3 for three, protobuf at 6.33.5, pillow at 12.3.0, orjson at 3.11.7, rich at 14.3.3 because version 14.3.2 has a denial-of-service problem, lupa at 2.8, anyio at 4.14.2 for one advisory tracked as a GitHub security advisory, and pyjwt at 2.14.0.

Two entries are conditioned rather than simple. cryptography is capped below 49 only on macOS on Intel, with the reason written in the file: version 49.0.0 dropped x86_64 macOS wheels while the release workflow still builds on an Intel macOS runner. And litellm is pinned to exactly 1.93.0 as the workspace lock target for a requested upgrade.

Above the floors sits a time-based guardrail. Packages uploaded in the last seven days are excluded, which keeps a supply-chain surprise out of a build. Two packages have date carve-outs that let a specific version through: litellm is allowed up to a July date, and lmnr up to an August date, the latter with a comment explaining that it admits a 0.7.60 streaming-token fix through the guardrail.

That combination is stricter than most projects attempt and also more fragile, because a carve-out is a decision someone has to revisit.

make build checks uv by sorting two version strings

Local development goes through one target. Running make build installs the workspace dependencies and the pre-commit hooks, and the README points at it directly for anyone working from a clone.

The target refuses to run on an old uv. The Makefile requires version 0.8.13, and the check prints both versions, sorts them, and requires the required version to come out first, which is a minimum test written indirectly. When it fails, the message says the installed version is less than required and suggests uv self update.

Everything else is deliberately small. The shell is pinned to bash with strict flags that stop on an unset variable, fail on a command error and fail on a broken pipe. The build itself runs uv sync with the dev group and then installs the pre-commit hooks through uv run. Formatting is ruff format and linting is ruff check with fix applied automatically, so the lint target edits your files rather than only reporting.

The package list is a variable rather than a literal, defaulting to the four workspace members: openhands-sdk, openhands-tools, openhands-workspace and openhands-agent-server. That is the same list the workspace configuration declares, and the fact that both exist means the set of packages is stated twice and has to be kept in step.

The default goal is help rather than build, so running make with no arguments lists the targets instead of installing anything.

setup.py is a stub named openhands-build-context

The root still carries a setup.py, and it is three lines:

python
from setuptools import setup

setup(name="openhands-build-context", version="0.0.0", packages=[])

The name is not a real distribution name, the version is a placeholder, and the package list is empty. So the file installs nothing. It exists for build context, which is what the name says, and the actual installable packages come from the four workspace members declared in the workspace configuration.

It is a small thing, but it is the kind of file that confuses tooling that probes for setup.py first, and it is the only place in the repository where a version of 0.0.0 appears next to released versions in the 1.50 range.

MANIFEST.in sits beside it as the other legacy packaging file, and the release metadata lives elsewhere entirely, in the workspace packages and in the tagged releases.

Other root files describe how the project expects to be worked on. There is an AGENTS.md, a CONTRIBUTING.md, a DEVELOPMENT.md that the README points to for development setup and testing, a MAINTAINERS file, a .python-version, a pre-commit configuration, and two directories whose purpose is not spelled out in the README: .agents/ and .openhands/.

The example list skips 04

The examples directory is described as comprehensive, and four entries are listed. There is a fifth.

01_standalone_sdk covers basic agent usage, custom tools and core workflows. 02_remote_agent_server covers the client-server architecture and WebSocket connections. 03_github_workflows covers CI/CD integration and automated workflows. 05_skills_and_plugins covers AgentSkills, plugins and marketplace examples.

The repository tree also contains 04_llm_specific_tools, and the README does not mention it. That is the only missing description, and it is the one you are most likely to want, because provider-specific tool implementations are exactly what people look for when they are choosing between agents.

The gap also explains why the standalone example is referenced by path later in the file. The minimal example for enabling public skill loading is named as examples/01_standalone_sdk/03_activate_skill.py, which tells you that the standalone folder is numbered internally as well.

For the documented set, the four listed directories map cleanly onto the SDK's three delivery modes. Standalone is in-process. The remote agent server is the split mode with a REST and WebSocket boundary, and it is the one that pairs with ephemeral workspaces. GitHub workflows is the hosted mode. Skills and plugins is the extension mode.

Skills that read your lockfile

The extension mechanism has a specific and rather clever default. Enabling public skills through AgentContext with load_public_skills set to true pulls in the OpenHands/extensions marketplace, which includes skills for tools like uv and deno among others.

The behaviour that follows is the interesting part. An agent can pick up current package-management guidance for a repository by looking at the files that repository already has. A uv.lock marker selects the uv skill, and deno.json, deno.jsonc or deno.lock select the deno skill.

So the guidance is selected by evidence in the repository rather than by configuration. There is nothing to declare, and nothing to keep in sync when a project changes its package manager, because the marker files change first and the agent follows.

That also makes it a supply-chain surface worth thinking about. An agent is being given instructions selected by a remote marketplace and applied on the basis of filenames in a repository, which is convenient in the same way that installing a plugin is convenient. The README notes where the smallest version of this lives, in the third file of the standalone example folder.

The project cites itself with an arXiv entry from 2025, listing the paper title as a composable and extensible foundation for production agents with a primary class of software engineering, and the README carries eight automatically maintained language links. The repository is MIT licensed on the default branch main.

Editorial conclusion

The OpenHands Software Agent SDK fits a team building a code agent product that needs the model loop, tools, conversation state and a server boundary to be its own code rather than a wrapper around someone else's runtime. It does not fit someone who wants a single pip install of a finished agent, since this is an SDK plus four workspace packages plus a server. Verify four things first. Read the dependency constraints rather than trusting the lockfile blindly, because eleven floors are pinned to named advisories and two packages carry date carve-outs that let a specific fix through a seven-day guardrail. Install uv 0.8.13 or newer before running make build, since the build target refuses older versions. Decide where your code belongs, because the repository publishes a hard ownership split across the Python SDK, the TypeScript client, Agent Canvas and the automation repository, and putting a server endpoint in the browser client is exactly what that split exists to prevent. And check which example you are copying, since the quick-start snippet in the README ends inside an unclosed string while the examples directory carries the real ones. Releases 1.49.6, 1.50.0 and 1.50.1 shipped between 2026-09-25 and 2026-09-30, and the last commit on main is dated 2026-10-02.

Frequently asked questions

What is the OpenHands Software Agent SDK?

An MIT licensed Python SDK, plus a browser-compatible TypeScript client and a REST API, for building agents that work with code. Agents can use the local machine as their workspace or run inside ephemeral workspaces in Docker or Kubernetes through the Agent Server, and the SDK is the engine behind the OpenHands CLI and OpenHands Cloud.

Which OpenHands repository owns which part of the system?

This repository owns the canonical Python SDK, the Agent Server, the browser-compatible TypeScript client, agents, tools, conversations, workspaces, events and the REST and WebSocket API. The main OpenHands repository consumes the TypeScript client as Agent Canvas, and OpenHands/automation owns scheduling, webhooks, run history and dispatching.

What does the OpenHands SDK quick start look like?

Construct an LLM with a model name and an API key read from the environment, build an Agent with tools referenced by their class name attribute such as TerminalTool.name and FileEditorTool.name, then create a Conversation binding that agent to a workspace, in the example the current working directory. The snippet in the README ends inside the send_message call.

How does the OpenHands SDK handle package management skills?

Enabling public skills with AgentContext and load_public_skills set to true includes the default OpenHands/extensions marketplace with skills such as uv and deno. Agents then pick up current package-management guidance for repositories whose markers include uv.lock, deno.json, deno.jsonc or deno.lock, and a minimal example is at examples/01_standalone_sdk/03_activate_skill.py.

What dependency policy does the OpenHands SDK workspace apply?

The workspace configuration sets a uv guardrail excluding packages uploaded in the last seven days, plus eleven constraint-dependencies each tied to an advisory, covering starlette, aiohttp, urllib3, protobuf, pillow, orjson, rich, lupa, anyio and pyjwt, with cryptography capped below 49 on Intel macOS and litellm pinned to 1.93.0. Two packages have date carve-outs so specific fixes can pass the guardrail.

Official sources

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

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/openhands-software-agent-sdk.svg)](https://hysenlabs.com/projects/openhands-software-agent-sdk)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/openhands-software-agent-sdk.svg)](https://hysenlabs.com/projects/openhands-software-agent-sdk)

Was this useful?