API Reference

The toolfuse package provides an interface for defining Tools with actions and observations.

Tool

class toolfuse.Tool(wraps: Tool | None = None)

Bases: ABC

A Tool is an abstract base class that defines the interface for agent tools.

Agent tools are the primary means by which an agent interacts with its environment. They encapsulate actions that an agent can perform and observations that an agent can make to understand the state of the environment. This class provides the necessary infrastructure for registering and managing these actions and observations.

actions() → List[Action]

Returns a list of all registered actions that the agent can take.

Each action represents a potential operation that the agent can perform in its environment.

Returns:

A list of Action instances representing the available actions.

Return type:

List[Action]

add_action(method: Callable) → None

Adds a new action to the tool using only the method provided. Name, schema, and description are derived automatically.

Parameters:

method (Callable) – The callable method that implements the action.

add_actions(methods: List[Callable]) → None

Adds multiple actions to the tool using a list of methods. Each method’s name, schema, and description are derived automatically.

Parameters:

methods (List[Callable]) – A list of callable methods that implement actions.

add_observation(method: Callable) → None

Adds a new observation to the tool using only the method provided. Name, schema, and description are derived automatically.

Parameters:

method (Callable) – The callable method that implements the observation.

add_observations(methods: List[Callable]) → None

Adds multiple observations to the tool using a list of methods. Each method’s name, schema, and description are derived automatically.

Parameters:

methods (List[Callable]) – A list of callable methods that implement observations.

close() → None

A method that should be implemented by subclasses to handle the closing of the tool.

This method is intended to provide a way to release any resources or perform any cleanup necessary when the tool is no longer needed.

context() → str

LLM context fork the tool

Returns:

LLM context for the tool

Return type:

str

find_action(name: str) → Action | None

Searches for an action or observation by name and returns it if found.

This method checks both the actions and observations lists for a match.

Parameters:

name (str) – The name of the action or observation to find.

Returns:

The Action or Observation instance with the matching name, or None if not found.

Return type:

Optional[Action]

json_schema(actions_only: bool = False, exclude_names: List[str] = []) → List[Dict[str, Any]]

Returns a list of JSON schemas representing the tool’s actions and, optionally, observations, excluding any actions or observations with names listed in ‘exclude_names’.

Each schema provides a structured description of an action’s or observation’s interface, including its name, expected arguments, and other metadata.

Parameters:

• actions_only (bool, optional) – If True, only the action schemas will be returned. Defaults to False.

• exclude_names (List[str], optional) – A list of action or observation names to exclude from the schema output.

Returns:

A list of dictionaries, each representing the JSON schema of an action or observation not excluded.

Return type:

List[Dict[str, Any]]

merge(other: Tool) → None

Merges the actions and observations from another tool into this tool.

Parameters:

other (Tool) – The tool to merge into this tool.

observations() → List[Observation]

Returns a list of all registered observations that the agent can make.

Each observation represents a piece of information that the agent can gather from its environment to inform its decision-making process.

Returns:

A list of Observation instances representing the available observations.

Return type:

List[Observation]

observe(observation: Observation, *args, **kwargs) → Any

Executes an observation with the provided arguments and keyword arguments.

Parameters:

• observation (Observation) – The Observation instance representing the observation to run.

• *args – Variable length argument list for the observation.

• **kwargs – Arbitrary keyword arguments for the observation.

Returns:

The result of the observation execution, which can vary depending on the observation.

Return type:

Any

ref() → V1ToolRef

Tool reference

classmethod type() → str

Tool type

Returns:

Tool type

Return type:

str

use(action: Action, *args, **kwargs) → Any

Executes an action with the provided arguments and keyword arguments.

Parameters:

• action (Action) – The Action instance representing the action to perform.

• *args – Variable length argument list for the action.

• **kwargs – Arbitrary keyword arguments for the action.

Returns:

The result of the action execution, which can vary depending on the action.

Return type:

Any

Decorators

toolfuse.action(method: Callable) → Callable

A decorator that marks a method as an action within the Tool.

This decorator adds a special attribute to the method indicating that it should be treated as an action. Actions are potential operations that an agent can perform in its environment.

Parameters:

method (Callable) – The method to be marked as an action.

Returns:

The original method with the added ‘_is_action’ attribute.

Return type:

Callable

toolfuse.observation(method: Callable) → Callable

A decorator that marks a method as an observation within the Tool.

This decorator adds a special attribute to the method indicating that it should be treated as an observation. Observations are pieces of information that an agent can gather from its environment to inform its decision-making process.

Parameters:

method (Callable) – The method to be marked as an observation.

Returns:

The original method with the added ‘_is_observation’ attribute.

Return type:

Callable

Actions & Observations

class toolfuse.Action(name: str, method: Callable, schema: Dict, description: str)

Bases: object

Represents an action that an agent can perform in an environment.

This class is used to encapsulate information about an action, including its name, the method that implements the action, the schema that defines the structure of the action’s parameters, and a human-readable description of the action.

name

The name of the action. This is typically a unique identifier.

Type:

str

method

The callable method that is executed when the action is taken.

Type:

Callable

schema

A dictionary that defines the structure and types of the parameters that the action expects.

Type:

Dict

description

A human-readable description of what the action does and its purpose within the context of the agent’s environment.

Type:

str

__call__(*args, **kwargs) → Any

Allows the Action instance to be called like a function, which will in turn call the method associated with this action, passing through any arguments and keyword arguments.

class toolfuse.Observation(name: str, method: Callable, schema: Dict, description: str)

Bases: Action

Represents an observation that an agent can make in an environment.

This class is used to encapsulate information about an observation, including its name, the method that implements the observation, the schema that defines the structure of the observation’s data, and a human-readable description of the observation.

name

The name of the observation. This is typically a unique identifier.

Type:

str

method

The callable method that is executed to obtain the observation.

Type:

Callable

schema

A dictionary that defines the structure and types of the data that the observation returns.

Type:

Dict

description

A human-readable description of what the observation represents and its purpose within the context of the agent’s environment.

Type:

str

__call__(*args, **kwargs) → Any

Allows the Observation instance to be called like a function, which will in turn call the method associated with this observation, passing through any arguments and keyword arguments.