---
title: "Tool Components"
id: tool-components-api
description: "Components related to Tool Calling."
slug: "/tool-components-api"
---


## tool_invoker

### ToolInvokerError

Bases: <code>Exception</code>

Base exception class for ToolInvoker errors.

### ToolNotFoundException

Bases: <code>ToolInvokerError</code>

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

### StringConversionError

Bases: <code>ToolInvokerError</code>

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

### ResultConversionError

Bases: <code>ToolInvokerError</code>

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

### ToolOutputMergeError

Bases: <code>ToolInvokerError</code>

Exception raised when merging tool outputs into state fails.

#### from_exception

```python
from_exception(tool_name: str, error: Exception) -> ToolOutputMergeError
```

Create a ToolOutputMergeError from an exception.

### ToolInvoker

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:

```python
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:

````python
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)

#### __init__

```python
__init__(
    tools: ToolsType,
    raise_on_failure: bool = True,
    convert_result_to_json_string: bool = False,
    streaming_callback: StreamingCallbackT | None = None,
    *,
    enable_streaming_callback_passthrough: bool = False,
    max_workers: int = 4
)
````

Initialize the ToolInvoker component.

**Parameters:**

- **tools** (<code>ToolsType</code>) – A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools.
- **raise_on_failure** (<code>bool</code>) – 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** (<code>bool</code>) – 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`.
- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>bool</code>) – 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** (<code>int</code>) – The maximum number of workers to use in the thread pool executor.
  This also decides the maximum number of concurrent tool invocations.

**Raises:**

- <code>ValueError</code> – If no tools are provided or if duplicate tool names are found.

#### warm_up

```python
warm_up()
```

Warm up the tool invoker.

This will warm up the tools registered in the tool invoker.
This method is idempotent and will only warm up the tools once.

#### run

```python
run(
    messages: list[ChatMessage],
    state: State | None = None,
    streaming_callback: StreamingCallbackT | None = None,
    *,
    enable_streaming_callback_passthrough: bool | None = None,
    tools: ToolsType | None = None
) -> dict[str, Any]
```

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

**Parameters:**

- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
- **streaming_callback** (<code>StreamingCallbackT | None</code>) – 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** (<code>bool | None</code>) – 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.
- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
  If set, it will override the `tools` parameter provided during initialization.

**Returns:**

- <code>dict\[str, Any\]</code> – 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.

**Raises:**

- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.

#### run_async

```python
run_async(
    messages: list[ChatMessage],
    state: State | None = None,
    streaming_callback: StreamingCallbackT | None = None,
    *,
    enable_streaming_callback_passthrough: bool | None = None,
    tools: ToolsType | None = None
) -> dict[str, Any]
```

Asynchronously processes ChatMessage objects containing tool calls.

Multiple tool calls are performed concurrently.

**Parameters:**

- **messages** (<code>list\[ChatMessage\]</code>) – A list of ChatMessage objects.
- **state** (<code>State | None</code>) – The runtime state that should be used by the tools.
- **streaming_callback** (<code>StreamingCallbackT | None</code>) – An asynchronous 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** (<code>bool | None</code>) – 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.
- **tools** (<code>ToolsType | None</code>) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls.
  If set, it will override the `tools` parameter provided during initialization.

**Returns:**

- <code>dict\[str, Any\]</code> – 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.

**Raises:**

- <code>ToolNotFoundException</code> – If the tool is not found in the list of available tools and `raise_on_failure` is True.
- <code>ToolInvocationError</code> – If the tool invocation fails and `raise_on_failure` is True.
- <code>StringConversionError</code> – If the conversion of the tool result to a string fails and `raise_on_failure` is True.
- <code>ToolOutputMergeError</code> – If merging tool outputs into state fails and `raise_on_failure` is True.

#### to_dict

```python
to_dict() -> dict[str, Any]
```

Serializes the component to a dictionary.

**Returns:**

- <code>dict\[str, Any\]</code> – Dictionary with serialized data.

#### from_dict

```python
from_dict(data: dict[str, Any]) -> ToolInvoker
```

Deserializes the component from a dictionary.

**Parameters:**

- **data** (<code>dict\[str, Any\]</code>) – The dictionary to deserialize from.

**Returns:**

- <code>ToolInvoker</code> – The deserialized component.
