openhands-sdk

openhands-sdk is the core package of the OpenHands Software Agent SDK, a clean and modular toolkit for building AI agents that work with code. It provides the primitives to define agents, connect them to LLMs, give them tools, and run multi-step conversations that read, write, and execute code.

Agents built with the SDK can use the local machine as their workspace or run inside ephemeral, sandboxed workspaces such as Docker or Kubernetes via the companion Agent Server. It is the engine behind OpenHands and can be used to build one-off tasks, routine maintenance automations, or entirely new agentic developer experiences.

What You Get

• A modular Agent abstraction for driving multi-step, tool-using coding agents
• An LLM integration layer with support for multiple providers
• A tool system plus MCP (Model Context Protocol) support for extending agent capabilities
• Conversation, event, and context models that structure an agent’s run
• Local and sandboxed workspace execution via the Agent Server

Common Use Cases

• Building agents for one-off tasks like generating a README or scaffolding code
• Automating routine maintenance such as dependency upgrades
• Orchestrating multi-agent workflows for large refactors and rewrites
• Embedding coding-agent capabilities into your own developer tools

Under The Hood

Architecture - The SDK is one package in a uv workspace monorepo (openhands-sdk, openhands-tools, openhands-agent-server, openhands-workspace). Its code lives under openhands-sdk/openhands/sdk/ and is split into focused subpackages: agent (the agent loop), llm (provider integration), tool and mcp (capabilities and Model Context Protocol), conversation and event (run structure), context, workspace, plus extension points like plugin, hooks, subagent, and skills. Agents run against a local workspace or delegate execution to the separate Agent Server for sandboxing.

Tech Stack - Python built and managed with uv across a multi-package workspace, using Pydantic-style typed models (py.typed), an LLM provider layer, and MCP support. The Agent Server package adds a REST API layer for remote/sandboxed execution.

Code Quality - The repo has an extensive tests/ tree spanning cross, integration, examples, and agent_server suites with a shared conftest, a Makefile, and CI, plus contributor and maintainer docs. Consistent updates and a high fork ratio signal healthy, active maintenance.

API Design - The public API is deliberately modular and typed: you construct an Agent with an LLM and tools, then drive a Conversation. The clear separation of tool, llm, and conversation concerns keeps common tasks concise while leaving room for plugins, hooks, and subagents when building more advanced experiences.