Module tool_invoker

ToolNotFoundException

Exception raised when a tool is not found in the list of available tools.

StringConversionError

Exception raised when the conversion of a tool result to a string fails.

ToolInvoker

Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects.

At initialization, the ToolInvoker component is provided with a list of available tools. At runtime, the component processes a list of ChatMessage object containing tool calls and invokes the corresponding tools. The results of the tool invocations are returned as a list of ChatMessage objects with tool role.

Usage example:

from haystack.dataclasses import ChatMessage, ToolCall, Tool
from haystack.components.tools import ToolInvoker

# Tool definition
def dummy_weather_function(city: str):
    return f"The weather in {city} is 20 degrees."

parameters = {"type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]}

tool = Tool(name="weather_tool",
            description="A tool to get the weather",
            function=dummy_weather_function,
            parameters=parameters)

# Usually, the ChatMessage with tool_calls is generated by a Language Model
# Here, we create it manually for demonstration purposes
tool_call = ToolCall(
    tool_name="weather_tool",
    arguments={"city": "Berlin"}
)
message = ChatMessage.from_assistant(tool_calls=[tool_call])

# ToolInvoker initialization and run
invoker = ToolInvoker(tools=[tool])
result = invoker.run(messages=[message])

print(result)

>>  {
>>      'tool_messages': [
>>          ChatMessage(
>>              _role=<ChatRole.TOOL: 'tool'>,
>>              _content=[
>>                  ToolCallResult(
>>                      result='"The weather in Berlin is 20 degrees."',
>>                      origin=ToolCall(
>>                          tool_name='weather_tool',
>>                          arguments={'city': 'Berlin'},
>>                          id=None
>>                      )
>>                  )
>>              ],
>>              _meta={}
>>          )
>>      ]
>>  }

ToolInvoker.__init__

def __init__(tools: List[Tool],
             raise_on_failure: bool = True,
             convert_result_to_json_string: bool = False)

Initialize the ToolInvoker component.

Arguments:

• tools: A list of tools that can be invoked.
• raise_on_failure: If True, the component will raise an exception in case of errors (tool not found, tool invocation errors, tool result conversion errors). If False, the component will return a ChatMessage object with error=True and a description of the error in result.
• convert_result_to_json_string: If True, the tool invocation result will be converted to a string using json.dumps. If False, the tool invocation result will be converted to a string using str.

Raises:

• ValueError: If no tools are provided or if duplicate tool names are found.

ToolInvoker.run

@component.output_types(tool_messages=List[ChatMessage])
def run(messages: List[ChatMessage]) -> Dict[str, Any]

Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available.

Arguments:

• messages: A list of ChatMessage objects.

Raises:

• ToolNotFoundException: If the tool is not found in the list of available tools and raise_on_failure is True.
• ToolInvocationError: If the tool invocation fails and raise_on_failure is True.
• StringConversionError: If the conversion of the tool result to a string fails and raise_on_failure is True.

Returns:

A dictionary with the key tool_messages containing a list of ChatMessage objects with tool role. Each ChatMessage objects wraps the result of a tool invocation.

ToolInvoker.to_dict

def to_dict() -> Dict[str, Any]

Serializes the component to a dictionary.

Returns:

Dictionary with serialized data.

ToolInvoker.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "ToolInvoker"

Deserializes the component from a dictionary.

Arguments:

• data: The dictionary to deserialize from.

Returns:

The deserialized component.