{"id":3721,"library":"openhands-tools","title":"OpenHands Tools - Runtime tools for AI agents","description":"OpenHands Tools is a Python SDK providing runtime components and utilities for building AI agents, including core agent definitions, tools, and conversation management. As of version 1.16.1, it focuses on enabling robust and extensible agent development. The library maintains an active release cadence, with frequent minor updates and significant feature additions in its 1.x releases.","status":"active","version":"1.16.1","language":"en","source_language":"en","source_url":"https://github.com/OpenHands/software-agent-sdk","tags":["AI Agents","SDK","Tools","LLM"],"install":[{"cmd":"pip install openhands-tools","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The PyPI package `openhands-tools` installs the `openhands` Python package. Core modules like `Agent` are found within `openhands.core`.","wrong":"import openhands_tools","symbol":"Agent","correct":"from openhands.core.agent import Agent"},{"note":"Tools are defined within the `openhands.core.tools` submodule, not directly under the top-level `openhands_tools` or `openhands` package.","wrong":"from openhands_tools import Tool","symbol":"Tool","correct":"from openhands.core.tools.tool import Tool"},{"note":"The `Conversation` class manages agent-user interactions and is a key component for agent execution.","symbol":"Conversation","correct":"from openhands.core.conversation import Conversation"}],"quickstart":{"code":"import os\nfrom openhands.core.agent import Agent\nfrom openhands.core.tools.tool import Tool\nfrom typing import List, Dict, Any\n\n# Define a simple tool function\ndef get_current_weather(location: str) -> str:\n    \"\"\"Get the current weather in a given location.\"\"\"\n    # In a real scenario, this would make an API call to a weather service\n    return f\"The weather in {location} is sunny with 25 degrees Celsius.\"\n\n# Create a Tool instance from the function\nweather_tool = Tool(\n    name=\"get_current_weather\",\n    description=\"Get the current weather in a given location\",\n    func=get_current_weather,\n    args_schema={\n        \"location\": {\"type\": \"string\", \"description\": \"The city and state, e.g. San Francisco, CA\"}\n    },\n)\n\n# Define a simple Agent that could potentially use this tool\n# In a real scenario, this agent would be instantiated with an LLM\n# and have more complex logic to interpret tasks and call tools.\nclass MySimpleAgent(Agent):\n    def __init__(self):\n        super().__init__(\n            name=\"SimpleWeatherAgent\",\n            description=\"An agent that can tell the weather.\",\n            tools=[weather_tool]\n        )\n    \n    # The 'run' method would typically interact with an LLM and orchestrate tool usage.\n    # For this quickstart, we'll just demonstrate its structure.\n    def run(self, task: str, *args, **kwargs):\n        print(f\"Agent '{self.name}' received task: '{task}'\")\n        print(f\"Agent's available tools: {[tool.name for tool in self.tools]}\")\n        if \"weather\" in task.lower():\n            print(\"Agent could call 'get_current_weather' if prompted by LLM for weather in a location.\")\n        return \"Agent is ready to process tasks with its tools.\"\n\n# Instantiate and demonstrate the agent\nagent = MySimpleAgent()\nprint(agent.run(\"What's the weather like in New York?\"))\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade 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.","message":"Prior 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.","severity":"breaking","affected_versions":"Before v1.15.0"},{"fix":"Review 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.","message":"The 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.","severity":"breaking","affected_versions":"v1.12.0 and later for integrations built before v1.12.0"},{"fix":"Ensure 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.","message":"Environment 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.","severity":"gotcha","affected_versions":"Before v1.16.0"},{"fix":"Upgrade to v1.13.0 or later for improved reliability and expanded features when developing remote agents, subagents, or complex multi-agent orchestration workflows.","message":"Remote 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.","severity":"gotcha","affected_versions":"Before v1.13.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}