openhands.sdk.tool

API reference for openhands.sdk.tool module

class Action

Bases: Schema, ABC

Base schema for input action.

Properties

• kind: str
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• visualize: Text Return Rich Text representation of this action. This method can be overridden by subclasses to customize visualization. The base implementation displays all action fields systematically.

class ExecutableTool

Bases: Protocol

Protocol for tools that are guaranteed to have a non-None executor.

This eliminates the need for runtime None checks and type narrowing when working with tools that are known to be executable.

Properties

• executor: ToolExecutor[Any, Any]
• name: str

Methods

init()

class FinishTool

Bases: ToolDefinition[FinishAction, FinishObservation]

Tool for signaling the completion of a task or conversation.

Properties

• kind: Literal[‘FinishTool’]
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• name: ClassVar[str] = ‘finish’

Methods

classmethod create()

Create FinishTool instance.

• Parameters:
  • conv_state – Optional conversation state (not used by FinishTool). params* – Additional parameters (none supported).
• Returns: A sequence containing a single FinishTool instance.
• Raises: ValueError – If any parameters are provided.

class Observation

Bases: Schema, ABC

Base schema for output observation.

Properties

• ERROR_MESSAGE_HEADER: ClassVar[str] = ‘[An error occurred during execution.]n’
• content: list[TextContent | ImageContent]
• is_error: bool
• kind: str
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• text: str Extract all text content from the observation.
  • Returns: Concatenated text from all TextContent items in content.
• to_llm_content: Sequence[TextContent | ImageContent] Default content formatting for converting observation to LLM readable content. Subclasses can override to provide richer content (e.g., images, diffs).
• visualize: Text Return Rich Text representation of this observation. Subclasses can override for custom visualization; by default we show the same text that would be sent to the LLM.

Methods

classmethod from_text()

Utility to create an Observation from a simple text string.

• Parameters:
  • text – The text content to include in the observation.
  • is_error – Whether this observation represents an error. kwargs* – Additional fields for the observation subclass.
• Returns: An Observation instance with the text wrapped in a TextContent.

class ThinkTool

Bases: ToolDefinition[ThinkAction, ThinkObservation]

Tool for logging thoughts without making changes.

Properties

• kind: Literal[‘ThinkTool’]
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• name: ClassVar[str] = ‘think’

Methods

classmethod create()

Create ThinkTool instance.

• Parameters:
  • conv_state – Optional conversation state (not used by ThinkTool). params* – Additional parameters (none supported).
• Returns: A sequence containing a single ThinkTool instance.
• Raises: ValueError – If any parameters are provided.

class Tool

Bases: BaseModel

Defines a tool to be initialized for the agent.

This is only used in agent-sdk for type schema for server use.

Properties

• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• name: str
• params: dict[str, Any]

Methods

classmethod validate_name()

Validate that name is not empty.

classmethod validate_params()

Convert None params to empty dict.

class ToolAnnotations

Bases: BaseModel

Annotations to provide hints about the tool’s behavior.

Based on Model Context Protocol (MCP) spec: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838

Properties

• destructiveHint: bool
• idempotentHint: bool
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• openWorldHint: bool
• readOnlyHint: bool
• title: str | None

class ToolDefinition

Bases: DiscriminatedUnionMixin, ABC, Generic

Base class for all tool implementations.

This class serves as a base for the discriminated union of all tool types. All tools must inherit from this class and implement the .create() method for proper initialization with executors and parameters.

Features:

• Normalize input/output schemas (class or dict) into both model+schema.
• Validate inputs before execute.
• Coerce outputs only if an output model is defined; else return vanilla JSON.
• Export MCP tool description.

Examples

Simple tool with no parameters: : class FinishTool(ToolDefinition[FinishAction, FinishObservation]): : @classmethod def create(cls, conv_state=None, <br/>

**

<br/> params): <br/>

return [cls(name=”finish”, …, executor=FinishExecutor())]

Complex tool with initialization parameters: : class TerminalTool(ToolDefinition[TerminalAction, : TerminalObservation]): @classmethod def create(cls, conv_state, <br/>

**

<br/> params): <br/>

executor = TerminalExecutor( : working_dir=conv_state.workspace.working_dir, <br/>

**

<br/> params, <br/> ) return [cls(name=”terminal”, …, executor=executor)]

Properties

• action_type: type[Action]
• annotations: ToolAnnotations | None
• description: str
• executor: Annotated[ToolExecutor | None, SkipJsonSchema()]
• kind: str
• meta: dict[str, Any] | None
• model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
• name: ClassVar[str] = ”
• observation_type: type[Observation] | None
• title: str

Methods

action_from_arguments()

Create an action from parsed arguments.

This method can be overridden by subclasses to provide custom logic for creating actions from arguments (e.g., for MCP tools).

• Parameters: arguments – The parsed arguments from the tool call.
• Returns: The action instance created from the arguments.

as_executable()

Return this tool as an ExecutableTool, ensuring it has an executor.

This method eliminates the need for runtime None checks by guaranteeing that the returned tool has a non-None executor.

• Returns: This tool instance, typed as ExecutableTool.
• Raises: NotImplementedError – If the tool has no executor.

abstractmethod classmethod create()

Create a sequence of Tool instances.

This method must be implemented by all subclasses to provide custom initialization logic, typically initializing the executor with parameters from conv_state and other optional parameters.

• Parameters: args** – Variable positional arguments (typically conv_state as first arg). kwargs* – Optional parameters for tool initialization.
• Returns: A sequence of Tool instances. Even single tools are returned as a sequence to provide a consistent interface and eliminate union return types.

classmethod resolve_kind()

Resolve a kind string to its corresponding tool class.

• Parameters: kind – The name of the tool class to resolve
• Returns: The tool class corresponding to the kind
• Raises: ValueError – If the kind is unknown

set_executor()

Create a new Tool instance with the given executor.

to_mcp_tool()

Convert a Tool to an MCP tool definition.

Allow overriding input/output schemas (usually by subclasses).

• Parameters:
  • input_schema – Optionally override the input schema.
  • output_schema – Optionally override the output schema.

to_openai_tool()

Convert a Tool to an OpenAI tool.

• Parameters:
  • add_security_risk_prediction – Whether to add a security_risk field to the action schema for LLM to predict. This is useful for tools that may have safety risks, so the LLM can reason about the risk level before calling the tool.
  • action_type – Optionally override the action_type to use for the schema. This is useful for MCPTool to use a dynamically created action type based on the tool’s input schema.

to_responses_tool()

Convert a Tool to a Responses API function tool (LiteLLM typed).

For Responses API, function tools expect top-level keys: (JSON configuration object)

class ToolExecutor

Bases: ABC, Generic

Executor function type for a Tool.

Methods

close()

Close the executor and clean up resources.

Default implementation does nothing. Subclasses should override this method to perform cleanup (e.g., closing connections, terminating processes, etc.).