Install & Compatibility
Where this runs
tested against v1.44.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✓ 41s
py 3.13
✕ build_error
✓ 37.2s
py 3.9
✕ build_error
✕ build_error
523MB installed
● package 523MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from openhands_tools import Agent
✗ from openhands import Agent
This quickstart demonstrates how to define a custom tool and create a basic `Agent` that is configured with this tool. In a full OpenHands runtime, the agent's `run` method would interact with an LLM to dynamically select and execute tools based on the given task.
import os
from openhands.core.agent import Agent
from openhands.core.tools.tool import Tool
from typing import List, Dict, Any
# Define a simple tool function
def get_current_weather(location: str) -> str:
"""Get the current weather in a given location."""
# In a real scenario, this would make an API call to a weather service
return f"The weather in {location} is sunny with 25 degrees Celsius."
# Create a Tool instance from the function
weather_tool = Tool(
name="get_current_weather",
description="Get the current weather in a given location",
func=get_current_weather,
args_schema={
"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
},
)
# Define a simple Agent that could potentially use this tool
# In a real scenario, this agent would be instantiated with an LLM
# and have more complex logic to interpret tasks and call tools.
class MySimpleAgent(Agent):
def __init__(self):
super().__init__(
name="SimpleWeatherAgent",
description="An agent that can tell the weather.",
tools=[weather_tool]
)
# The 'run' method would typically interact with an LLM and orchestrate tool usage.
# For this quickstart, we'll just demonstrate its structure.
def run(self, task: str, *args, **kwargs):
print(f"Agent '{self.name}' received task: '{task}'")
print(f"Agent's available tools: {[tool.name for tool in self.tools]}")
if "weather" in task.lower():
print("Agent could call 'get_current_weather' if prompted by LLM for weather in a location.")
return "Agent is ready to process tasks with its tools."
# Instantiate and demonstrate the agent
agent = MySimpleAgent()
print(agent.run("What's the weather like in New York?"))
Debug
Known issues
breakingPrior to v1.15.0, the SDK's core API underwent more frequent breaking changes, especially concerning agent and tool interfaces. Users migrating from significantly older versions may encounter incompatibilities.fixUpgrade to v1.15.0 or later for enhanced API stability. Always review the GitHub release notes and migration guides carefully when upgrading across major features or several minor versions.
affects: Before v1.15.0
breakingThe introduction of the Agent Client Protocol (ACP) in v1.12.0 fundamentally changed how agents communicate and are implemented, particularly for custom `ACPAgent` implementations or remote interactions.fixReview the new ACP documentation and update agent implementations to conform to the new protocol if targeting ACP-enabled features or migrating older agents. Consider `ACPAgent` for new client-server agent setups.
affects: v1.12.0 and later for integrations built before v1.12.0
gotchaEnvironment variables (`${VAR}`) in certain server configuration fields might not have been reliably resolved in versions prior to v1.16.0, leading to unexpected runtime behavior or incorrect settings.fixEnsure environment variables are explicitly passed where needed, or upgrade to v1.16.0+ for more consistent `${VAR}` resolution behavior across all MCP server configuration fields. affects: Before v1.16.0
gotchaRemote and subagent functionality was significantly enhanced in v1.12.0 and v1.13.0. Users employing complex multi-agent or remote execution patterns in earlier versions may have encountered limitations or less robust behavior.fixUpgrade to v1.13.0 or later for improved reliability and expanded features when developing remote agents, subagents, or complex multi-agent orchestration workflows.
affects: Before v1.13.0
Upgrade
Version history
1.44.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
No dependency data recorded yet.