ToolInvoker

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

Basic Information

• Type: haystack.components.tools.tool_invoker.ToolInvoker

Inputs

Parameter	Type	Default	Description
messages	List[ChatMessage]		A list of ChatMessage objects.
state	Optional[State]	None	The runtime state that should be used by the tools.
streaming_callback	Optional[StreamingCallbackT]	None	A callback function that will be called to emit tool results. Note that the result is only emitted once it becomes available — it is not streamed incrementally in real time.
enable_streaming_callback_passthrough	Optional[bool]	None	If True, the streaming_callback will be passed to the tool invocation if the tool supports it. This allows tools to stream their results back to the client. Note that this requires the tool to have a streaming_callback parameter in its invoke method signature. If False, the streaming_callback will not be passed to the tool invocation. If None, the value from the constructor will be used.

Outputs

Parameter	Type	Default	Description
tool_messages	List[ChatMessage]		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.
state	State		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.

Overview

Work in Progress

Bear with us while we're working on adding pipeline examples and most common components connections.

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

Also handles reading/writing from a shared State. 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
from haystack.tools import 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={}
>>          )
>>      ]
>>  }

Usage example with a Toolset:

from haystack.dataclasses import ChatMessage, ToolCall
from haystack.tools import Tool, Toolset
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)

# Create a Toolset
toolset = Toolset([tool])

# 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 with Toolset
invoker = ToolInvoker(tools=toolset)
result = invoker.run(messages=[message])

print(result)


## Usage Example

```yaml
components:
  ToolInvoker:
    type: haystack.components.tools.tool_invoker.ToolInvoker
    init_parameters:

Parameters

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
tools	Union[List[Tool], Toolset]		A list of tools that can be invoked or a Toolset instance that can resolve tools.
raise_on_failure	bool	True	If True, the component raises 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	bool	False	If True, the tool invocation result is converted to a string using json.dumps. If False, the tool invocation result is converted to a string using str.
streaming_callback	Optional[StreamingCallbackT]	None	A callback function that will be called to emit tool results. Note that the result is only emitted once it becomes available — it is not streamed incrementally in real time.
enable_streaming_callback_passthrough	bool	False	If True, the streaming_callback will be passed to the tool invocation if the tool supports it. This allows tools to stream their results back to the client. Note that this requires the tool to have a streaming_callback parameter in its invoke method signature. If False, the streaming_callback will not be passed to the tool invocation.
max_workers	int	4	The maximum number of workers to use in the thread pool executor. This also decides the maximum number of concurrent tool invocations.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
messages	List[ChatMessage]		A list of ChatMessage objects.
state	Optional[State]	None	The runtime state that should be used by the tools.
streaming_callback	Optional[StreamingCallbackT]	None	A callback function that will be called to emit tool results. Note that the result is only emitted once it becomes available — it is not streamed incrementally in real time.
enable_streaming_callback_passthrough	Optional[bool]	None	If True, the streaming_callback will be passed to the tool invocation if the tool supports it. This allows tools to stream their results back to the client. Note that this requires the tool to have a streaming_callback parameter in its invoke method signature. If False, the streaming_callback will not be passed to the tool invocation. If None, the value from the constructor will be used.