openhands-sdk

name	openhands-sdk
description	Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.
triggers	["openhands-sdk","openhands sdk","software-agent-sdk","agent-sdk","/sdk"]

OpenHands Software Agent SDK

All SDK documentation lives at https://docs.openhands.dev/sdk.

For the full topic index, fetch https://docs.openhands.dev/llms.txt and read the "OpenHands Software Agent SDK" section.

Quick reference

Install: pip install openhands-sdk openhands-tools

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=os.getenv("LLM_MODEL", "gpt-5.5"),
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL", None),
)

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)

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

Core classes (openhands.sdk)

Class	Purpose
Agent	Reasoning-action loop
Condenser	Conversation history compression system
Conversation	Conversation orchestration system
Event	Typed event framework
LLM	Provider-agnostic language model interface
SecurityAnalyzer	Action security analysis and validation
Skill	Reusable prompt system
Tool / ToolDefinition	Action-observation tool framework
Workspace	Execution environment abstraction

API reference

openhands.sdk.agent, openhands.sdk.conversation, openhands.sdk.event, openhands.sdk.llm, openhands.sdk.security, openhands.sdk.tool, openhands.sdk.utils, openhands.sdk.workspace

Guides

• ACP Agent: Delegate to an ACP-compatible server (Claude Code, Gemini CLI, etc.) instead of calling an LLM directly.
• Agent Settings: Configure, serialize, and recreate agents from structured settings.
• Agent Skills & Context: Skills add specialized behaviors, domain knowledge, and context-aware triggers to your agent through structured prompts.
• API-based Sandbox: Connect to hosted API-based agent server for fully managed infrastructure.
• Apptainer Sandbox: Run agent server in rootless Apptainer containers for HPC and shared computing environments.
• Ask Agent Questions: Get sidebar replies from the agent during conversation execution without interrupting the main flow.
• Assign Reviews: Automate PR management with intelligent reviewer assignment and workflow notifications using OpenHands Agent
• Browser Session Recording: Record and replay your agent's browser sessions using rrweb.
• Browser Use: Enable web browsing and interaction capabilities for your agent.
• Context Condenser: Manage agent memory by condensing conversation history to save tokens.
• Conversation Goals: Add a resumable goal strategy to a normal agent-server conversation.
• Conversation with Async: Use async/await for concurrent agent operations and non-blocking execution.
• Creating Custom Agent: Learn how to design specialized agents with custom tool sets
• Critic (Experimental): Real-time evaluation of agent actions using an LLM-based critic model, with built-in iterative refinement.
• Custom Tools: Tools define what agents can do. The SDK includes built-in tools for common operations and supports creating custom tools for specialized needs.
• Custom Tools with Remote Agent Server: Learn how to use custom tools with a remote agent server by building a custom base image that includes your tool implementations.

Examples

Source: examples/

01_standalone_sdk/

• 01_hello_world.py
• 02_custom_tools.py
• 03_activate_skill.py
• 04_confirmation_mode_example.py
• 05_use_llm_registry.py
• 06_interactive_terminal_w_reasoning.py
• 07_mcp_integration.py
• 08_mcp_with_oauth.py
• 09_pause_example.py
• 10_persistence.py
• 11_async.py
• 12_custom_secrets.py
• 13_get_llm_metrics.py
• 14_context_condenser.py
• 15_browser_use.py
• 16_llm_security_analyzer.py

02_remote_agent_server/

• 01_convo_with_local_agent_server.py
• 02_convo_with_docker_sandboxed_server.py
• 03_browser_use_with_docker_sandboxed_server.py
• 04_convo_with_api_sandboxed_server.py
• 05_vscode_with_docker_sandboxed_server.py
• 06_custom_tool
• 07_convo_with_cloud_workspace.py
• 08_convo_with_apptainer_sandboxed_server.py
• 09_acp_agent_with_remote_runtime.py
• 10_cloud_workspace_share_credentials.py
• 11_conversation_fork.py
• 12_settings_and_secrets_api.py
• 13_workspace_get_llm.py
• 14_client_defined_tools.py

03_github_workflows/

• 01_basic_action
• 02_pr_review
• 03_todo_management
• 04_datadog_debugging
• 05_posthog_debugging

04_llm_specific_tools/

• 01_gpt5_apply_patch_preset.py
• 02_gemini_file_tools.py

05_skills_and_plugins/

• 01_loading_agentskills
• 02_loading_plugins
• 03_managing_installed_skills
• 04_mixed_marketplace_skills