How to Build Your First Autonomous Coding Agent with OpenHands SDK

The landscape of software development is undergoing its most profound transformation since the advent of integrated development environments. According to recent GitHub surveys, 92% of developers are already using AI coding tools in some capacity, with autonomous agents representing the next evolutionary leap beyond simple autocomplete and chat interfaces. These agents don’t just suggest code—they plan, execute, debug, and iterate independently, fundamentally reshaping how we build software.

Enter OpenHands, the open-source framework that has emerged as the community standard for autonomous coding agents. With over 64,000 GitHub stars and adoption by major enterprises, OpenHands represents a shift from proprietary black-box solutions to transparent, extensible, and model-agnostic agent architectures. This guide walks you through building your first autonomous coding agent using the OpenHands Software Agent SDK—a composable Python framework designed for everything from quick prototyping to enterprise-scale deployments.

What Is OpenHands and Why It Matters

OpenHands is more than a single product; it’s a comprehensive ecosystem for AI-driven development. The project encompasses four primary interfaces: the Software Agent SDK (the composable engine), a CLI for terminal-based workflows, a Local GUI with REST API and React frontend, and OpenHands Cloud for hosted deployments. What distinguishes OpenHands from alternatives is its architectural philosophy: stateless, immutable components with type-safe Pydantic models, designed for seamless local-to-remote execution portability.

The SDK’s emphasis on coding distinguishes it from general-purpose agent frameworks like LangChain. While LangChain excels at chat-based support and back-office automation, OpenHands is purpose-built for software engineering. This focus has paid dividends in benchmark performance—OpenHands consistently ranks as a top performer on SWE-bench, SWT-bench, and multi-SWE-bench evaluations. The framework has become the preferred harness for evaluating LLMs on coding tasks, with researchers from institutions including Carnegie Mellon contributing to its development.

Critically, OpenHands is MIT-licensed and model-agnostic. Unlike proprietary alternatives such as Claude Code or OpenAI’s Codex that lock users into specific models, OpenHands works with any LLM—from Anthropic’s Claude and OpenAI’s GPT to open-source alternatives like Qwen, DeepSeek, and Mistral’s Devstral. Given the pace of model evolution, this flexibility isn’t merely convenient; it’s strategically essential.

Architecture Overview

The OpenHands Software Agent SDK organizes functionality into four distinct Python packages, enabling developers to import only what they need:

Package	Purpose	Required
openhands-sdk	Core agent framework + base workspace classes	Always
openhands-tools	Pre-built tools (bash, file editing, etc.)	Optional
openhands-workspace	Extended workspace implementations (Docker, remote)	Optional
openhands-agent-server	Multi-user API server	Optional

The SDK supports two deployment architectures. Local Development mode runs everything in a single process with LocalWorkspace, requiring no Docker—ideal for prototyping. Production/Sandboxed mode uses RemoteWorkspace to auto-spawn agent servers in containers, enabling sandboxed execution for security, multi-user deployments, and distributed systems on Kubernetes.

The core execution flow follows a reasoning-action loop: the Agent calls the LLM for decisions, executes Tools to perform actions, and manages state through immutable Events. Components include the Agent (reasoning-action loop), Conversation (state management), LLM interface (provider-agnostic with retry logic), Tool System (typed Action/Observation/Executor pattern), and Security module (action risk assessment).

Step-by-Step Tutorial

Let’s build a basic autonomous coding agent. First, install the prerequisites:

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the SDK
uv tool install openhands --python 3.12

Set your LLM credentials:

export LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"
export LLM_API_KEY="your-api-key-here"

Now create your first agent:

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

# Configure the LLM
llm = LLM(
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL", None),
)

# Create the agent with tools
agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

# Set up workspace and conversation
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

# Send a task and run
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

For sandboxed execution, wrap the workspace in a Docker container:

from openhands.workspace import DockerWorkspace
from openhands.tools.preset.default import get_default_agent

with DockerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
    platform="linux/amd64",  # or linux/arm64 for Apple Silicon
) as workspace:
    agent = get_default_agent(llm=llm, cli_mode=True)
    conversation = Conversation(agent=agent, workspace=workspace)
    conversation.send_message("Refactor the codebase to use type hints.")
    conversation.run()

The SDK provides 24+ examples covering custom tools, MCP integration, microagents, browser automation, and GitHub workflows. Each follows the same pattern: configure LLM → create Agent → add Tools → start Conversation → send message → run.

Comparison with Alternatives

The autonomous coding agent space features several notable contenders. Devin from Cognition AI made headlines as the first autonomous AI software engineer, but remains a closed commercial product with waitlist access. Claude Code from Anthropic offers a polished terminal experience but requires Claude models exclusively. GitHub Copilot provides excellent inline suggestions but lacks autonomous planning and execution capabilities.

OpenHands differentiates through openness and flexibility. Devin and Claude Code offer superior out-of-box polish, but lock users into proprietary ecosystems. OpenHands’ model-agnostic design lets teams switch between Claude, GPT, Gemini, DeepSeek, or local models like Devstral without rewriting agent logic. The SDK approach also enables deeper customization—teams can build entirely new developer experiences rather than being confined to pre-built interfaces.

Performance benchmarks tell a compelling story. OpenHands achieves state-of-the-art results on SWE-bench Verified, with the research team contributing innovations including task planning and decomposition, automatic context compression, and security analysis. The framework has been adopted as the evaluation harness by major model providers, including Alibaba’s Qwen team.

Deployment Options

OpenHands offers deployment flexibility spanning local development to enterprise Kubernetes clusters:

Local GUI: Run openhands serve to launch a web interface at localhost:3000, complete with VS Code integration and browser automation via VNC.

CLI Mode: Execute openhands for a terminal experience comparable to Claude Code, supporting both interactive sessions and scriptable automation.

OpenHands Cloud: The hosted commercial offering provides $10 in free credits, deeper GitHub/GitLab/Bitbucket integrations, Slack/Jira/Linear connectivity, multi-user support, RBAC, and usage reporting.

Self-Hosted Enterprise: For organizations requiring VPC deployment, OpenHands Enterprise offers Kubernetes-based self-hosting with extended support and research team access. The enterprise version is source-available, with licensing required beyond one month of use.

SDK-First Deployment: For custom applications, the SDK enables programmatic deployment—embed agents in CI/CD pipelines, build internal developer tools, or create specialized coding assistants.

Conclusion and Future Outlook

The OpenHands Software Agent SDK represents a maturation point for autonomous coding technology. By combining research-grade performance with production-ready architecture, it bridges the gap between experimental prototypes and reliable developer tools. The framework’s emphasis on composability, model-agnosticism, and transparent execution addresses the real-world concerns of engineering teams evaluating AI agents.

Looking ahead, several trends will shape this space. Multi-agent collaboration—where specialized agents handle different aspects of development—will become standard. The integration of browser automation, as demonstrated by OpenHands’ VNC capabilities, points toward agents that can navigate full-stack workflows including frontend testing and documentation review. Security sandboxing will move from optional to mandatory as organizations deploy agents with broader system access.

For developers and engineering leaders, the message is clear: autonomous coding agents are transitioning from novelty to necessity. The OpenHands SDK provides the most transparent, flexible path to adopting this technology—whether you’re automating dependency updates, refactoring legacy codebases, or building entirely new AI-powered development experiences. With its open-source foundation and active research community, OpenHands isn’t just keeping pace with the autonomous coding revolution; it’s helping define it.

---

Sources: OpenHands Documentation (docs.openhands.dev), OpenHands GitHub Repository (64k+ stars), arXiv:2511.03690, SWE-bench Leaderboards (swebench.com), Anthropic Claude Code Documentation, Docker Workspace Documentation, Enterprise Deployment Guide, Software Agent SDK Guide, Local Setup Documentation, LLM Configuration Guide, SDK Architecture Overview