openhands.sdk.tool

​

class 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

​

Properties

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

​

Methods

​

init()

​

class FinishTool

​

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()

• 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

​

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()

• 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

​

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()

• 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

​

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()

​

classmethod validate_params()

​

class ToolAnnotations

​

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

• 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

**

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

**

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

Copy

Ask AI

**

<br/> params, <br/> ) return [cls(name=”bash”, …, 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()

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

​

as_executable()

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

​

abstractmethod classmethod create()

• 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()

• 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()

​

to_mcp_tool()

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

​

to_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()

​

class ToolExecutor

​

Methods

​

close()