OpenHands Software Agent SDK: a Python, TypeScript and REST toolkit for agents that edit code
A clean, modular SDK for building AI agents with OpenHands V1.
At a glance
- What is it?
- The SDK splits agent execution into a Python core, an OpenAPI contract and a browser client, and lets the same agent run on your laptop or inside an ephemeral container. It is a good fit if you are building code-modifying agents into your own product; it is the wrong tool if you want a finished assistant.
- Who is it for?
- Adopt it if you are embedding code-editing agents into your own product and want the execution loop, tool schema and workspace abstraction handled for you. Do not adopt it if you need a finished assistant UI, or if your runtime is not Python or TypeScript, since the SDK ships only those two client surfaces plus REST.
- 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 September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem it solves: an agent loop that can actually touch a repository
Most agent frameworks hand you a chat loop and leave the filesystem to you. This SDK takes the opposite position. Its unit of work is a conversation bound to a workspace, and its default tools are a terminal, a file editor and a task tracker. The README's quick start has the agent write a file called FACTS.txt into the current directory, which is a small illustration of the actual claim: the agent is expected to change real files, not describe changes.
The stated use cases run from one-off chores (generating a README) through routine maintenance (dependency updates) to multi-agent refactors and rewrites. That ordering matters. The first two are single-conversation jobs where you can read the diff afterwards. The third is where the architecture gets interesting and where the operational burden lands on you.
Who it is for, judging by the repository boundaries section, is developers building developer tools. The README says the SDK is the engine behind the OpenHands CLI and OpenHands Cloud, and that a separate repository, OpenHands/automation, owns scheduling, webhooks and run history. If you are building the thing that decides when an agent runs, this is a component, not a product.
How the pieces fit: Python core, OpenAPI contract, TypeScript client
The README is unusually explicit about ownership boundaries, and that is the most useful part of the document. This repository owns the canonical Python SDK and the Agent Server implementation, plus a 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.
The flow is stated as a one-way pipeline: SDK/Agent Server, then the OpenAPI contract, then clients/typescript, then Agent Canvas. Backend behaviour and endpoints belong in the Python packages. Browser-compatible client access belongs in the TypeScript client. UI belongs in Agent Canvas. Automation lifecycle behaviour belongs in the automation repository.
That is a contract-first design, and it has a consequence worth naming. The TypeScript client is generated from the server's OpenAPI description rather than hand-written against it. If you upgrade the server and regenerate the client, you get type errors instead of silent field mismatches. The cost is that client and server versions are coupled: a client built against one contract is not guaranteed to work against a server that has moved on.
Execution itself is split by workspace. The README says agents can use the local machine as their workspace, or run inside ephemeral workspaces in Docker or Kubernetes using the Agent Server. The quick start takes the first path, passing os.getcwd() as the workspace. The remote path is the one the examples directory covers separately, under examples/02_remote_agent_server/, described as client-server architecture and WebSocket connections.
Getting a first conversation running
The README's quick start is a single Python file. It imports LLM, Agent, Conversation and Tool from openhands.sdk, then three tool classes from separate modules: FileEditorTool from openhands.tools.file_editor, TaskTrackerTool from openhands.tools.task_tracker, and TerminalTool from openhands.tools.terminal.
The LLM is constructed with a model string and an API key read from the environment: LLM(model="gpt-5.5", api_key=os.getenv("LLM_API_KEY")). The Agent takes that LLM plus a list of Tool objects, each built by name, for example Tool(name=TerminalTool.name). The Conversation is then created with agent=agent and workspace=cwd, where cwd is os.getcwd(). You call conversation.send_message() with a natural-language instruction and then conversation.run().
Two things about this shape are worth noting. Tools are referenced by name rather than by instance, so the tool registry is doing lookup work at construction time. And the workspace is an explicit argument, not an ambient setting, which is what makes the local and containerised modes interchangeable at the call site.
The README does not include the pip install line in the excerpt provided; it points to the Getting Started Guide at docs.openhands.dev/sdk/getting-started for installation. For working from the repository itself, it gives one command: make build, described as installing the workspace dependencies and pre-commit hooks. I have not run any of this, so treat the exact package name as something to confirm against the getting-started page.
Skills, marketplaces and the AgentContext switch
There is a second layer above tools. The README describes enabling public skills with AgentContext(load_public_skills=True), which pulls from a default marketplace at OpenHands/extensions. The example given is package-management guidance: uv and deno skills that activate when a repository contains markers like uv.lock, deno.json, deno.jsonc or deno.lock.
This is a different mechanism from tools. A tool is a capability the agent can invoke. A skill, as described here, is context that gets attached when a marker file is present. The design intent is that an agent working in a repository using uv picks up current uv guidance without you writing it into a prompt.
The trade-off is that skill activation depends on file markers, so it is a heuristic. A repository that uses uv without committing uv.lock, or one that commits a lock file for a different tool, will not trigger the skill. The README points to examples/01_standalone_sdk/03_activate_skill.py as the minimal example for turning public skill loading on, which is the place to look if you want to see what the marketplace actually injects.
Loading from a public marketplace also means your agent's behaviour depends on content you do not control and did not review. The README does not describe a pinning or versioning mechanism for marketplace skills. If you enable load_public_skills=True in a production agent, that is a supply-chain surface you are accepting, and the documentation excerpt does not tell you how to freeze it.
The Agent Server boundary and what it costs you
Running the agent on your own machine is the simple path. Running it in Docker or Kubernetes through the Agent Server is the path that makes multi-tenant or CI use viable, and it is also where the operational weight sits. The README frames this as a benefit (ephemeral workspaces) and it genuinely is one, because a container that gets thrown away after a conversation cannot leave a mess in your home directory.
What the README does not describe, at least in the portion available, is the isolation model in any detail. Ephemeral is not the same as sandboxed. A workspace that is destroyed after use still had network access and whatever credentials you passed into it during the run. The Agent Server API reference is linked separately at docs.openhands.dev/sdk/guides/agent-server/api-reference/server-details/alive, which suggests the details live there rather than in the README.
This is the point where I would slow down before adopting. The interesting question is not whether the container is ephemeral, it is what the agent can reach from inside it. The README does not answer that, and I am not going to guess. Treat the workspace isolation model as the first thing to verify against your own threat model, particularly if the agent is reading untrusted content such as issues or pull request bodies.
There is a second boundary cost. The README assigns scheduling, webhooks, run history and dispatching to the separate OpenHands/automation repository. If you want any of those, you are either adopting a second component or building them yourself. The SDK executes conversations that something else dispatched.
Where this is the wrong choice
If you want an assistant, this is not it. The SDK gives you Conversation and run(). It does not give you a chat interface, a permission prompt before a destructive command, or a diff review step. Those live in Agent Canvas or in whatever you build. The README's quick start ends with print("All done!") and no inspection of what changed.
Language coverage is the second constraint. The repository ships Python and TypeScript client surfaces plus REST. If your stack is Go, Java or Rust, you are writing an HTTP client against the OpenAPI contract by hand, and you inherit the version coupling described earlier without the generated types that make it manageable.
Third, the release cadence is fast. The three most recent releases listed are v1.46.0 on 2026-09-09, v1.45.0 two days earlier, and v1.44.1 on 2026-08-28. That is a minor version roughly every few days in the recent window. For a library that owns your agent's execution loop, that pace means you need a pinning and upgrade story before you start, not after. Nothing in the README describes a long-term support line or a stability guarantee for the API surface.
Finally, the SDK is opinionated about what an agent is: an LLM plus named tools plus a workspace, driven by a conversation. If your design does not fit that shape, you will spend your time working around the abstraction rather than with it.
Alternatives and the actual difference in approach
The clearest comparison is with a general-purpose agent framework such as LangGraph or the OpenAI Agents SDK. Those treat tools and control flow as things you compose, and they are indifferent to what the tools do. A file-editing tool is something you write. The OpenHands SDK ships the file editor, terminal and task tracker as first-class tools and makes the workspace a parameter of the conversation, so the code-execution case is the default rather than an integration you assemble.
The second comparison is with running the full OpenHands application. The README states that this SDK is the engine behind the OpenHands CLI and OpenHands Cloud, and that the OpenHands/OpenHands repository consumes the TypeScript client as Agent Canvas. If you want a working assistant today, the application is the shorter path. The SDK is for when you need the loop embedded in your own product, with your own UI and your own dispatch logic.
A third, narrower comparison is with a plain container plus a shell script. That gives you isolation and reproducibility with no agent abstraction at all. You would lose the tool schema, the event stream, and the OpenAPI contract that lets a browser client follow a run over WebSocket. Whether that loss matters depends entirely on whether you need to observe runs from outside the process.
Licence, maintenance and what to check before you pin a version
The licence is MIT, per the repository metadata and the licence badge in the README. That is permissive: you can use it in closed-source products, and the main obligation is preserving the copyright notice and licence text. This is a description of the licence, not legal advice; if you are redistributing it or bundling it into a product with its own compliance process, have someone qualified read the actual LICENSE file rather than this paragraph.
The maintenance cost is dominated by the release cadence. With minor versions landing days apart, the practical work is not fixing bugs in the SDK, it is keeping your integration aligned with a moving target. Two specific things to check on each upgrade: whether the OpenAPI contract changed in a way that invalidates your generated TypeScript client, and whether the tools you referenced by name still exist under the same module paths. The quick start imports from openhands.tools.file_editor, openhands.tools.task_tracker and openhands.tools.terminal, so those module paths are part of what you are depending on.
If you enable AgentContext(load_public_skills=True), add a third check: what the OpenHands/extensions marketplace is currently serving, since the README does not describe a way to pin it. For a repository whose whole job is executing code, that is the upgrade surface I would watch most closely.
Editorial conclusion
Adopt it if you are embedding code-editing agents into your own product and want the execution loop, tool schema and workspace abstraction handled for you. Do not adopt it if you need a finished assistant UI, or if your runtime is not Python or TypeScript, since the SDK ships only those two client surfaces plus REST. Before committing, verify the Agent Server's workspace isolation model against your own threat model, and check that the version you pin still matches the OpenAPI contract your client was generated from.
Community notes