openhands/openhands-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.
• Custom Visualizer: Customize conversation visualization by creating custom visualizers or configuring the default visualizer.
• Deferred Init (Warm-Pool): Pre-warm agent-server pods before a user is matched, then activate them at runtime with POST /api/init.
• Docker Sandbox: Run agent server in isolated Docker containers for security and reproducibility.
• Exception Handling: Provider‑agnostic exceptions raised by the SDK and recommended patterns for handling them.
• FAQ: Frequently asked questions about the OpenHands SDK
• File-Based Agents: Define specialized sub-agents as simple Markdown files with YAML frontmatter — no Python code required.
• Fork a Conversation: Branch off an existing conversation for follow-up exploration without contaminating the original.
• Getting Started: Install the OpenHands SDK and build AI agents that write software.
• Goal Completion Loop: Drive a conversation toward a verifiable objective with a judge-driven, self-continuing completion loop.
• GPT-5 Preset (ApplyPatchTool): Use the GPT-5 preset to build an agent that swaps the standard FileEditorTool for ApplyPatchTool.
• Hello World: The simplest possible OpenHands agent - configure an LLM, create an agent, and complete a task.
• Hooks: Use lifecycle hooks to observe, log, and customize agent execution.
• Image Input: Send images to multimodal agents for vision-based tasks and analysis.
• Interactive Terminal: Enable agents to interact with terminal applications like ipython, python REPL, and other interactive CLI tools.
• Iterative Refinement: Implement iterative refinement workflows where agents refine their work based on critique feedback until quality thresholds are met.
• LLM Fallback Strategy: Automatically try alternate LLMs when the primary model fails with a transient error.
• LLM Profile Store: Save, load, and manage reusable LLM configurations so you never repeat setup code again.
• LLM Registry: Dynamically select and configure language models using the LLM registry.
• LLM Streaming: Stream LLM responses token-by-token for real-time display and interactive user experiences.
• LLM Subscriptions: Use your ChatGPT Plus/Pro subscription to access Codex models without consuming API credits.
• Local Agent Server: Install and run an OpenHands Agent Server on your machine, then connect to it from the SDK.
• Metrics Tracking: Track token usage, costs, and latency metrics for your agents.
• Model Context Protocol: Model Context Protocol (MCP) enables dynamic tool integration from external servers. Agents can discover and use MCP-provided tools automatically.
• Model Routing: Route agent's LLM requests to different models.
• Observability & Tracing: Enable OpenTelemetry tracing to monitor and debug your agent's execution with tools like Laminar, MLflow, Honeycomb, or any OTLP-compatible backend.
• OpenAI-Compatible Endpoint: Call an OpenHands agent-server through the OpenAI Chat Completions protocol.
• OpenHands Cloud Workspace: Connect to OpenHands Cloud for fully managed sandbox environments with optional SaaS credential inheritance.
• Overview: Run agents on remote servers with isolated workspaces for production deployments.
• Parallel Tool Execution: Execute multiple tools concurrently within a single LLM response to improve throughput for independent operations.
• Pause and Resume: Pause agent execution, perform operations, and resume without losing state.
• Persistence: Save and restore conversation state for multi-session workflows.
• Plugins: Plugins bundle skills, hooks, MCP servers, agents, and commands into reusable packages that extend agent capabilities.
• PR Review: Use OpenHands Agent to generate meaningful pull request review
• Reasoning: Access model reasoning traces from Anthropic extended thinking and OpenAI responses API.
• Secret Registry: Provide environment variables and secrets to agent workspace securely.
• Security & Action Confirmation: Control agent action execution through confirmation policy and security analyzer.
• Send Message While Running: Interrupt running agents to provide additional context or corrections.
• Software Agent SDK: Build AI agents that write software. A clean, modular SDK with production-ready tools.
• Stuck Detector: Detect and handle stuck agents automatically with timeout mechanisms.
• Task Tool Set: Delegate complex work to specialized sub-agents that run synchronously and return results to the parent agent.
• Theory of Mind (TOM) Agent: Enable your agent to understand user intent and preferences through Theory of Mind capabilities, providing personalized guidance based on user modeling.
• TODO Management: Implement TODOs using OpenHands Agent

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
• 17_image_input.py
• 18_send_message_while_processing.py
• 19_llm_routing.py
• 20_stuck_detector.py
• 21_generate_extraneous_conversation_costs.py
• 22_anthropic_thinking.py
• 23_responses_reasoning.py
• 24_planning_agent_workflow.py
• 25_agent_delegation.py
• 26_custom_visualizer.py
• 27_observability_laminar.py
• 28_ask_agent_example.py
• 29_llm_streaming.py
• 30_tom_agent.py
• 31_iterative_refinement.py
• 32_configurable_security_policy.py
• 33_hooks
• 34_critic_example.py
• 35_subscription_login.py
• 36_event_json_to_openai_messages.py
• 37_llm_profile_store
• 38_browser_session_recording.py
• 39_llm_fallback.py
• 40_acp_agent_example.py
• 41_task_tool_set.py
• 42_file_based_subagents.py
• 44_model_switching_in_convo.py
• 45_parallel_tool_execution.py
• 46_agent_settings.py
• 47_defense_in_depth_security.py
• 48_conversation_fork.py
• 49_switch_llm_tool.py
• 50_async_cancellation.py
• 51_agent_hooks
• 52_dynamic_workflow.py
• 53_client_defined_tools.py
• 54_goal_completion_loop.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
• 15_openai_compatible_gateway.py
• 16_deferred_init.py
• hook_scripts
• scripts

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