OpenHands Tools - Runtime tools for AI agents

1.16.1 · active · verified Sat Apr 11

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.

Warnings

breaking 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.
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.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install openhands-tools Install latest version

Imports

Agent
```
from openhands.core.agent import Agent
```
The PyPI package `openhands-tools` installs the `openhands` Python package. Core modules like `Agent` are found within `openhands.core`.
Tool
```
from openhands.core.tools.tool import Tool
```
Tools are defined within the `openhands.core.tools` submodule, not directly under the top-level `openhands_tools` or `openhands` package.
Conversation
```
from openhands.core.conversation import Conversation
```
The `Conversation` class manages agent-user interactions and is a key component for agent execution.

Quickstart

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?"))

view raw JSON →