openhands.sdk.tool

API reference for openhands.sdk.tool module

class FinishTool

Bases: ToolDefinition[FinishAction, FinishObservation]

Tool for signaling the completion of a task or conversation.

Methods

create() -> Sequence[Self]

source

Create FinishTool instance.

Parameters:

• conv_state ConversationState | None – Optional conversation state (not used by FinishTool).
• **params – Additional parameters (none supported).

Returns:

• Sequence[Self] A sequence containing a single FinishTool instance.

Raises:

• ValueError – If any parameters are provided.

  conv_state · ConversationState | None

  None

  params

  None

class ThinkTool

Bases: ToolDefinition[ThinkAction, ThinkObservation]

Tool for logging thoughts without making changes.

Methods

create() -> Sequence[Self]

source

Create ThinkTool instance.

Parameters:

• conv_state ConversationState | None – Optional conversation state (not used by ThinkTool).
• **params – Additional parameters (none supported).

Returns:

• Sequence[Self] A sequence containing a single ThinkTool instance.

Raises:

• ValueError – If any parameters are provided.

  conv_state · ConversationState | None

  None

  params

  None

list_registered_tools() -> list[str]

source

register_tool() -> None

source

name · str · required

None

factory · ToolDefinition | type[ToolDefinition] | Callable[..., Sequence[ToolDefinition]] · required

None

resolve_tool() -> Sequence[ToolDefinition]

source

tool_spec · Tool · required

None

conv_state · ConversationState · required

None

class Action

Bases: Schema, ABC

Base schema for input action.

Properties

• 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 Observation

Bases: Schema, ABC

Base schema for output observation.

Properties

• ERROR_MESSAGE_HEADER: str
• content: list[TextContent | ImageContent] Content returned from the tool as a list of TextContent/ImageContent objects. When there is an error, it should be written in this field.
• is_error: bool Whether the observation indicates an error
• 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

from_text() -> Self

source

Utility to create an Observation from a simple text string.

Parameters:

• text str – The text content to include in the observation.
• is_error bool – Whether this observation represents an error.
• **kwargs Any – Additional fields for the observation subclass.

Returns:

• Self An Observation instance with the text wrapped in a TextContent.

  text · str · required

  None

  is_error · bool

  None

  kwargs · Any

  None

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

• name: str Name of the tool class, e.g.,
• params: dict[str, Any] Parameters for the tool

Methods

validate_name() -> str

source

Validate that name is not empty.

v · str · required

None

validate_params() -> dict[str, Any]

source

Convert None params to empty dict.

v · dict[str, Any] | None · required

None

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

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

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

• model_config: ConfigDict
• title: str | None A human-readable title for the tool.
• readOnlyHint: bool If true, the tool does not modify its environment. Default: false
• destructiveHint: bool If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. (This property is meaningful only when readOnlyHint == false) Default: true
• idempotentHint: bool If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when readOnlyHint == false) Default: false
• openWorldHint: bool If true, this tool may interact with an

class ToolDefinition

Bases: DiscriminatedUnionMixin, ABC

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.

Example:

Simple tool with no parameters: class FinishTool(ToolDefinition[FinishAction, FinishObservation]): @classmethod def create(cls, conv_state=None, **params): return [cls(name=“finish”, …, executor=FinishExecutor())]

Complex tool with initialization parameters: class TerminalTool(ToolDefinition[TerminalAction, TerminalObservation]): @classmethod def create(cls, conv_state, **params): executor = TerminalExecutor( working_dir=conv_state.workspace.working_dir, **params, ) return [cls(name=“terminal”, …, executor=executor)]

Properties

• model_config: ConfigDict
• name: str
• description: str
• action_type: type[Action]
• observation_type: type[Observation] | None
• annotations: ToolAnnotations | None
• meta: dict[str, Any] | None
• executor: SkipJsonSchema[ToolExecutor | None]
• title: str

Methods

abstractmethod create() -> Sequence[Self]

source

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:

• Sequence[Self] A sequence of Tool instances. Even single tools are returned as a sequence

• Sequence[Self] to provide a consistent interface and eliminate union return types.

  args

  None

  kwargs

  None

set_executor() -> Self

source

Create a new Tool instance with the given executor.

executor · ToolExecutor · required

None

as_executable() -> ExecutableTool

source

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:

• ExecutableTool This tool instance, typed as ExecutableTool.

Raises:

• NotImplementedError – If the tool has no executor.

action_from_arguments() -> Action

source

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 dict[str, Any] – The parsed arguments from the tool call.

Returns:

• Action The action instance created from the arguments.

  arguments · dict[str, Any] · required

  None

to_mcp_tool() -> dict[str, Any]

source

Convert a Tool to an MCP tool definition.

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

Parameters:

• input_schema dict[str, Any] | None – Optionally override the input schema.

• output_schema dict[str, Any] | None – Optionally override the output schema.

  input_schema · dict[str, Any] | None

  None

  output_schema · dict[str, Any] | None

  None

to_openai_tool() -> ChatCompletionToolParam

source

Convert a Tool to an OpenAI tool.

Parameters:

• add_security_risk_prediction bool – 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 type[Schema] | None – 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.

  add_security_risk_prediction · bool

  None

  action_type · type[Schema] | None

  None

to_responses_tool() -> FunctionToolParam

source

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

For Responses API, function tools expect top-level keys: { “type”: “function”, “name”: …, “description”: …, “parameters”: … }

Parameters:

• add_security_risk_prediction bool – Whether to add a security_risk field

• action_type type[Schema] | None – Optional override for the action type

  add_security_risk_prediction · bool

  None

  action_type · type[Schema] | None

  None

resolve_kind() -> type

source

Resolve a kind string to its corresponding tool class.

Parameters:

• kind str – The name of the tool class to resolve

Returns:

• type The tool class corresponding to the kind

Raises:

• ValueError – If the kind is unknown

  kind · str · required

  None

class ToolExecutor

Bases: ABC

Executor function type for a Tool.

Methods

close() -> None

source

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